このガイドでは、ベクトル エンベディングの省略可能なメタデータについて説明します。ベクトル検索では、各エンベディングのメタデータを定義できます。
メタデータは、フィルタリングできない任意の情報で、Vector Search は各エンベディングにこの情報を保存できます。これにより、次のような有用なコンテキストを含むエンベディングを取得できます。
商品名、価格、画像 URL などの商品詳細。
テキスト エンベディングの説明、スニペット、日付、作成者。
ユーザー エンベディングのユーザー情報。
場所エンベディングの座標。
主な機能と利点
メタデータの主な機能とメリットは次のとおりです。
結果付きのコンテキスト: 検索結果に直接情報を提供できるため、個別のルックアップが不要になり、レイテンシが短縮されます。
柔軟な構造: メタデータは JSON オブジェクトとして提供されるため、複雑なネストされたデータとしてメタデータを定義できます。
フィルタリング不可: ベクトル エンベディング メタデータは、
restricts
やnumeric_restricts
とは異なるフィルタリング不可の情報を保存して取得するためのものです。効率的な更新:
update_mask
フィールドを使用すると、API がメタデータのみを更新するように指定し、エンベディング ベクトルの再送信を回避できます。分離された情報: フィルタリングできない情報を、
restricts
などのフィルタリング可能な属性から分離できます。開発の効率化: 検索レスポンスにはベクトル エンベディングに関連付けられたメタデータが含まれており、リッチ検索結果の表示やコンテキスト ベースの後処理などの機能に伴う複雑さが軽減されます。
データ形式
オプションの embedding_metadata
フィールドには、フィルタリング不可のリッチ情報を Vector Search のエンベディングに柔軟に関連付ける JSON オブジェクトが格納されます。これにより、結果とともにコンテキストが返されるため、アプリケーションを効率化できます。また、upsertDatapoints
API の update_mask
を使用して、メタデータのみを効率的に更新できます。
データポイントの構造の例:
{
"id": "movie_001",
"embedding": [0.1, 0.2, ..., 0.3],
"sparse_embedding": {
"values": [-0.4, 0.2, -1.3],
"dimensions": [10, 20, 30]
},
"numeric_restricts": [{'namespace': 'year', 'value_int': 2022}],
"restricts": [{'namespace': 'genre', 'allow': ['action', 'comedy']}],
# --- New embedding_metadata field ---
"embedding_metadata": {
"title": "Ballet Train",
"runtime": {
"hours": 2,
"minutes": 6
},
"review_info": {
"review": "This movie is fun and...",
"rotten_potatoes_rating": 76
}
}
# ------------------------------------
},
# ... other data points
embedding_metadata
を使用したデータの取り込み
データポイントを追加する際に、次のいずれかの操作が行われた場合に embedding_metadata
を含めることができます。
- ファイルのアップロード(Cloud Storage):
- JSON または AVRO 形式を使用します。
embedding_metadata
では CSV はサポートされていません。
- JSON または AVRO 形式を使用します。
upsertDatapoints
API の使用:- API リクエスト ペイロードでデータポイント オブジェクト(
embedding_metadata
を含む)を渡します。
- API リクエスト ペイロードでデータポイント オブジェクト(
クエリでの embedding_metadata
の取得
findNeighbors
API を使用して標準の最近傍検索を行う場合、returnFullDatapoint
が True
に設定されていると、各近傍の embedding_metadata
フィールドがレスポンスに自動的に含まれます。
curl
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors" \
-d '{deployedIndexId:"${DEPLOYED_INDEX_ID}", "queries":[{datapoint:{"featureVector":"<FEATURE_VECTOR>"}}], returnFullDatapoint:true}'
embedding_metadata
の更新
upsertDatapoints
API と値 embedding_metadata
を使用する update_mask
を使用して、メタデータを更新します。update_mask
フィールドには、追加のマスク値が含まれることもあります。フィールド マスクの使用については、エンベディング メタデータを更新するをご覧ください。
update_mask
フィールドを使用すると、embedding_metadata
のみが更新されるため、制限フィールドとエンベディング フィールドの再送信を回避できます。
次の例は、update_mask
を指定して upsertDatapoints
を呼び出し、メタデータの定義と更新、ターゲットに設定された IndexDatapoint
の作成を行う方法を示しています。
curl
curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints:[
{
datapoint_id: "'${DATAPOINT_ID_1}'",
feature_vector: [...],
embedding_metadata:{"title": "updated title", "rating": 4.5, "tags": ["updated", "reviewed"]
}, update_mask: "embedding_metadata"}'