공개 색인 엔드포인트 배포 및 관리

색인을 쿼리하려면 먼저 몇 가지 단계를 수행해야 합니다.

필요한 경우 IndexEndpoint를 만들거나 기존 IndexEndpoint를 재사용합니다.
IndexEndpoint ID를 가져옵니다.
색인을 IndexEndpoint에 배포합니다.

`IndexEndpoint` 만들기

gcloud

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

INDEX_ENDPOINT_NAME: 색인 엔드포인트의 표시 이름
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

참고: 공개 엔드포인트를 사용하려면 --public-endpoint-enabled를 지정해야 합니다.

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

Linux, macOS 또는 Cloud Shell

gcloud ai index-endpoints create \
    --display-name=INDEX_ENDPOINT_NAME \
    --public-endpoint-enabled \
    --region=LOCATION \
    --project=PROJECT_ID

Windows(PowerShell)

gcloud ai index-endpoints create `
    --display-name=INDEX_ENDPOINT_NAME `
    --public-endpoint-enabled `
    --region=LOCATION `
    --project=PROJECT_ID

Windows(cmd.exe)

gcloud ai index-endpoints create ^
    --display-name=INDEX_ENDPOINT_NAME ^
    --public-endpoint-enabled ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

INDEX_ENDPOINT_NAME: 색인 엔드포인트의 표시 이름
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호

참고: 공개 엔드포인트를 사용하려면 publicEndpointEnabled 필드가 true여야 합니다.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints

JSON 요청 본문:

{
 "display_name": "INDEX_ENDPOINT_NAME",
 "publicEndpointEnabled": "true"
}

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

cURL(Linux, macOS, Cloud Shell)

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

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

curl -X POST \
     -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/indexEndpoints"

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 POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexEndpointOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-13T04:09:56.641107Z",
      "updateTime": "2022-01-13T04:09:56.641107Z"
    }
  }
}

응답에 "done": true가 포함될 때까지 작업 상태를 폴링할 수 있습니다.

Python

Vertex AI SDK for Python을 설치하거나 업데이트하는 방법은 Vertex AI SDK for Python 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.

