入力データの形式と構造

新しいインデックスの作成や既存のインデックスの更新を行うには、以下のセクションで説明する形式と構造のベクトルをベクトル検索に提供します。

入力データ ストレージとファイル構造

前提条件

入力データを、Google Cloud プロジェクトの Cloud Storage バケットに保存します。

入力データファイルは、次のように編成する必要があります。

• 入力データファイルの各バッチは、単一の Cloud Storage ディレクトリに配置します。
• データファイルは batch_root の直下に配置し、ファイル名に .csv、.json、.avro の接尾辞を付けます。
• バッチ ルート ディレクトリに格納できるオブジェクト（ファイル）数は 5,000 件までです。
• 各データファイルは一連のレコードとして解釈されます。レコードの形式は、ファイル名の接尾辞によって決まります。それらの形式の要件については、データファイルの形式をご覧ください。
• 各レコードには、id、特徴ベクトル、Vertex AI Feature Store でサポートされているオプション フィールド（制限やクラウディングなど）を含めます。
• delete という名前のサブディレクトリが存在することがあります。batch_root / delete の直下にある各ファイルは、各行に 1 つの id がある、id レコードのテキスト ファイルとして扱われます。
• その他のディレクトリとファイルはすべて無視されます。

入力データ処理

• すべてのデータファイルのすべてのレコード（delete にあるものを含む）は、入力の単一バッチで構成されます。
• データファイル内のレコードの相対的な順序は重要ではありません。
• 1 つの ID は、1 つのバッチ内に 1 個だけ存在できます。同じ ID の重複がある場合は、1 つのベクトル数として表示されます。
• 通常のデータファイルと削除データファイルの両方に同じ 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 のいずれかを少なくとも 1 つ含める必要があります。
• 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 フィールドを追加して、制限内で TokenNamespace オブジェクトの配列を指定できます。オブジェクトごとに、以下を行います。
  • TokenNamespace.namespace の namespace フィールドを指定します。
  • オプションの allow フィールドには、TokenNamespace.string_tokens のリストである文字列の配列を設定できます。
  • オプションの deny フィールドには、TokenNamespace.string_blacklist_tokens のリストである文字列の配列を設定できます。
  • crowding_tag フィールドの値（存在する場合）は文字列にする必要があります。
• オプションの numeric_restricts フィールドを含めて、NumericRestrictNamespace の配列を指定できます。オブジェクトごとに、以下を行います。
  • NumericRestrictNamespace.namespace の 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 の各行に含まれるレコードは 1 つだけです。
• 各行の最初の値はベクトル ID でなければなりません。これは、有効な UTF-8 文字列である必要があります。
• ID の後に、密エンベディングまたはスパース エンベディングの少なくとも 1 つを指定する必要があります。
• 密エンベディングの場合、次の N 値は特徴ベクトルを表します。ここで、N はインデックスの作成時に構成された特徴ベクトルの次元です。
• スパース エンベディングの場合は、任意の数の dimension:value を指定できます。ここで、value は浮動小数点数として解析され、dimension は long として解析されます。
• 密エンベディングとスパース エンベディングの両方を含むハイブリッド エンベディングの場合、スパース エンベディングの前に密エンベディングを指定する必要があります。
• 特徴ベクトル値は、Java 言語仕様で定義されている浮動小数点リテラルにする必要があります。
• 追加の値は name=value の形式で指定できます。
• crowding_tag という名前はクラウディング タグとして解釈され、レコード内で 1 回だけ使用できます。

• 他のすべての 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 です。名前空間ごとに 1 つの値を関連付ける必要があるため、同じ名前を繰り返さないでください。

  たとえば、#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
  

次のステップ

• インデックスの作成と管理の方法を学ぶ。