入力データの形式と構造

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

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

前提条件

入力データを、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 は、次のインデックス バージョンから削除されます。
• 通常のデータファイルにあるレコードは次のバージョンに含まれ、古いインデックスのバージョンにある値を上書きします。

JSON の例を次に示します。

{"id": "1", "embedding": [1,1,1]}
{"id": "2", "embedding": [2,2,2]}

有効な入力データファイルの編成の例を次に示します。

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 フィールドを含める必要があります。
• 各レコードには、特徴ベクトルを表す N 浮動小数点数の配列である embedding フィールドが含まれている必要があります。ここで、N は、インデックスが作成されたときに構成された特徴ベクトルの次元です。
• オプションの 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 ファイルを使用します。

• 次のスキーマを遵守するレコードを作成します。

  {
    "type": "record",
    "name": "FeatureVector",
    "fields": [
      {
        "name": "id",
        "type": "string"
      },
      {
        "name": "embedding",
        "type": {
          "type": "array",
          "items": "float"
        }
      },
      {
        "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

• UTF-8 を使用して CSV ファイルをエンコードします。
• CSV の各行に含まれるレコードは 1 つだけです。
• 各行の最初の値はベクトル ID でなければなりません。これは、有効な UTF-8 文字列である必要があります。
• ID に続く次の N 値は特徴ベクトルを表します。ここで N はインデックスの作成時に構成された特徴ベクトルの次元です。
• 特徴ベクトル値は、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
  }
  

次のステップ

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