def vector_search_create_index_endpoint(
    project: str, location: str, display_name: str
) -> None:
    """Create a vector search index endpoint.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        display_name (str): Required. The index endpoint display name
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create Index Endpoint
    index_endpoint = aiplatform.MatchingEngineIndexEndpoint.create(
        display_name=display_name,
        public_endpoint_enabled=True,
        description="Matching Engine Index Endpoint",
    )

    print(index_endpoint.name)

콘솔

다음 안내에 따라 색인 엔드포인트를 만듭니다.

Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
벡터 검색으로 이동
활성 색인 목록이 표시됩니다.
페이지 상단에서 색인 엔드포인트 탭을 선택합니다. 색인 엔드포인트가 표시됩니다.
새 색인 엔드포인트 만들기를 클릭합니다. 새 색인 엔드포인트 만들기 패널이 열립니다.
색인 엔드포인트의 표시 이름을 입력합니다.
리전 필드의 드롭다운에서 리전을 선택합니다.
액세스 필드에서 표준을 선택합니다.
만들기를 클릭합니다.

엔드포인트에 색인 배포

gcloud

이 예시에서는 gcloud ai index-endpoints deploy-index 명령어를 사용합니다.

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
DEPLOYED_INDEX_ID: 배포된 색인을 고유하게 식별하기 위해 사용자가 지정한 문자열. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 형식 가이드라인은 DeployedIndex.id를 참조하세요.
DEPLOYED_INDEX_ENDPOINT_NAME: 배포된 색인 엔드포인트의 표시 이름
INDEX_ID: 색인 ID
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

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

Linux, macOS 또는 Cloud Shell

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID \
    --deployed-index-id=DEPLOYED_INDEX_ID \
    --display-name=DEPLOYED_INDEX_ENDPOINT_NAME \
    --index=INDEX_ID \
    --region=LOCATION \
    --project=PROJECT_ID

Windows(PowerShell)

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID `
    --deployed-index-id=DEPLOYED_INDEX_ID `
    --display-name=DEPLOYED_INDEX_ENDPOINT_NAME `
    --index=INDEX_ID `
    --region=LOCATION `
    --project=PROJECT_ID

Windows(cmd.exe)

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID ^
    --deployed-index-id=DEPLOYED_INDEX_ID ^
    --display-name=DEPLOYED_INDEX_ENDPOINT_NAME ^
    --index=INDEX_ID ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
DEPLOYED_INDEX_ID: 배포된 색인을 고유하게 식별하기 위해 사용자가 지정한 문자열. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 형식 가이드라인은 DeployedIndex.id를 참조하세요.
DEPLOYED_INDEX_ENDPOINT_NAME: 배포된 색인 엔드포인트의 표시 이름
INDEX_ID: 색인 ID
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex

JSON 요청 본문:

{
 "deployedIndex": {
   "id": "DEPLOYED_INDEX_ID",
   "index": "projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID",
   "displayName": "DEPLOYED_INDEX_ENDPOINT_NAME"
 }
}

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

cURL(Linux, macOS, Cloud Shell)

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

curl -X POST \
     -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/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex"

PowerShell(Windows)

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

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

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

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-10-19T17:53:16.502088Z",
     "updateTime": "2022-10-19T17:53:16.502088Z"
   },
   "deployedIndexId": "DEPLOYED_INDEX_ID"
 }
}

Python

Vertex AI SDK for Python을 설치하거나 업데이트하는 방법은 Vertex AI SDK for Python 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.

def vector_search_deploy_index(
    project: str,
    location: str,
    index_name: str,
    index_endpoint_name: str,
    deployed_index_id: str,
) -> None:
    """Deploy a vector search index to a vector search index endpoint.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        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".
        index_endpoint_name (str): Required. Index endpoint to deploy the index to.
        deployed_index_id (str): Required. The user specified ID of the DeployedIndex.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

    # Create the index instance from an existing index
    index = aiplatform.MatchingEngineIndex(index_name=index_name)

    # Create the index endpoint instance from an existing endpoint.
    index_endpoint = aiplatform.MatchingEngineIndexEndpoint(
        index_endpoint_name=index_endpoint_name
    )

    # Deploy Index to Endpoint
    index_endpoint = index_endpoint.deploy_index(
        index=index, deployed_index_id=deployed_index_id
    )

    print(index_endpoint.deployed_indexes)

콘솔

다음 안내에 따라 엔드포인트에 색인을 배포합니다.

Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
벡터 검색으로 이동
활성 색인 목록이 표시됩니다.
배포하려는 색인의 이름을 선택합니다. 색인 세부정보 페이지가 열립니다.
색인 세부정보 페이지에서 엔드포인트에 배포를 클릭합니다. 색인 배포 패널이 열립니다.
표시 이름을 입력합니다. 이 이름은 ID 역할을 하며 업데이트될 수 없습니다.
엔드포인트 드롭다운에서 이 색인을 배포할 엔드포인트를 선택합니다. 참고: 색인이 이미 엔드포인트에 배포된 경우 엔드포인트를 사용할 수 없습니다.
(선택사항): 머신 유형 필드에서 표준 또는 높은 메모리를 선택합니다.
선택사항. 자동 확장 사용 설정을 선택하여 워크로드 수요에 따라 노드 수를 자동으로 조절합니다. 자동 확장이 사용 중지된 경우 기본 복제본 수는 2개입니다.
배포를 클릭하여 색인을 엔드포인트에 배포합니다. 참고: 배포되는 데 약 30분이 소요됩니다.

색인 도메인 이름 가져오기

