메타데이터가 포함된 벡터 검색 임베딩

이 가이드에서는 벡터 임베딩의 선택적 메타데이터에 대한 정보를 제공합니다. 벡터 검색을 사용하면 각 임베딩의 메타데이터를 정의할 수 있습니다.

메타데이터는 필터링할 수 없는 임의 정보로, 벡터 검색에서 각 임베딩에 대해 저장할 수 있습니다. 이를 통해 다음과 같은 유용한 컨텍스트가 포함된 임베딩을 제공할 수 있습니다.

  • 제품 세부정보(예: 이름, 가격, 이미지 URL)

  • 텍스트 임베딩의 설명, 스니펫, 날짜, 저작자입니다.

  • 사용자 임베딩의 사용자 정보입니다.

  • 장소 임베딩의 좌표입니다.

주요 특징 및 장점

메타데이터 사용의 기능과 이점은 다음과 같습니다.

  • 결과와 함께 제공되는 컨텍스트: 검색 결과에 직접 정보가 제공되므로 별도로 조회할 필요가 없으며 지연 시간이 줄어듭니다.

  • 유연한 구조: 메타데이터는 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 형식을 사용합니다. 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와 update_mask을 사용하여 embedding_metadata 값을 사용하여 메타데이터를 업데이트합니다. 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"}'