メタデータを使用するベクトル検索エンベディング

このガイドでは、ベクトル エンベディングの省略可能なメタデータについて説明します。ベクトル検索では、各エンベディングのメタデータを定義できます。

メタデータは、フィルタリングできない任意の情報で、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 はサポートされていません。
  • upsertDatapoints API の使用:
    • API リクエスト ペイロードでデータポイント オブジェクト（embedding_metadata を含む）を渡します。

クエリでの 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"}'