색인을 배포한 후에는 온라인 쿼리에 색인을 사용할 수 있도록 도메인 이름이 필요합니다. 이 값은 publicEndpointDomainName 아래에 있습니다.

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`"  ${ENDPOINT}/v1/projects/${PROJECT_ID}/locations/${REGION}/indexEndpoints/${INDEX_ENDPOINT_ID}

응답 예시

{
  "name": "projects/181224308459/locations/us-central1/indexEndpoints/3370566089086861312",
  "displayName": "public-endpoint-test1",
  "deployedIndexes": [
    {
      "id": "test_index_public1",
      "index": "projects/181224308459/locations/us-central1/indexes/7733428228102029312",
      "displayName": "test_index_public1",
      "createTime": "2023-02-08T23:19:58.026843Z",
      "indexSyncTime": "2023-02-09T05:26:19.309417Z",
      "automaticResources": {
        "minReplicaCount": 2,
        "maxReplicaCount": 2
      },
      "deploymentGroup": "default"
    }
  ],
  "etag": "AMEw9yNkXQcSke8iqW9SYxfhj_hT9GCwPt1XlxVwJRSCxiXOYnG4CKrZM_X0oH-XN8tR",
  "createTime": "2023-02-08T22:44:20.285382Z",
  "updateTime": "2023-02-08T22:44:26.515162Z",
  "publicEndpointDomainName": "1957880287.us-central1-181224308459.vdb.vertexai.goog"
}

자동 확장 사용 설정

벡터 검색은 워크로드 수요에 따라 노드 수를 자동으로 조정할 수 있는 자동 확장을 지원합니다. 수요가 높으면 노드가 노드 풀에 추가됩니다(지정한 최대 크기를 초과하지 않음). 수요가 적으면 노드 풀이 지정된 최소 크기로 축소됩니다. 현재 복제본을 모니터링하여 사용 중인 실제 노드와 변경사항을 확인할 수 있습니다.

자동 확장을 사용하려면 색인을 배포할 때 maxReplicaCount 및 minReplicaCount를 지정합니다.

gcloud

다음 예시에서는 gcloud ai index-endpoints deploy-index 명령어를 사용합니다.

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
DEPLOYED_INDEX_ID: 배포된 색인을 고유하게 식별하기 위해 사용자가 지정한 문자열. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 형식 가이드라인은 DeployedIndex.id를 참조하세요.
DEPLOYED_INDEX_NAME: 배포된 색인의 표시 이름
INDEX_ID: 색인 ID
MIN_REPLICA_COUNT: 배포된 색인이 항상 배포되는 최소 머신 복제본 수. 지정된 경우 값이 1 이상이어야 합니다.
MAX_REPLICA_COUNT: 배포된 색인이 배포될 수 있는 최대 머신 복제본 수
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

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

Linux, macOS 또는 Cloud Shell

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID \
    --deployed-index-id=DEPLOYED_INDEX_ID \
    --display-name=DEPLOYED_INDEX_NAME \
    --index=INDEX_ID \
    --min-replica-count=MIN_REPLICA_COUNT \
    --max-replica-count=MAX_REPLICA_COUNT \
    --region=LOCATION \
    --project=PROJECT_ID

Windows(PowerShell)

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID `
    --deployed-index-id=DEPLOYED_INDEX_ID `
    --display-name=DEPLOYED_INDEX_NAME `
    --index=INDEX_ID `
    --min-replica-count=MIN_REPLICA_COUNT `
    --max-replica-count=MAX_REPLICA_COUNT `
    --region=LOCATION `
    --project=PROJECT_ID

Windows(cmd.exe)

gcloud ai index-endpoints deploy-index INDEX_ENDPOINT_ID ^
    --deployed-index-id=DEPLOYED_INDEX_ID ^
    --display-name=DEPLOYED_INDEX_NAME ^
    --index=INDEX_ID ^
    --min-replica-count=MIN_REPLICA_COUNT ^
    --max-replica-count=MAX_REPLICA_COUNT ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
DEPLOYED_INDEX_ID: 배포된 색인을 고유하게 식별하기 위해 사용자가 지정한 문자열. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 형식 가이드라인은 DeployedIndex.id를 참조하세요.
DEPLOYED_INDEX_NAME: 배포된 색인의 표시 이름
INDEX_ID: 색인 ID
MIN_REPLICA_COUNT: 배포된 색인이 항상 배포되는 최소 머신 복제본 수. 지정된 경우 값이 1 이상이어야 합니다.
MAX_REPLICA_COUNT: 배포된 색인이 배포될 수 있는 최대 머신 복제본 수
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex

