활성 색인 업데이트 및 재빌드

개요

대규모 검색어를 사용할 때는 가장 정확한 정보를 얻기 위해 항상 색인을 업데이트하는 것이 중요합니다. 이제 일괄 일정을 통해 데이터 포인트를 삽입 및 삭제할 수 있는 일괄 업데이트나 몇 초 만에 색인을 업데이트하고 쿼리할 수 있는 스트리밍 업데이트를 사용하여 벡터 검색 색인을 업데이트할 수 있습니다.

또한 UpdateIndex를 사용하여 display_name, description, labels와 같은 중요한 메타데이터 필드를 업데이트할 수 있습니다. 또한 결과 분류 또는 사전 색인 쿼리 필터링을 돕기 위해 색인에 선택적인 태그를 추가할 수도 있습니다.

일괄 색인 업데이트

기존 Index의 콘텐츠를 업데이트하려면 IndexService.UpdateIndex 메서드를 사용합니다.

기존 Index의 기존 콘텐츠를 바꾸려면 다음 안내를 따르세요.

• Index.metadata.contentsDeltaUri를 업데이트할 벡터가 포함된 Cloud Storage URI로 설정합니다.
• isCompleteOverwrite를 true로 설정합니다.

IndexService.UpdateIndex를 호출할 때 contentsDeltaUri 필드를 설정하면 다른 색인 필드(예: displayName, description 또는 userLabels)를 동일한 호출의 일부로 업데이트할 수 없습니다.

gcloud ai indexes update INDEX_ID \
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
    --region=LOCATION \
    --project=PROJECT_ID

