输入数据格式和结构

如需构建新索引或更新现有索引，请按照以下部分所述的格式和结构向 Vector Search 提供向量。

输入数据存储和文件组织

前提条件

将输入数据存储在 Google Cloud 项目的 Cloud Storage 存储桶中。

输入数据文件应按以下方式组织：

  • 每批输入数据文件应位于单个 Cloud Storage 目录下。
  • 数据文件应直接放在 batch_root 下，并采用以下后缀进行命名：.csv、.json 和 .avro。
  • 批处理根目录中的对象（文件）数量上限为 5,000 个。
  • 每个数据文件都被解释为一组记录。记录的格式由文件名的后缀决定，相关文档介绍了这些格式要求。请参阅数据文件格式。
  • 每个记录都应具有 id、特征向量以及 Vertex AI Feature Store 支持的可选字段，例如 restricts 和 crowding。
  • 可能存在名为 delete 的子目录。每个直接位于 batch_root/delete 下的文件都被视为包含 id 记录的文本文件，并且每个 id 占一行。
  • 不允许使用所有其他子目录。

输入数据处理

  • 来自所有数据文件的所有记录（包括 delete 下的记录）组成一个输入批次。
  • 数据文件中记录的相对排序无关紧要。
  • 一个 ID 在一个批次中只应出现一次。如果存在具有相同 ID 的重复记录，将显示为一个向量计数。
  • 一个 ID 不能同时出现在常规数据文件和删除数据文件中。
  • delete 目录下的数据文件中的所有 ID 都会使其从下一个索引版本中移除。
  • 常规数据文件中的记录包含在下一个版本中，并覆盖旧索引版本中的值。

以下是密集型、稀疏型和混合型嵌入的示例：

  • 密集嵌入：

    {"id": "1", "embedding": [1,1,1]}
{"id": "2", "embedding": [2,2,2]}

  • 稀疏嵌入（公开预览版）：

    {"id": "3", "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1, 4]}}
{"id": "4", "sparse_embedding": {"values": [-0.4, 0.2, -1.3], "dimensions": [10, 20, 20]}}

  • 混合嵌入（公开预览版）：

    {"id": "5", "embedding": [5, 5, -5], "sparse_embedding": {"values": [0.1], "dimensions": [500]}}
{"id": "6", "embedding": [6, 7, -8.1], "sparse_embedding": {"values": [0.1, -0.2], "dimensions": [40, 901]}}

下面是一个有效输入数据文件组织的示例：

batch_root/
  feature_file_1.csv
  feature_file_2.csv
  delete/
    delete_file.txt

feature_file_1.csv 和 feature_file_2.csv 文件包含 CSV 格式的记录。delete_file.txt 文件包含要从下一个索引版本中删除的记录 ID 列表。

数据文件格式

JSON

  • 使用 UTF-8 对 JSON 文件编码。
  • JSON 文件的每一行都会被解释为一个单独的 JSON 对象。
  • 每个记录都必须包含一个 id 字段，以指定向量的 ID。
  • 每个记录都必须包含 embedding 或 sparse_embedding 中的至少一个。
  • embedding 字段是表示特征向量的 N 浮点数的数组，其中 N 是创建索引时配置的特征向量的维度。此字段只能用于密集嵌入。
    • 在创建索引时指定的 configs.dimensions 的长度必须与 embeddings 相同。configs.dimensions 仅适用于 embedding，不适用于 sparse_embedding。
  • sparse_embedding 字段是一个包含 values 和 dimensions 字段的对象。values 字段是表示特征向量的浮点数列表，dimensions 字段是表示相应值所在维度的整数列表。例如，看起来像 [0,0.1,0,0,0.2] 的稀疏嵌入可以表示为 "sparse_embedding": {"values": [0.1, 0.2], "dimensions": [1,4]}。此字段仅可用于稀疏嵌入。
    • sparse_embedding.values 的长度必须与 sparse_embedding.dimensions 的长度相同。它们的长度不必与 configs.dimensions 相同，后者是在索引创建时指定的，不适用于 sparse_embedding。
  • 可以包含可选的 restricts 字段，用于指定 restricts 中的 TokenNamespace 对象数组。对于每个对象：
    • 指定 namespace 字段，即 TokenNamespace.namespace。
    • 可选的 allow 字段可以设置为字符串数组，即 TokenNamespace.string_tokens 列表。
    • 可选的 deny 字段可以设置为字符串数组，即 TokenNamespace.string_blacklist_tokens 列表。
    • crowding_tag 字段（如果存在）的值必须是一个字符串。
  • 可以包含可选的 numeric_restricts 字段，用于指定 NumericRestrictNamespace 数组。对于每个对象：
    • 指定 namespace 字段，即 NumericRestrictNamespace.namespace。
    • 值字段 value_int、value_float 和 value_double 之一。
    • 该字段不得包含名为 op 的字段。此字段仅适用于查询。

Avro

  • 使用有效的 Avro 文件。
  • 如需表示仅包含稀疏数据点的数据，请在 sparse_embedding 字段中提供稀疏嵌入，并在 embedding 字段中输入空白列表。

  • 创建符合以下架构的记录：

    {
  "type": "record",
  "name": "FeatureVector",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "embedding",
      "type": {
        "type": "array",
        "items": "float"
      }
    },
    {
      "name": "sparse_embedding",
      "type": [
        "null",
        {
          "type": "record",
          "name": "sparse_embedding",
          "fields": [
            {
              "name": "values",
              "type": {
                "type": "array",
                "items": "float"
              }
            },
            {
              "name": "dimensions",
              "type": {
                "type": "array",
                "items": "long"
              }
            }
          ]
        }
      ]
    },
    {
      "name": "restricts",
      "type": [
        "null",
        {
          "type": "array",
          "items": {
            "type": "record",
            "name": "Restrict",
            "fields": [
              {
                "name": "namespace",
                "type": "string"
              },
              {
                "name": "allow",
                "type": [
                  "null",
                  {
                    "type": "array",
                    "items": "string"
                  }
                ]
              },
              {
                "name": "deny",
                "type": [
                  "null",
                  {
                    "type": "array",
                    "items": "string"
                  }
                ]
              }
            ]
          }
        }
      ]
    },
    {
      "name": "numeric_restricts",
      "type": [
        "null",
        {
          "type": "array",
          "items": {
            "name": "NumericRestrict",
            "type": "record",
            "fields": [
              {
                "name": "namespace",
                "type": "string"
              },
              {
                "name": "value_int",
                "type": [ "null", "int" ],
                "default": null
              },
              {
                "name": "value_float",
                "type": [ "null", "float" ],
                "default": null
              },
              {
                "name": "value_double",
                "type": [ "null", "double" ],
                "default": null
              }
            ]
          }
        }
      ],
      "default": null
    },
    {
      "name": "crowding_tag",
      "type": [
        "null",
        "string"
      ]
    }
  ]
}