JSON 요청 본문:

{
 "deployedIndex": {
   "id": "DEPLOYED_INDEX_ID",
   "index": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID",
   "displayName": "DEPLOYED_INDEX_NAME",
   "automaticResources": {
     "minReplicaCount": MIN_REPLICA_COUNT,
     "maxReplicaCount": MAX_REPLICA_COUNT
   }
 }
}

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

cURL(Linux, macOS, Cloud Shell)

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

curl -X POST \
     -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/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex"

PowerShell(Windows)

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

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

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

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2023-10-19T17:53:16.502088Z",
     "updateTime": "2023-10-19T17:53:16.502088Z"
   },
   "deployedIndexId": "DEPLOYED_INDEX_ID"
 }
}

콘솔

색인 배포 중에만 콘솔에서 자동 확장을 사용 설정할 수 있습니다.

Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
벡터 검색으로 이동
활성 색인 목록이 표시됩니다.
배포하려는 색인의 이름을 선택합니다. 색인 세부정보 페이지가 열립니다.
색인 세부정보 페이지에서 엔드포인트에 배포를 클릭합니다. 색인 배포 패널이 열립니다.
표시 이름을 입력합니다. 이 이름은 ID 역할을 하며 업데이트될 수 없습니다.
엔드포인트 드롭다운에서 이 색인을 배포할 엔드포인트를 선택합니다. 참고: 색인이 이미 엔드포인트에 배포된 경우 엔드포인트를 사용할 수 없습니다.
(선택사항): 머신 유형 필드에서 표준 또는 높은 메모리를 선택합니다.
선택사항. 자동 확장 사용 설정을 선택하여 워크로드 수요에 따라 노드 수를 자동으로 조절합니다. 자동 확장이 사용 중지된 경우 기본 복제본 수는 2개입니다.

minReplicaCount 및 maxReplicaCount 모두 설정되지 않으면 기본적으로 2로 설정됩니다.
maxReplicaCount만 설정된 경우 기본적으로 minReplicaCount는 2로 설정됩니다.
minReplicaCount만 설정된 경우 maxReplicaCount가 minReplicaCount로 설정됩니다.

`DeployedIndex` 변형

MutateDeployedIndex API를 사용하여 이미 배포된 색인의 배포 리소스(예: minReplicaCount 및 maxReplicaCount)를 업데이트할 수 있습니다.

색인이 배포된 후에는 사용자가 machineType를 변경할 수 없습니다.
만약 요청에 maxReplicaCount가 지정되지 않은 경우 DeployedIndex는 기존 maxReplicaCount를 계속 사용합니다.

gcloud

다음 예시에서는 gcloud ai index-endpoints mutate-deployed-index 명령어를 사용합니다.

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
DEPLOYED_INDEX_ID: 배포된 색인을 고유하게 식별하기 위해 사용자가 지정한 문자열. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 형식 가이드라인은 DeployedIndex.id를 참조하세요.
MIN_REPLICA_COUNT: 배포된 색인이 항상 배포되는 최소 머신 복제본 수. 지정된 경우 값이 1 이상이어야 합니다.
MAX_REPLICA_COUNT: 배포된 색인이 배포될 수 있는 최대 머신 복제본 수
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

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

Linux, macOS 또는 Cloud Shell

gcloud ai index-endpoints mutate-deployed-index INDEX_ENDPOINT_ID \
    --deployed-index-id=DEPLOYED_INDEX_ID \
    --min-replica-count=MIN_REPLICA_COUNT \
    --max-replica-count=MAX_REPLICA_COUNT \
    --region=LOCATION \
    --project=PROJECT_ID

Windows(PowerShell)

