輸入資料格式和結構

如要建立新的索引或更新現有索引，請按照下列各節所述的格式和結構，為向量搜尋提供向量。

輸入資料儲存和檔案組織

修課條件

將輸入資料儲存在 Cloud Storage 值區中，並儲存在 Google Cloud 專案中。

輸入資料檔案應按照以下方式排序：

• 每批輸入資料檔案都應位於單一 Cloud Storage 目錄中。
• 資料檔案應直接放在 batch_root 下方，並使用下列後置字串命名：.csv、.json 和 .avro。
• 批次根目錄中的物件 (檔案) 上限為 5000 個。
• 系統會將每個資料檔案解讀為一組記錄。記錄的格式由檔案名稱的後置字元決定，以下將說明這些格式規定。請參閱「資料檔案格式」。
• 每個記錄都應包含 id、特徵向量，以及 Vertex AI 特徵儲存庫支援的選用欄位，例如限制和擁擠。
• 可能會有名為 delete 的子目錄。batch_root/delete 下方的每個檔案都會視為 id 記錄的文字檔案，每行一個 id。
• 其他所有子目錄皆不允許。
• 系統不支援轉碼 gzip 壓縮檔案做為輸入資料。

輸入資料處理

• 所有資料檔案 (包括 delete 底下的檔案) 的所有記錄都包含單一批輸入資料。
• 資料檔案中記錄的相對順序並不重要。
• 單一 ID 應只在批次中出現一次。如果有重複的 ID，系統會以一個向量計數顯示。
• 同一個 ID 無法同時出現在一般資料檔案和刪除資料檔案中。
• 刪除資料檔案中的所有 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 相同，因為 configs.dimensions 會在索引建立時指定，且不適用於 sparse_embedding。
• 您可以加入選用的 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 與數值類型後置詞配對，會解讀為數值命名空間限制。數字類型後置字為 int 的 i、float 的 f，以及 double 的 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
  

後續步驟

• 瞭解如何建立及管理索引