CSV

  • 格式：ID,N feature vector values,Any number of dimension:value sparse values,name=value lists
  • 使用 UTF-8 对 CSV 文件编码。
  • CSV 中的每一行必须只包含一条记录。
  • 每行中的第一个值必须是向量 ID，它必须是有效的 UTF-8 字符串。
  • 在 ID 之后，必须至少指定一个密集嵌入或稀疏嵌入。
  • 对于密集嵌入，接下来的 N 值表示特征向量，其中 N 是在创建索引时配置的特征向量的维度。
  • 对于稀疏嵌入，可以指定任意数量的 dimension:value，其中 value 会解析为浮点数，dimension 会解析为 long。
  • 对于同时具有稠密嵌入和稀疏嵌入的混合嵌入，必须先指定稠密嵌入，然后再指定稀疏嵌入。
  • 特征向量值必须是 Java 语言规范中定义的浮点字面量。
  • 其他值可以采用 name=value 格式。
  • 名称 crowding_tag 会被解释为拥挤标记，并且只能在记录中出现一次。

  • 所有其他 name=value 对都会被解释为词元命名空间限制。如果命名空间中有多个值，则同一名称可以重复。

    例如，color=red,color=blue 表示此 TokenNamespace：

    {
  "namespace": "color"
  "string_tokens": ["red", "blue"]
}

  • 如果值以 ! 开头，则字符串的其余部分被解释为排除的值。

    例如，color=!red 表示此 TokenNamespace：

    {
  "namespace": "color"
  "string_blacklist_tokens": ["red"]
}

  • 带有数字类型后缀的 #name=numericValue 对会被解释为数字命名空间限制。数字类型后缀为 i（表示 int）、f（表示浮点）和 d（表示双精度）。同一名称不应重复，因为每个命名空间应该有一个关联的值。

    例如，#size=3i 表示此 NumericRestrictNamespace：

    {
  "namespace": "size"
  "value_int": 3
}

    #ratio=0.1f 表示此 NumericRestrictNamespace：

    {
  "namespace": "ratio"
  "value_float": 0.1
}

    #weight=0.3d 表示此 NumericRestriction：

    {
  "namespace": "weight"
  "value_double": 0.3
}

  • 以下示例数据点具有 id: "6"、embedding: [7, -8.1]、sparse_embedding: {values: [0.1, -0.2, 0.5], dimensions: [40, 901, 1111]}}、拥挤标记 test、词元许可名单 color: red, blue、词元拒绝名单 color: purple，以及数值限制 ratio 和浮点 0.1：

    6,7,-8.1,40:0.1,901:-0.2,1111:0.5,crowding_tag=test,color=red,color=blue,color=!purple,ratio=0.1f

后续步骤