gcloud ai indexes update INDEX_ID `
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE `
    --region=LOCATION `
    --project=PROJECT_ID

gcloud ai indexes update INDEX_ID ^
    --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^
    --region=LOCATION ^
    --project=PROJECT_ID

PATCH http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID

{
 "metadata": {
   "contentsDeltaUri": "INPUT_DIR",
   "isCompleteOverwrite": true
 }
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "http://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID" | Select-Object -Expand Content

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-01-12T23:56:14.480948Z",
     "updateTime": "2022-01-12T23:56:14.480948Z"
   }
 }
}

Index에 연결된 배포가 있는 경우(Index.deployed_indexes 필드 참조) 원래 Index에 특정 변경사항이 수행되면 이러한 변경사항이 반영되도록 백그라운드에서 DeployedIndex가 비동기식으로 자동 업데이트됩니다.

변경사항이 전파되었는지 확인하려면 업데이트 색인 작업 완료 시간과 DeployedIndex.index_sync_time을 비교하세요.

스트리밍 색인 업데이트

스트리밍 업데이트를 사용하여 몇 초 내에 색인을 업데이트하고 쿼리할 수 있습니다. 현재는 기존 일괄 업데이트 색인으로 스트리밍 업데이트를 사용할 수 없으며, 새 색인을 만들어야 합니다. 자세한 내용은 스트리밍 업데이트를 위한 색인 만들기를 참조하세요.

스트리밍 업데이트에 사용되는 1GB당 $0.45가 청구됩니다. 가격 책정에 대한 자세한 내용은 Vertex AI 가격 책정 페이지를 참조하세요. 스트리밍 업데이트는 메모리에서 배포된 색인에 직접 적용되고 짧은 지연 후 쿼리 결과에 반영됩니다.

데이터 포인트 업서트

이 샘플을 사용하여 데이터 포인트를 업서트하는 방법을 알아보세요. upsert-datapoints는 배열 형식의 JSON만 허용합니다.

def stream_update_vector_search_index(
    project: str, location: str, index_name: str, datapoints: Sequence[dict]
) -> None:
    """Stream update an existing vector search index

    Args:
      project (str): Required. The Project ID
      location (str): Required. The region name, e.g. "us-central1"
      index_name (str): Required. The index to update. A fully-qualified index
        resource name or a index ID.  Example:
        "projects/123/locations/us-central1/indexes/my_index_id" or
        "my_index_id".
      datapoints: Sequence[dict]: Required. The datapoints to be updated. The dict
        element should be of the IndexDatapoint type.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index instance from an existing index with stream_update
    # enabled
    my_index = aiplatform.MatchingEngineIndex(index_name=index_name)

    # Upsert the datapoints to the index
    my_index.upsert_datapoints(datapoints=datapoints)

  
  DATAPOINT_ID_1=
  DATAPOINT_ID_2=
  curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" http://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
  -d '{datapoints: [{datapoint_id: "'${DATAPOINT_ID_1}'", feature_vector: [...]},
  {datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...]}]}'
  
  

처리량 할당량 한도는 업서트에 포함된 데이터 양과 관련이 있습니다. 데이터 포인트 ID가 색인에 있으면 임베딩이 업데이트되고, 그렇지 않으면 새 임베딩이 추가됩니다.

동적 메타데이터 업데이트

스트리밍 제한 또는 숫자 제한을 업데이트해야 하는 이유는 다양합니다. 예를 들어 빠르게 이동하는 대용량 데이터를 처리할 때 특정 데이터 스트림의 우선순위를 지정해야 할 수 있습니다. 제한 또는 숫자 제한을 직접 업데이트하면 실시간으로 포커스를 미세 조정하여 가장 중요한 데이터가 즉시 처리되거나 강조 표시되도록 할 수 있습니다.

전체 업데이트에 대한 압축 비용 없이 스트리밍 색인 내의 데이터 포인트 제한 및 숫자 제한을 직접 업데이트할 수 있습니다.

이러한 메타데이터 전용 업데이트를 수행하려면 요청에 update_mask 필드를 추가해야 합니다. update_mask의 값은 all_restricts로 설정해야 합니다. 데이터 포인트에 설정된 제한 및 숫자 제한 값은 업데이트에 적용하려는 새로운 값이어야 합니다.

다음 예에서는 기존 데이터 포인트 2개에 제한을 추가하는 방법을 보여줍니다.

DATAPOINT_ID_1=
DATAPOINT_ID_2=

curl -H "Content-Type: application/json" -H "Authorization: Bearer gcloud auth print-access-token" http://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
-d '{datapoints:
[{datapoint_id: "'${DATAPOINT_ID_1}'", feature_vector: [...],  restricts:[{namespace: "color", allow_list: ["red"]}]},
{datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...],  restricts:[{namespace: "color", allow_list: ["red"]}]}
], update_mask: "all_restricts"}'

데이터 포인트 삭제

스트리밍 색인에서 데이터 포인트를 삭제해야 할 수도 있습니다. 이 curl을 사용하거나 Google Cloud 콘솔에서 이 작업을 수행할 수 있습니다.

색인에서 데이터 포인트를 삭제하는 주요 사용 사례는 색인과 실제 소스 간에 패리티를 유지하는 것입니다. 벡터 임베딩을 사용하여 검색 및 추천 목적으로 도서 인벤토리를 나타내는 서점을 고려해 보세요. 도서가 매진되거나 재고가 없는 경우 색인에서 해당 데이터 포인트를 삭제하면 검색 결과와 추천이 정확하고 최신 상태로 유지됩니다.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" http://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/indexes/{INDEX_ID}:removeDatapoints -d '{datapoint_ids: ["'{DATAPOINT_ID_1}'", "'{DATAPOINT_ID_2}'"]}'

소형화

마지막 재빌드 이후 새로운 업데이트를 모두 고려하여 색인이 주기적으로 다시 빌드됩니다. 이러한 재빌드 또는 '압축'은 쿼리 성능과 안정성을 높여줍니다. 스트리밍 업데이트와 배치 업데이트 모두에 대해 압축이 발생합니다.

• 스트리밍 업데이트: 벡터 검색은 휴리스틱 기반 측정항목을 사용하여 압축을 트리거할 시기를 결정합니다. 압축되지 않은 가장 오래된 데이터가 5일 전 데이터인 경우에는 항상 압축이 트리거됩니다. 스트리밍 업데이트 비용 외에도 일괄 업데이트와 동일한 요율로 색인을 재빌드하는 비용이 청구됩니다.

• 일괄 업데이트: 증분 데이터 세트 크기가 기본 데이터 세트 크기의 20%를 초과할 때 발생합니다.

색인 재빌드 및 쿼리

평소와 같이 grpc cli, 클라이언트 라이브러리, Python용 Vertex AI SDK를 사용하여 일치 또는 일괄 일치 요청을 전송할 수 있습니다. 쿼리를 재빌드할 때는 몇 초 이내에 업데이트가 표시될 수 있습니다. 색인을 쿼리하는 방법은 색인 쿼리로 최근접 이웃 가져오기를 참조하세요.

선택적인 필드

색인을 만들 때는 쿼리 미세 조정을 위해 사용할 수 있는 몇 가지 선택적인 필드가 있습니다.

제한으로 업서트

색인을 업서트하고 제한을 추가하는 것은 데이터 포인트에 태그를 지정하여 쿼리 시 필터링용으로 식별되도록 하는 방법입니다. 쿼리가 전송되기 전 데이터에 표시되는 결과를 제한하도록 제한 태그를 추가해야 할 수 있습니다. 예를 들어 고객이 색인에서 한 쿼리를 실행하려고 하지만 신발을 검색할 때와 같이 '빨간색'과 일치하는 항목만 결과에 표시하길 원합니다. 다음 예시에서는 색인을 업서트하고 모든 빨간색 신발로 필터링하고 파란색 신발은 거부합니다. 이렇게 하면 실행하기 전에 크고 다양한 색인에서 최상의 특정 옵션으로 검색 필터를 지정할 수 있습니다.

토큰 제한 외에도 예시에는 숫자 제한이 사용됩니다. 여기에서 데이터 포인트는 가격 20, 길이 0.3, 너비 0.5와 연결됩니다. 쿼리 시에는 이러한 숫자 제한을 사용해서 결과를 필터링하여 가격, 길이, 너비 값에 따라 쿼리 결과를 제한할 수 있습니다. 예를 들어 이 데이터 포인트는 가격이 25보다 크고, 길이가 1보다 작고 너비가 1보다 작은 값을 필터링하는 쿼리에 표시됩니다.

필터링에 대한 자세한 내용은 색인 생성을 위한 벡터 검색을 참조하세요.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" http://${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints: [
  {
    datapoint_id: "'${DATAPOINT_ID_1}'",
    feature_vector: [...],
    restricts: { namespace: "color", allow_list: ["red"], deny_list: ["blue"]},
    numeric_restricts: [{namespace: "price", value_int: 20}, {namespace: "length", value_float: 0.3}, {namespace: "width", value_double: 0.5}]
  }
]}'

크라우딩으로 업서트

크라우딩 태그는 결과 다양성을 향상시켜서 비슷한 결과를 제한합니다. 크라우딩은 결과 그룹의 일부 값 이하가 crowding_attribute의 동일한 값을 반환하도록 요구하는 가장 가까운 이웃 검색으로 생성되는 이웃 목록에 대한 제약 조건입니다. 예를 들어 신발을 사기 위해 온라인 쇼핑을 했다고 가정해보세요. 결과에 다양한 색상이 표시될 수 있지만 축구화와 같은 단일 스타일 제품을 원할 수 있습니다. 쿼리에서 per_crowding_attribute_num_neighbors = 3을 설정하여 동일한 색상의 신발이 3켤레 이하로 반환되도록 요청할 수 있습니다. 이 때 crowding_attribute는 데이터 포인트를 삽입할 때 신발 색상으로 설정한다고 가정합니다.

이 필드는 동일한 크라우딩 태그를 사용하여 허용되는 최대 일치 항목 수를 나타냅니다.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" http://${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints: [
  {
    datapoint_id: "'${DATAPOINT_ID_1}'",
    feature_vector: [...],
    restricts: { namespace: "type", allow_list: ["cleats"]}
    crowding_tag: { crowding_attribute: "red-shoe"},
  }
]}'

다음 단계

• 색인 구성 매개변수 알아보기
• 색인 모니터링 방법 알아보기