gcloud ai index-endpoints mutate-deployed-index INDEX_ENDPOINT_ID `
    --deployed-index-id=DEPLOYED_INDEX_ID `
    --min-replica-count=MIN_REPLICA_COUNT `
    --max-replica-count=MAX_REPLICA_COUNT `
    --region=LOCATION `
    --project=PROJECT_ID

Windows(cmd.exe)

gcloud ai index-endpoints mutate-deployed-index INDEX_ENDPOINT_ID ^
    --deployed-index-id=DEPLOYED_INDEX_ID ^
    --min-replica-count=MIN_REPLICA_COUNT ^
    --max-replica-count=MAX_REPLICA_COUNT ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
DEPLOYED_INDEX_ID: 배포된 색인을 고유하게 식별하기 위해 사용자가 지정한 문자열. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 형식 가이드라인은 DeployedIndex.id를 참조하세요.
MIN_REPLICA_COUNT: 배포된 색인이 항상 배포되는 최소 머신 복제본 수. 지정된 경우 값이 1 이상이어야 합니다.
MAX_REPLICA_COUNT: 배포된 색인이 배포될 수 있는 최대 머신 복제본 수
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:mutateDeployedIndex

JSON 요청 본문:

{
"deployedIndex": {
  "id": "DEPLOYED_INDEX_ID",
  "index": "projects/PROJECT_ID/locations/LOCATION/indexes/INDEX_ID",
  "displayName": "DEPLOYED_INDEX_NAME"
}
}

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

cURL(Linux, macOS, Cloud Shell)

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

curl -X POST \
     -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/indexEndpoints/INDEX_ENDPOINT_ID:mutateDeployedIndex"

PowerShell(Windows)

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

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

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

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

{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID",
"metadata": {
  "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployIndexOperationMetadata",
  "genericMetadata": {
    "createTime": "2020-10-19T17:53:16.502088Z",
    "updateTime": "2020-10-19T17:53:16.502088Z"
  },
  "deployedIndexId": "DEPLOYED_INDEX_ID"
}
}

성능에 영향을 주는 배포 설정

다음 배포 설정은 벡터 검색을 사용할 때 지연 시간, 가용성, 비용에 영향을 줄 수 있습니다. 이 가이드는 대부분의 케이스에 적용됩니다. 하지만 항상 구성으로 실험하여 사용 사례에 적합한지 확인해야 합니다.

설정 성능 영향

머신 유형

설정	성능 영향
머신 유형	하드웨어 선택은 선택한 샤드 크기와 직접 관련됩니다. 색인 생성 시에 지정한 샤드 선택에 따라 각 머신 유형에서 성능과 비용 간의 균형을 제공합니다. 가격 책정 페이지를 참조하여 사용 가능한 하드웨어와 가격을 확인합니다. 일반적으로 성능은 다음과 같은 순서로 증가합니다. E2 표준 E2 highmem N1 표준 N2D 표준
최소 복제본 수	`minReplicaCount`는 트래픽이 낮은 수준에서 빠르게 확장될 때 시스템에 콜드 스타트 문제가 발생하지 않도록 가용성 및 지연 시간을 위한 최소 용량을 예약합니다. 워크로드가 낮은 수준으로 떨어졌다가 빠르게 높은 수준으로 증가하는 경우에는 `minReplicaCount`를 초기 트래픽 버스트를 수용할 수 있는 수로 설정하는 것이 좋습니다.
최대 복제본 수	`maxReplicaCount`는 주로 사용량 비용을 제어합니다. 지연 시간이 증가하고 가용성이 낮아지는 단점이 있지만 특정 기준점 이상으로 비용이 증가하지 않도록 선택할 수 있습니다.

하드웨어 선택은 선택한 샤드 크기와 직접 관련됩니다. 색인 생성 시에 지정한 샤드 선택에 따라 각 머신 유형에서 성능과 비용 간의 균형을 제공합니다.

가격 책정 페이지를 참조하여 사용 가능한 하드웨어와 가격을 확인합니다. 일반적으로 성능은 다음과 같은 순서로 증가합니다.

E2 표준
E2 highmem
N1 표준
N2D 표준

최소 복제본 수

minReplicaCount는 트래픽이 낮은 수준에서 빠르게 확장될 때 시스템에 콜드 스타트 문제가 발생하지 않도록 가용성 및 지연 시간을 위한 최소 용량을 예약합니다.

워크로드가 낮은 수준으로 떨어졌다가 빠르게 높은 수준으로 증가하는 경우에는 minReplicaCount를 초기 트래픽 버스트를 수용할 수 있는 수로 설정하는 것이 좋습니다.

최대 복제본 수 maxReplicaCount는 주로 사용량 비용을 제어합니다. 지연 시간이 증가하고 가용성이 낮아지는 단점이 있지만 특정 기준점 이상으로 비용이 증가하지 않도록 선택할 수 있습니다.

`IndexEndpoints` 나열

IndexEndpoint 리소스를 나열하고 연결된 DeployedIndex 인스턴스 정보를 보려면 다음 코드를 실행합니다.

gcloud

다음 예시에서는 gcloud ai index-endpoints list 명령어를 사용합니다.

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

LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

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

Linux, macOS 또는 Cloud Shell

gcloud ai index-endpoints list \
    --region=LOCATION \
    --project=PROJECT_ID

Windows(PowerShell)

gcloud ai index-endpoints list `
    --region=LOCATION `
    --project=PROJECT_ID

Windows(cmd.exe)

gcloud ai index-endpoints list ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호

HTTP 메서드 및 URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints

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

cURL(Linux, macOS, Cloud Shell)

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints"

PowerShell(Windows)

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

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints" | Select-Object -Expand Content

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

{
 "indexEndpoints": [
   {
     "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID",
     "displayName": "INDEX_ENDPOINT_DISPLAY_NAME",
     "deployedIndexes": [
       {
         "id": "DEPLOYED_INDEX_ID",
         "index": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID",
         "displayName": "DEPLOYED_INDEX_DISPLAY_NAME",
         "createTime": "2021-06-04T02:23:40.178286Z",
         "privateEndpoints": {
           "matchGrpcAddress": "GRPC_ADDRESS"
         },
         "indexSyncTime": "2022-01-13T04:22:00.151916Z",
         "automaticResources": {
           "minReplicaCount": 2,
           "maxReplicaCount": 10
         }
       }
     ],
     "etag": "AMEw9yP367UitPkLo-khZ1OQvqIK8Q0vLAzZVF7QjdZ5O3l7Zow-mzBo2l6xmiuuMljV",
     "createTime": "2021-03-17T04:47:28.460373Z",
     "updateTime": "2021-06-04T02:23:40.930513Z",
     "network": "VPC_NETWORK_NAME"
   }
 ]
}

콘솔

다음 안내를 따라 색인 엔드포인트 목록을 확인합니다.

Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
벡터 검색으로 이동
페이지 상단에서 색인 엔드포인트 탭을 선택합니다.
기존 색인 엔드포인트가 모두 표시됩니다.

자세한 내용은 IndexEndpoint 참고 문서를 확인하세요.

색인 배포 취소

엔드포인트에서 색인을 배포 취소하려면 다음 코드를 실행합니다.

gcloud

다음 예시에서는 gcloud ai index-endpoints undeploy-index 명령어를 사용합니다.

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
DEPLOYED_INDEX_ID: 배포된 색인을 고유하게 식별하기 위해 사용자가 지정한 문자열. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 형식 가이드라인은 DeployedIndex.id를 참조하세요.
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

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

Linux, macOS 또는 Cloud Shell

gcloud ai index-endpoints undeploy-index INDEX_ENDPOINT_ID \
    --deployed-index-id=DEPLOYED_INDEX_ID \
    --region=LOCATION \
    --project=PROJECT_ID

Windows(PowerShell)

gcloud ai index-endpoints undeploy-index INDEX_ENDPOINT_ID `
    --deployed-index-id=DEPLOYED_INDEX_ID `
    --region=LOCATION `
    --project=PROJECT_ID

