输入数据格式和结构

如需构建新索引或更新现有索引，请按照以下部分所述的格式和结构向 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
  

后续步骤

• 了解如何创建和管理索引