메타데이터를 포함한 벡터 검색 임베딩

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

메타데이터는 벡터 검색이 각 임베딩마다 저장할 수 있는 필터링 불가능한 임의의 정보입니다. 이는 다음과 같은 유용한 컨텍스트를 임베딩에 제공할 수 있습니다.

  • 제품 이름, 가격, 이미지 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 형식을 사용하세요. 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와 update_mask를 사용해 embedding_metadata 값을 업데이트합니다. update_mask 필드에는 다른 마스크 값이 추가될 수도 있습니다. 필드 마스크 사용 예시는 임베딩 메타데이터 업데이트를 참조하세요.

update_mask 필드는 embedding_metadata만 업데이트하도록 보장하여 restrict 및 embedding 필드를 다시 제출할 필요가 없게 합니다.

다음 예시는 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"}'