Windows(cmd.exe)

gcloud ai index-endpoints undeploy-index INDEX_ENDPOINT_ID ^
    --deployed-index-id=DEPLOYED_INDEX_ID ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
DEPLOYED_INDEX_ID: 배포된 색인을 고유하게 식별하기 위해 사용자가 지정한 문자열. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함할 수 있습니다. 형식 가이드라인은 DeployedIndex.id를 참조하세요.
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID:undeployIndex

JSON 요청 본문:

{
 "deployed_index_id": "DEPLOYED_INDEX_ID"
}

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

cURL(Linux, macOS, Cloud Shell)

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

curl -X POST \
     -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/indexEndpoints/INDEX_ENDPOINT_ID:undeployIndex"

PowerShell(Windows)

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

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

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

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UndeployIndexOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-01-13T04:09:56.641107Z",
     "updateTime": "2022-01-13T04:09:56.641107Z"
   }
 }
}

콘솔

엔드포인트에서 색인을 배포 취소하려면 다음 안내를 따르세요.

Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
벡터 검색으로 이동
활성 색인 목록이 표시됩니다.
배포 취소할 색인을 선택합니다. 색인 세부정보 페이지가 열립니다.
배포된 색인 섹션에서 배포 취소하려는 색인 버전을 식별하세요.
색인과 동일한 행에 있는 옵션 메뉴를 클릭하고 배포 취소를 선택합니다.
확인 화면이 열립니다. 배포 취소를 클릭합니다. 참고: 배포가 취소되는 데 최대 30분이 걸릴 수 있습니다.

