輸入資料格式和結構

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

必要條件

將輸入資料儲存在專案的 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
  

後續步驟

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