含中繼資料的 Vector Search 嵌入

本指南提供向量嵌入的選用中繼資料相關資訊。 Vector Search 可讓您為每個嵌入項目定義中繼資料。

中繼資料是不可篩選的任意資訊，Vector Search 可為每個嵌入儲存這類資訊。這類資訊可提供實用的背景資訊，例如：

  • 產品詳細資料，例如名稱、價格和圖片網址。

  • 文字嵌入的說明、摘要、日期和作者。

  • 使用者嵌入的使用者資訊。

  • 地點嵌入的座標。

主要功能與優點

使用中繼資料的優點包括：

  • 提供搜尋結果的背景資訊：資訊可直接顯示在搜尋結果中，不必另外查詢，減少延遲。

  • 彈性結構：中繼資料以 JSON 物件的形式提供，因此中繼資料可定義為複雜的巢狀資料。

  • 無法篩選：向量嵌入中繼資料用於儲存及擷取無法篩選的資訊，與 restricts 和 numeric_restricts 不同。

  • 有效率的更新：您可以使用 update_mask 欄位指定 API「只」更新中繼資料，避免重新提交嵌入向量。

  • 分離式資訊：不可篩選的資訊可以與可篩選的屬性 (例如 restricts) 分開。

  • 簡化開發流程：搜尋回覆會包含與向量嵌入相關聯的中繼資料，同時減少顯示複合式搜尋結果和執行以內容為準的後續處理等功能所需的複雜度。

資料格式

選用的 embedding_metadata 欄位會保留 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 格式。 系統不支援以 CSV 格式匯入 embedding_metadata。
  • 使用 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，避免重新提交限制和嵌入欄位。

以下範例示範如何定義及更新中繼資料，以建立指定目標的 IndexDatapoint、指定 update_mask，以及呼叫 upsertDatapoints。

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"}'