新しいインデックスの作成や既存のインデックスの更新を行うには、以下のセクションで説明する形式と構造のベクトルをベクトル検索に提供します。
入力データ ストレージとファイル構造
前提条件
入力データを、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 }
次のステップ
- インデックスの作成と管理の方法を学ぶ。