`IndexEndpoint` 삭제

IndexEndpoint를 삭제하기 전에 엔드포인트에 배포된 모든 색인을 배포 취소해야 합니다.

gcloud

다음 예시에서는 gcloud ai index-endpoints delete 명령어를 사용합니다.

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

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

Linux, macOS 또는 Cloud Shell

gcloud ai index-endpoints delete INDEX_ENDPOINT_ID \
    --region=LOCATION \
    --project=PROJECT_ID

Windows(PowerShell)

gcloud ai index-endpoints delete INDEX_ENDPOINT_ID `
    --region=LOCATION `
    --project=PROJECT_ID

Windows(cmd.exe)

gcloud ai index-endpoints delete INDEX_ENDPOINT_ID ^
    --region=LOCATION ^
    --project=PROJECT_ID

REST

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

INDEX_ENDPOINT_ID: 색인 엔드포인트 ID
LOCATION: Vertex AI를 사용하는 리전
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
PROJECT_NUMBER: 프로젝트의 자동으로 생성된 프로젝트 번호

HTTP 메서드 및 URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID

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

cURL(Linux, macOS, Cloud Shell)

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

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID"

PowerShell(Windows)

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

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

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID" | Select-Object -Expand Content

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

{
 "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeleteOperationMetadata",
   "genericMetadata": {
     "createTime": "2022-01-13T04:36:19.142203Z",
     "updateTime": "2022-01-13T04:36:19.142203Z"
   }
 },
 "done": true,
 "response": {
   "@type": "type.googleapis.com/google.protobuf.Empty"
 }
}

콘솔

색인 엔드포인트를 삭제하려면 다음 안내를 따르세요.

Google Cloud 콘솔의 Vertex AI 섹션에서 배포 및 사용 섹션으로 이동합니다. 벡터 검색을 선택합니다.
벡터 검색으로 이동
페이지 상단에서 색인 엔드포인트 탭을 선택합니다.
기존 색인 엔드포인트가 모두 표시됩니다.
삭제하려는 색인과 동일한 행에 있는 옵션 메뉴를 클릭하고 삭제를 선택합니다.
확인 화면이 열립니다. 삭제를 클릭합니다. 이제 색인 엔드포인트가 삭제됩니다.

공개 색인 엔드포인트 배포 및 관리

IndexEndpoint 만들기

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

Python

콘솔

엔드포인트에 색인 배포

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

Python

콘솔

색인 도메인 이름 가져오기

응답 예시

자동 확장 사용 설정

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

콘솔

DeployedIndex 변형

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

성능에 영향을 주는 배포 설정

IndexEndpoints 나열

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

콘솔

색인 배포 취소

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

콘솔

IndexEndpoint 삭제

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

콘솔

`IndexEndpoint` 만들기

`DeployedIndex` 변형

`IndexEndpoints` 나열

`IndexEndpoint` 삭제