이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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

개요

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

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

일괄 색인 업데이트

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

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

Index.metadata.contentsDeltaUri를 업데이트할 벡터가 포함된 Cloud Storage URI로 설정합니다.
isCompleteOverwrite를 true로 설정합니다. true로 설정하면 제공한 새 메타데이터 파일로 전체 색인을 완전히 덮어씁니다.

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

gcloud

색인 메타데이터 파일을 업데이트합니다 .

gcloud ai indexes update 명령어 를 사용합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

LOCAL_PATH_TO_METADATA_FILE: 메타데이터 파일의 로컬 경로
INDEX_ID: 색인 ID
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

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

Windows(PowerShell)

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

Windows(cmd.exe)

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

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

INPUT_DIR: 색인 콘텐츠의 Cloud Storage 디렉터리 경로
INDEX_ID: 색인 ID
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호

HTTP 메서드 및 URL:

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

JSON 요청 본문:

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

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

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

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$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 "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

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

콘솔

다음 안내를 따라 일괄 색인 콘텐츠를 업데이트합니다.

Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
벡터 검색으로 이동
업데이트할 색인을 선택합니다. 색인 정보 페이지가 열립니다.
색인 수정을 선택합니다. 색인 수정 창이 열립니다.
Cloud Storage 필드에서 벡터 데이터가 저장된 Cloud Storage 폴더를 검색하고 선택합니다.
(선택사항) 모든 기존 데이터를 덮어쓰려면 전체 덮어쓰기 상자를 선택합니다.
업데이트를 클릭합니다.
완료를 클릭하여 패널을 닫습니다.

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

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

스트리밍 색인 업데이트

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

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

데이터 포인트 업서트

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

Python

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)

Curl

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

  
  DATAPOINT_ID_1=
  DATAPOINT_ID_2=
  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: [...]},
  {datapoint_id: "'${DATAPOINT_ID_2}'", feature_vector: [...]}]}'

공개 미리보기인 하이브리드 검색을 사용하면 데이터 포인트에 대한 희소 및 밀집 임베딩 표현이 지원됩니다. 업서트 연산에서 밀집 임베딩을 생략하면 밀집 표현이 삭제되고, 희소 임베딩을 생략하면 희소 표현이 삭제됩니다.

이 예시에서는 밀집 임베딩과 희소 임베딩을 둘 다 업데이트합니다.

  
    curl -X POST -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: "111", feature_vector: [0.111, 0.111], "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}}]}'

이 예시에서는 밀집 임베딩을 업데이트하고 희소 임베딩을 삭제합니다.

    
      curl -X POST -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: "111", feature_vector: [0.111, 0.111]}]}'

이 예시에서는 희소 임베딩을 업데이트하고 밀집 임베딩을 삭제합니다.

    
      curl -X POST -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: "111",  "sparse_embedding": {"values": [111.0,111.1,111.2], "dimensions": [10,20,30]}}]}'

콘솔

다음 안내에 따라 콘텐츠를 스트리밍 색인으로 업데이트하세요.

Google Cloud 콘솔에서 벡터 검색 페이지로 이동합니다.
벡터 검색으로 이동
업데이트할 색인을 선택합니다. 색인 정보 페이지가 열립니다.
색인 수정을 클릭합니다. 색인 수정 창이 열립니다.
창에서 콘텐츠를 추가할 데이터 포인트 업서트 탭을 선택합니다.
데이터 포인트 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" https://${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


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

콘솔

이 안내를 따라 스트리밍 색인에서 데이터 포인트를 삭제합니다.

Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
벡터 검색으로 이동
업데이트할 스트리밍 색인을 선택합니다. 색인 정보 페이지가 열립니다.
색인 수정을 선택합니다. 색인 수정 창이 열립니다.
창에서 데이터 포인트 삭제 탭을 선택합니다.
쉼표로 구분된 데이터 포인트 ID 목록을 제공하여 최대 20개의 데이터 포인트를 추가하세요.
삭제를 클릭합니다.
완료를 클릭하여 패널을 닫습니다.

소형화

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

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

색인 재빌드 및 쿼리

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

선택적인 필드

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

제한으로 업서트

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

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

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

Python

# Upsert datapoints
_TEST_DATAPOINT_1 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="3",
    feature_vector=[0.00526886899, -0.0198396724],
    restricts=[
        aiplatform_v1.types.index.IndexDatapoint.Restriction(namespace="Color", allow_list=["red"])
    ],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_int=1,
        )
    ],
)
_TEST_DATAPOINT_2 =  aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="4",
    feature_vector=[0.00526886899, -0.0198396724],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_double=0.1,
        )
    ],
    crowding_tag=aiplatform_v1.types.index.IndexDatapoint.CrowdingTag(crowding_attribute="crowding"),
)
_TEST_DATAPOINT_3 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="5",
    feature_vector=[0.00526886899, -0.0198396724],
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_float=1.1,
        )
    ],
)

_TEST_DATAPOINTS = [_TEST_DATAPOINT_1, _TEST_DATAPOINT_2, _TEST_DATAPOINT_3]

my_streaming_index = my_streaming_index.upsert_datapoints(datapoints=_TEST_DATAPOINTS)

# Dynamic metadata update
_TEST_DATAPOINT_4 = aiplatform_v1.types.index.IndexDatapoint(
    datapoint_id="-2",
    numeric_restricts=[
        aiplatform_v1.types.index.IndexDatapoint.NumericRestriction(
            namespace="cost",
            value_float=1.1,
        )
    ],
)
my_streaming_index = my_streaming_index.upsert_datapoints(datapoints=[_TEST_DATAPOINT4], update_mask=["all_restricts"])

curl

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${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`" https://${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"},
  }
]}'

다음 단계

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