다음 섹션에서는 색인을 구성하고, 만들고, 나열하고, 삭제하는 방법을 설명합니다.
색인 개요
색인은 임베딩 벡터로 구성된 하나 이상의 파일입니다. 이러한 벡터는 벡터 검색을 사용하여 배포하고 쿼리하려는 대량의 데이터로 생성됩니다. 벡터 검색을 사용하면 데이터로 업데이트하려는 방법에 따라 두 가지 유형의 색인을 만들 수 있습니다. 일괄 업데이트용으로 설계된 색인이나 업데이트 스트리밍용으로 설계된 색인을 만들 수 있습니다.
일괄 색인은 매주 또는 매월 처리되는 시스템과 같이 일정 기간 동안 저장된 데이터를 사용하여 색인을 대량으로 업데이트하려는 경우에 사용됩니다 스트리밍 색인은 새 데이터가 데이터 스토어에 추가될 때 색인 데이터를 업데이트하려는 경우에 사용됩니다. 예를 들어 서점을 운영하고 새로운 재고를 가능한 한 빨리 온라인에 표시하려는 경우가 해당됩니다. 설정과 요구사항이 다르기 때문에 선택하는 유형이 중요합니다.
색인 매개변수 구성
색인을 만들기 전에 색인의 매개변수를 구성합니다.
예를 들어 index_metadata.json
이라는 파일을 만듭니다.
{ "contentsDeltaUri": "gs://BUCKET_NAME/path", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "shardSize": "SHARD_SIZE_MEDIUM", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 5000, "fractionLeafNodesToSearch": 0.03 } } } }
색인 구성 매개변수에서 이러한 각 필드의 정의를 찾을 수 있습니다.
색인 만들기
색인 크기
색인 데이터는 처리를 위해 샤드라고 하는 동일한 부분으로 분할됩니다. 색인을 만들 때 사용할 샤드 크기를 지정해야 합니다. 지원되는 크기는 다음과 같습니다.
SHARD_SIZE_SMALL
: 샤드당 2GiBSHARD_SIZE_MEDIUM
: 샤드당 20GiBSHARD_SIZE_LARGE
: 샤드당 50GiB
색인 배포(공개 엔드포인트 사용 또는 VPC 엔드포인트 사용)에 사용할 수 있는 머신 유형은 색인의 샤드 크기에 따라 달라집니다. 다음 표에서는 각 머신 유형이 지원하는 샤드 크기를 확인할 수 있습니다.
머신 유형 | SHARD_SIZE_SMALL |
SHARD_SIZE_MEDIUM |
SHARD_SIZE_LARGE |
---|---|---|---|
n1-standard-16 |
|||
n1-standard-32 |
|||
e2-standard-2 |
(기본값) | ||
e2-standard-16 |
(기본값) | ||
e2-highmem-16 |
(기본값) | ||
n2d-standard-32 |
샤드 크기 및 머신 유형이 가격에 미치는 영향을 알아보려면 Vertex AI 가격 책정 페이지를 참조하세요.
일괄 업데이트 색인 만들기
다음 안내를 따라 색인을 만들고 배포합니다. 임베딩이 아직 준비되지 않았으면 빈 일괄 색인 만들기로 건너뛸 수 있습니다. 이 옵션을 사용하면 색인 생성 시 임베딩 데이터가 필요하지 않습니다.
색인을 만들려면 다음 안내를 따르세요.
gcloud
아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- LOCAL_PATH_TO_METADATA_FILE: 메타데이터 파일의 로컬 경로
- INDEX_NAME: 색인의 표시 이름
- LOCATION: Vertex AI를 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
gcloud ai indexes create \ --metadata-file=LOCAL_PATH_TO_METADATA_FILE \ --display-name=INDEX_NAME \ --region=LOCATION \ --project=PROJECT_ID
Windows(PowerShell)
gcloud ai indexes create ` --metadata-file=LOCAL_PATH_TO_METADATA_FILE ` --display-name=INDEX_NAME ` --region=LOCATION ` --project=PROJECT_ID
Windows(cmd.exe)
gcloud ai indexes create ^ --metadata-file=LOCAL_PATH_TO_METADATA_FILE ^ --display-name=INDEX_NAME ^ --region=LOCATION ^ --project=PROJECT_ID
다음과 비슷한 응답이 표시됩니다.
You can poll for the status of the operation for the response to include "done": true. Use the following example to poll the status. $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1
describe
명령어에 대한 자세한 내용은 gcloud AI 작업을 참조하세요.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- INPUT_DIR: 색인 콘텐츠의 Cloud Storage 디렉터리 경로
- INDEX_NAME: 색인의 표시 이름
- LOCATION: Vertex AI를 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호
HTTP 메서드 및 URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
JSON 요청 본문:
{ "display_name": "INDEX_NAME", "metadata": { "contentsDeltaUri": "INPUT_DIR", "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
다음과 비슷한 JSON 응답이 표시됩니다.
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2022-01-08T01:21:10.147035Z", "updateTime": "2022-01-08T01:21:10.147035Z" } } }
Terraform
다음 샘플에서는 google_vertex_ai_index
Terraform 리소스를 사용하여 일괄 업데이트용 색인을 만듭니다.
Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요.
Python
Vertex AI SDK for Python을 설치하거나 업데이트하는 방법은 Vertex AI SDK for Python 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.
콘솔
다음 안내에 따라 일괄 업데이트용 색인을 만듭니다.
- Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
- 새 색인 만들기를 클릭하여 색인 창을 엽니다. 새 색인 만들기 창이 나타납니다.
- 표시 이름 필드에 색인을 고유하게 식별할 수 있는 이름을 입력합니다.
- 설명 필드에 색인의 용도에 대한 설명을 입력합니다.
- 리전 필드의 드롭다운에서 리전을 선택합니다.
- Cloud Storage 필드에서 벡터 데이터가 저장된 Cloud Storage 폴더를 검색하고 선택합니다.
- 알고리즘 유형 드롭다운에서 벡터 검색이 효율적인 검색을 위해 사용하는 알고리즘 유형을 선택합니다. treeAH 알고리즘을 선택하는 경우 대략적인 이웃 수를 입력합니다.
- 측정기준 필드에 입력 벡터의 측정기준 수를 입력합니다.
- 업데이트 방법 필드에서 일괄을 선택합니다.
- 샤드 크기 필드의 드롭다운에서 원하는 샤드 크기를 선택합니다.
- 만들기를 클릭합니다. 새 색인이 준비되면 색인 목록에 새 색인이 표시됩니다. 참고: 빌드 시간은 완료까지 최대 1시간이 걸릴 수 있습니다.
빈 일괄 색인 만들기
색인을 즉시 만들고 배포하려면 빈 일괄 색인을 만들면 됩니다. 이 옵션을 사용하면 색인 생성 시 임베딩 데이터가 필요하지 않습니다.
빈 색인을 만드는 요청은 일괄 업데이트용 색인을 만드는 것과 거의 동일합니다. 차이점은 데이터 위치를 연결하지 않으므로 contentsDeltaUri
필드를 삭제하는 것입니다. 다음은 빈 일괄 색인의 예시입니다.
빈 색인 요청 예시
{ "display_name": INDEX_NAME, "indexUpdateMethod": "BATCH_UPDATE", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
스트리밍 업데이트 색인 만들기
다음 안내에 따라 스트리밍 색인을 만들고 배포합니다. 임베딩이 아직 준비되지 않았으면 스트리밍 업데이트를 위한 빈 색인 만들기로 건너뜁니다. 이 옵션을 사용하면 색인 생성 시 임베딩 데이터가 필요하지 않습니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- INDEX_NAME: 색인의 표시 이름
- DESCRIPTION: 색인에 대한 설명
- INPUT_DIR: 색인 콘텐츠의 Cloud Storage 디렉터리 경로
- DIMENSIONS: 임베딩 벡터의 차원 수
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호
- LOCATION: Vertex AI를 사용하는 리전
HTTP 메서드 및 URL:
POST https://ENDPOINT-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
JSON 요청 본문:
{ displayName: "INDEX_NAME", description: "DESCRIPTION", metadata: { contentsDeltaUri: "INPUT_DIR", config: { dimensions: "DIMENSIONS", approximateNeighborsCount: 150, distanceMeasureType: "DOT_PRODUCT_DISTANCE", algorithmConfig: {treeAhConfig: {leafNodeEmbeddingCount: 10000, leafNodesToSearchPercent: 2}} }, }, indexUpdateMethod: "STREAM_UPDATE" }
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
다음과 비슷한 JSON 응답이 표시됩니다.
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.ui.CreateIndexOperationMetadata", "genericMetadata": { "createTime": "2023-12-05T23:17:45.416117Z", "updateTime": "2023-12-05T23:17:45.416117Z", "state": "RUNNING", "worksOn": [ "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID" ] } } }
콘솔
다음 안내에 따라 Google Cloud 콘솔에서 스트리밍 업데이트의 색인을 만드세요.
스트리밍 업데이트에 사용할 수 있는 색인을 만들려면 indexUpdateMethod
를 STREAM_UPDATE
로 설정해야 한다는 점을 제외하고는 일괄 업데이트 색인을 설정하는 것과 비슷한 단계가 필요합니다.
- Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
- 새 색인 만들기를 클릭하여 색인 창을 엽니다. 새 색인 만들기 창이 나타납니다.
- 표시 이름 필드에 색인을 고유하게 식별할 수 있는 이름을 입력합니다.
- 설명 필드에 색인의 용도에 대한 설명을 입력합니다.
- 리전 필드의 드롭다운에서 리전을 선택합니다.
- Cloud Storage 필드에서 벡터 데이터가 저장된 Cloud Storage 폴더를 검색하고 선택합니다.
- 알고리즘 유형 드롭다운에서 벡터 검색이 검색을 수행하는 데 사용할 알고리즘 유형을 선택합니다. treeAH 알고리즘을 선택하는 경우 대략적인 이웃 수를 입력합니다.
- 측정기준 필드에 입력 벡터의 측정기준 수를 입력합니다.
- 업데이트 방법 필드에서 스트림을 선택합니다.
- 샤드 크기 필드의 드롭다운에서 원하는 샤드 크기의 선택합니다.
- 만들기를 클릭합니다. 새 색인이 준비되면 색인 목록에 새 색인이 표시됩니다. 참고: 빌드 시간은 완료까지 최대 1시간이 걸릴 수 있습니다.
Python
Vertex AI SDK for Python을 설치하거나 업데이트하는 방법은 Vertex AI SDK for Python 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.
스트리밍 업데이트용 빈 색인 만들기
색인을 즉시 만들고 배포하려면 스트리밍을 위해 빈 색인을 만들면 됩니다. 이 옵션을 사용하면 색인 생성 시 임베딩 데이터가 필요하지 않습니다.
빈 색인을 만드는 요청은 스트리밍을 위한 색인을 만드는 것과 거의 동일합니다. 차이점은 데이터 위치를 연결하지 않으므로 contentsDeltaUri
필드를 삭제하는 것입니다. 다음은 빈 스트리밍 색인 예시입니다.
빈 색인 요청 예시
{ "display_name": INDEX_NAME, "indexUpdateMethod": "STREAM_UPDATE", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "algorithm_config": { "treeAhConfig": { "leafNodeEmbeddingCount": 500, "leafNodesToSearchPercent": 7 } } } } }
색인 나열
gcloud
아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- INDEX_NAME: 색인의 표시 이름
- LOCATION: Vertex AI를 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
gcloud ai indexes list \ --region=LOCATION \ --project=PROJECT_ID
Windows(PowerShell)
gcloud ai indexes list ` --region=LOCATION ` --project=PROJECT_ID
Windows(cmd.exe)
gcloud ai indexes list ^ --region=LOCATION ^ --project=PROJECT_ID
다음과 비슷한 응답이 표시됩니다.
You can poll for the status of the operation for the response to include "done": true. Use the following example to poll the status. $ gcloud ai operations describe 1234567890123456789 --project=my-test-project --region=us-central1
describe
명령어에 대한 자세한 내용은 gcloud AI 작업을 참조하세요.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- INDEX_NAME: 색인의 표시 이름
- LOCATION: Vertex AI를 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호
HTTP 메서드 및 URL:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexes
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
다음과 비슷한 JSON 응답이 표시됩니다.
{ "indexes": [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID", "displayName": "INDEX_NAME", "metadataSchemaUri": "gs://google-cloud-aiplatform/schema/matchingengine/metadata/nearest_neighbor_search_1.0.0.yaml", "metadata": { "config": { "dimensions": 100, "approximateNeighborsCount": 150, "distanceMeasureType": "DOT_PRODUCT_DISTANCE", "featureNormType": "NONE", "algorithmConfig": { "treeAhConfig": { "maxLeavesToSearch": 50, "leafNodeCount": 10000 } } } }, "etag": "AMEw9yNU8YX5IvwuINeBkVv3yNa7VGKk11GBQ8GkfRoVvO7LgRUeOo0qobYWuU9DiEc=", "createTime": "2020-11-08T21:56:30.558449Z", "updateTime": "2020-11-08T22:39:25.048623Z" } ] }
콘솔
색인 목록을 확인하려면 다음 안내를 따르세요.
- Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
- 활성 색인 목록이 표시됩니다.
색인 조정
색인을 조정하려면 배포된 색인의 성능, 특히 재현율과 지연 시간에 영향을 주는 구성 매개변수를 설정해야 합니다. 이러한 매개변수는 색인을 처음 만들 때 설정됩니다. 무작위 대입 색인을 사용하여 재현율을 측정할 수 있습니다.
성능에 영향을 주는 구성 매개변수
다음 구성 매개변수는 색인 생성 시 설정할 수 있으며 벡터 검색을 사용할 때 재현율, 지연 시간, 가용성, 비용에 영향을 줄 수 있습니다. 이 가이드는 대부분의 케이스에 적용됩니다. 하지만 항상 구성으로 실험하여 사용 사례에 적합한지 확인해야 합니다.
매개변수 정의는 색인 구성 매개변수를 참조하세요.
매개변수 | 정보 | 성능 영향 |
---|---|---|
shardSize
|
각 머신의 데이터 양을 제어합니다. 샤드 크기를 선택할 때 향후 데이터 세트의 크기를 예상하세요. 데이터 세트 크기에 상한값이 있으면 이에 맞게 적절한 샤드 크기를 선택합니다. 상한값이 없거나 사용 사례가 지연 시간 변동에 매우 민감한 경우에는 큰 샤드 크기를 선택하는 것이 좋습니다. |
더 작은 샤드를 많이 구성하면 검색 중에 더 많은 수의 후보 결과가 처리됩니다. 더 많은 수의 샤드는 다음과 같은 방식으로 성능에 영향을 줄 수 있습니다.
더 큰 샤드의 수를 적게 구성하면 검색 중에 처리되는 후보 결과가 줄어듭니다. 더 적은 수의 샤드는 다음과 같은 방식으로 성능에 영향을 줄 수 있습니다.
|
distanceMeasureType
|
데이터 포인트와 쿼리 벡터 간의 거리 계산에 사용되는 알고리즘을 결정합니다. |
다음
|
leafNodeEmbeddingCount
|
각 리프 노드의 임베딩 수입니다. 기본적으로 1000으로 설정됩니다.
일반적으로 |
각 리프 노드의 임베딩 수를 늘리면 지연 시간이 줄어들지만 재현율 품질은 저하될 수 있습니다. 다음과 같은 방법으로 성능에 영향을 줄 수 있습니다.
각 리프 노드의 임베딩 수를 줄이면 다음과 같은 방식으로 성능에 영향을 미칠 수 있습니다.
|
무작위 대입 색인을 사용하여 재현율 측정
가장 가까운 이웃을 가져오려면 무작위 대입 알고리즘으로 색인을 사용합니다. 무작위 대입 알고리즘은 100% 재현율을 제공하지만 지연 시간이 길어집니다. 무작위 대입 색인을 사용하여 재현율을 측정하는 것은 일반적으로 프로덕션 제공에 적합하지 않지만 오프라인으로 다양한 색인 생성 옵션의 재현율을 평가하는 데 유용할 수 있습니다.
무작위 대입 알고리즘으로 색인을 만들려면 색인 메타데이터에 brute_force_config
를 지정합니다.
curl -X POST -H "Content-Type: application/json" \ -H "Authorization: Bearer `gcloud auth print-access-token`" \ https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \ -d '{ displayName: "'${DISPLAY_NAME}'", description: "'${DESCRIPTION}'", metadata: { contentsDeltaUri: "'${INPUT_DIR}'", config: { dimensions: 100, approximateNeighborsCount: 150, distanceMeasureType: "DOT_PRODUCT_DISTANCE", featureNormType: "UNIT_L2_NORM", algorithmConfig: { bruteForceConfig: {} } }, }, }'
색인 삭제
gcloud
아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- INDEX_ID: 색인 ID
- LOCATION: Vertex AI를 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
gcloud ai indexes delete INDEX_ID \ --region=LOCATION \ --project=PROJECT_ID
Windows(PowerShell)
gcloud ai indexes delete INDEX_ID ` --region=LOCATION ` --project=PROJECT_ID
Windows(cmd.exe)
gcloud ai indexes delete INDEX_ID ^ --region=LOCATION ^ --project=PROJECT_ID
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- INDEX_ID: 색인 ID
- LOCATION: Vertex AI를 사용하는 리전
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호
HTTP 메서드 및 URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
다음과 비슷한 JSON 응답이 표시됩니다.
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeleteOperationMetadata", "genericMetadata": { "createTime": "2022-01-08T02:35:56.364956Z", "updateTime": "2022-01-08T02:35:56.364956Z" } }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty" } }
콘솔
다음 안내를 따라 하나 이상의 색인을 삭제합니다.
- Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
- 활성 색인 목록이 표시됩니다.
- 색인을 삭제하려면 색인과 동일한 행에 있는 옵션 메뉴로 이동하여 삭제를 선택합니다.
다음 단계
- 색인 구성 매개변수 알아보기
- 공개 색인 엔드포인트 배포 및 관리 방법 알아보기
- VPC 네트워크에서 색인 엔드포인트 배포 및 관리 방법 알아보기
- 색인 업데이트 및 다시 빌드 방법 알아보기
- 색인 모니터링 방법 알아보기