輸入資料格式和結構

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

必要條件

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

輸入資料檔案應按照下列方式整理：

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

輸入資料處理

  • 所有資料檔案 (包括 delete 下的檔案) 的所有記錄，都包含單一輸入批次。
  • 資料檔案中記錄的相對順序並不重要。
  • 單一 ID 在批次中只能出現一次。如果重複的向量具有相同 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 欄位，指定 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 (適用於 float) 和 d (適用於 double)。同一名稱不應重複，因為每個命名空間應只關聯一個值。

    舉例來說，#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，以及浮點數 0.1 的數值限制 ratio：

    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

後續步驟