Implantar e gerenciar endpoints de índice público

Há algumas etapas necessárias antes de poder consultar um índice:

1. Crie uma IndexEndpoint, se necessário, ou reutilize uma IndexEndpoint atual.
2. Consiga o código da IndexEndpoint.
3. Implantar o índice no IndexEndpoint.

Crie um IndexEndpoint

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

• INDEX_ENDPOINT_NAME: nome de exibição do endpoint do índice.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.

Observação: para usar um endpoint público, --public-endpoint-enabled precisa ser especificado.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• INDEX_ENDPOINT_NAME: nome de exibição do endpoint do índice.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.

Observação: para usar um endpoint público, o campo publicEndpointEnabled precisa ser true.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Pesquise o status da operação até que a resposta inclua "done": true.

Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

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)

Console

Use estas instruções para criar um endpoint de índice.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acessar a Vector Search

2. Uma lista dos índices ativos será exibida.
3. Na parte superior da página, selecione a guia Endpoints do índice. Os endpoints do índice serão exibidos.
4. Clique em Criar novo endpoint de índice. O painel "Criar um endpoint de índice" é aberto.
5. Informe um nome de exibição para o endpoint do índice.
6. No campo Região, selecione uma região na lista suspensa.
7. No campo Acesso, selecione Padrão.
8. Clique em Criar.

Implantar um índice em um endpoint

Importante: a implantação inicial de um índice em um endpoint geralmente leva de 20 a 30 minutos. É possível implantar no máximo 20 índices em um endpoint.

gcloud

O exemplo a seguir usa o comando gcloud ai index-endpoints deploy-index.

Antes de usar os dados do comando abaixo, faça estas substituições:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• DEPLOYED_INDEX_ID: uma string especificada pelo usuário para identificar de maneira exclusiva o índice implantado. Ela precisa começar com uma letra e conter apenas letras, números ou sublinhados. Consulte DeployedIndex.id para ver as diretrizes de formato.
• DEPLOYED_INDEX_ENDPOINT_NAME: nome de exibição do endpoint do índice implantado.
• INDEX_ID: o ID do índice.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• DEPLOYED_INDEX_ID: uma string especificada pelo usuário para identificar de maneira exclusiva o índice implantado. Ela precisa começar com uma letra e conter apenas letras, números ou sublinhados. Consulte DeployedIndex.id para ver as diretrizes de formato.
• DEPLOYED_INDEX_ENDPOINT_NAME: nome de exibição do endpoint do índice implantado.
• INDEX_ID: o ID do índice.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.

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)

Console

Use estas instruções para implantar o índice em um endpoint.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acessar a Vector Search

2. Uma lista dos índices ativos será exibida.
3. Selecione o nome do índice que você quer implantar. A página de detalhes do índice é aberta.
4. Na página de detalhes do índice, clique em Implantar no endpoint. O painel de implantação do índice será aberto.
5. Insira um nome de exibição. Ele funciona como um ID e não pode ser atualizado.
6. No menu suspenso Endpoint, selecione o endpoint em que você quer implantar esse índice. Observação: o endpoint ficará indisponível se o índice já estiver implantado nele.
7. Opcional: no campo Tipo de máquina, selecione "Padrão" ou "Alta memória".
8. Opcional. Selecione Ativar escalonamento automático para redimensionar automaticamente o número de nós com base nas demandas das cargas de trabalho. Se o escalonamento automático estiver desativado, o número padrão de réplicas será 2.
9. Clique em Implantar para implantar o modelo no endpoint. Observação: a implantação leva cerca de 30 minutos.

Importante: se você usar um endpoint público, será necessário usar a autenticação OAuth. Nesse caso, não especifique o deployedIndexAuthConfig, que é usado para a autenticação de endpoint particular.

Acessar o nome de domínio do índice

Depois de implantar o índice, você precisará do nome de domínio para poder usá-lo em uma consulta on-line. O valor está disponível em 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}

Exemplo de resposta

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

Ativar o escalonamento automático

O Vector Search oferece suporte ao escalonamento automático, que pode redimensionar automaticamente o número de nós com base nas demandas das cargas de trabalho. Quando a demanda é alta, os nós são adicionados ao pool de nós (não excedem o tamanho máximo designado). Quando a demanda é baixa, o pool de nós volta para um tamanho mínimo designado por você. Para verificar os nós reais em uso e as alterações, monitore as réplicas atuais.

Para ativar o escalonamento automático, especifique maxReplicaCount e minReplicaCount ao implantar o índice:

gcloud

O exemplo a seguir usa o comando gcloud ai index-endpoints deploy-index.

Antes de usar os dados do comando abaixo, faça estas substituições:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• DEPLOYED_INDEX_ID: uma string especificada pelo usuário para identificar de maneira exclusiva o índice implantado. Ela precisa começar com uma letra e conter apenas letras, números ou sublinhados. Consulte DeployedIndex.id para ver as diretrizes de formato.
• DEPLOYED_INDEX_NAME: nome de exibição do índice implantado.
• INDEX_ID: o ID do índice.
• MIN_REPLICA_COUNT: o número mínimo de réplicas de máquina em que o índice será implantado sempre. Se especificado, o valor precisa ser igual ou maior que 1.
• MAX_REPLICA_COUNT: número máximo de réplicas de máquina em que o índice pode ser implantado.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• DEPLOYED_INDEX_ID: uma string especificada pelo usuário para identificar de maneira exclusiva o índice implantado. Ela precisa começar com uma letra e conter apenas letras, números ou sublinhados. Consulte DeployedIndex.id para ver as diretrizes de formato.
• DEPLOYED_INDEX_NAME: nome de exibição do índice implantado.
• INDEX_ID: o ID do índice.
• MIN_REPLICA_COUNT: o número mínimo de réplicas de máquina em que o índice será implantado sempre. Se especificado, o valor precisa ser igual ou maior que 1.
• MAX_REPLICA_COUNT: número máximo de réplicas de máquina em que o índice pode ser implantado.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Console

Só é possível ativar o escalonamento automático no console durante a implantação do índice.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acessar a Vector Search

2. Uma lista dos índices ativos será exibida.
3. Selecione o nome do índice que você quer implantar. A página de detalhes do índice é aberta.
4. Na página de detalhes do índice, clique em Implantar no endpoint. O painel de implantação do índice será aberto.
5. Insira um nome de exibição. Ele funciona como um ID e não pode ser atualizado.
6. No menu suspenso Endpoint, selecione o endpoint em que você quer implantar esse índice. Observação: o endpoint ficará indisponível se o índice já estiver implantado nele.
7. Opcional: no campo Tipo de máquina, selecione "Padrão" ou "Alta memória".
8. Opcional. Selecione Ativar escalonamento automático para redimensionar automaticamente o número de nós com base nas demandas das cargas de trabalho. Se o escalonamento automático estiver desativado, o número padrão de réplicas será 2.

• Se minReplicaCount e maxReplicaCount não estiverem definidos, eles serão definidos como 2 por padrão.
• Se apenas maxReplicaCount for definido, minReplicaCount será definido como 2 por padrão.
• Se apenas minReplicaCount estiver definido, maxReplicaCount será definido como igual a minReplicaCount.

Observação: o Google recomenda que DeployedIndex use pelo menos duas réplicas por fragmento. Para isso, defina minReplicaCount como 2.

Modificar um DeployedIndex

Use a API MutateDeployedIndex para atualizar os recursos de implantação (por exemplo, minReplicaCount e maxReplicaCount) de um índice já implantado.

• Os usuários não terão permissão para alterar o machineType após a implantação do índice.
• Se maxReplicaCount não for especificado na solicitação, o DeployedIndex continuará usando o maxReplicaCount já existente.

gcloud

O exemplo a seguir usa o comando gcloud ai index-endpoints mutate-deployed-index.

Antes de usar os dados do comando abaixo, faça estas substituições:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• DEPLOYED_INDEX_ID: uma string especificada pelo usuário para identificar de maneira exclusiva o índice implantado. Ela precisa começar com uma letra e conter apenas letras, números ou sublinhados. Consulte DeployedIndex.id para ver as diretrizes de formato.
• MIN_REPLICA_COUNT: o número mínimo de réplicas de máquina em que o índice será implantado sempre. Se especificado, o valor precisa ser igual ou maior que 1.
• MAX_REPLICA_COUNT: número máximo de réplicas de máquina em que o índice pode ser implantado.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• DEPLOYED_INDEX_ID: uma string especificada pelo usuário para identificar de maneira exclusiva o índice implantado. Ela precisa começar com uma letra e conter apenas letras, números ou sublinhados. Consulte DeployedIndex.id para ver as diretrizes de formato.
• MIN_REPLICA_COUNT: o número mínimo de réplicas de máquina em que o índice será implantado sempre. Se especificado, o valor precisa ser igual ou maior que 1.
• MAX_REPLICA_COUNT: número máximo de réplicas de máquina em que o índice pode ser implantado.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Observação: o Google recomenda que DeployedIndex use pelo menos duas réplicas por fragmento. Para isso, defina minReplicaCount como 2.

Configurações de implantação que afetam o desempenho

As configurações de implantação a seguir podem afetar a latência, a disponibilidade e o custo ao usar a pesquisa de vetor. Essa orientação se aplica à maioria dos casos. No entanto, sempre teste as configurações para garantir que elas funcionem com seu caso de uso.

Configuração	Impacto no desempenho
Tipo de máquina	A seleção de hardware tem uma interação direta com o tamanho do fragmento selecionado. Dependendo das opções de fragmento especificadas no momento da criação do índice, cada tipo de máquina oferece uma compensação entre desempenho e custo. Consulte a página de preços para determinar o hardware disponível e o preço. Em geral, o desempenho aumenta na seguinte ordem: E2 padrão E2 highmem N1 padrão N2D padrão
Contagem mínima de réplicas	O minReplicaCount reserva uma capacidade mínima de disponibilidade e latência para garantir que o sistema não tenha problemas de inicialização a frio quando o tráfego escalonar verticalmente e com rapidez os níveis baixos. Se você tem cargas de trabalho que caem para níveis baixos e depois aumentam rapidamente para níveis mais altos, defina minReplicaCount como um número que possa acomodar os bursts iniciais de tráfego.
Contagem máxima de réplicas	maxReplicaCount permite principalmente controlar o custo de uso. É possível evitar o aumento dos custos além de um determinado limite, mas permitindo o aumento da latência e reduzindo a disponibilidade.

Listar IndexEndpoints

Para listar os recursos do IndexEndpoint e visualizar as informações de qualquer instância de DeployedIndex associada, execute o código:

gcloud

O exemplo a seguir usa o comando gcloud ai index-endpoints list.

Antes de usar os dados do comando abaixo, faça estas substituições:

• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Console

Use estas instruções para conferir uma lista dos endpoints de índice.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acesse a Pesquisa de vetor

2. Na parte de cima da página, selecione a guia Endpoint de índice.
3. Todos os endpoints de índice atuais serão exibidos.

Para saber mais, consulte a documentação de referência para IndexEndpoint.

Cancelar a implantação de um índice

Para desfazer a implantação de um índice de um endpoint, execute o seguinte código:

gcloud

O exemplo a seguir usa o comando gcloud ai index-endpoints undeploy-index.

Antes de usar os dados do comando abaixo, faça estas substituições:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• DEPLOYED_INDEX_ID: uma string especificada pelo usuário para identificar de maneira exclusiva o índice implantado. Ela precisa começar com uma letra e conter apenas letras, números ou sublinhados. Consulte DeployedIndex.id para ver as diretrizes de formato.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• DEPLOYED_INDEX_ID: uma string especificada pelo usuário para identificar de maneira exclusiva o índice implantado. Ela precisa começar com uma letra e conter apenas letras, números ou sublinhados. Consulte DeployedIndex.id para ver as diretrizes de formato.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
 "deployed_index_id": "DEPLOYED_INDEX_ID"
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Console

Use estas instruções para cancelar a implantação de um índice de um endpoint.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acessar a Vector Search

2. Uma lista dos índices ativos será exibida.
3. Selecione o índice que você quer desfazer a implantação. A página de detalhes do índice é aberta.
4. Na seção Índices implantados, identifique a versão do índice que você quer remover.
5. Clique no menu de opções que está na mesma linha do índice e selecione Cancelar a implantação.
6. Uma tela de confirmação será aberta. Clique em Cancelar a implantação. Observação: pode levar até 30 minutos para que a implantação seja cancelada.

Observação: leva de 10 a 20 minutos para que os jobs de back-end do Google limpem a implantação. Não é possível reutilizar o ID do DeployedIndex até que a implantação seja limpa.

Excluir um IndexEndpoint

Antes de excluir um IndexEndpoint, é preciso undeploy de todos os índices implantados no endpoint.

gcloud

O exemplo a seguir usa o comando gcloud ai index-endpoints delete.

Antes de usar os dados do comando abaixo, faça estas substituições:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

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

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• INDEX_ENDPOINT_ID: o ID do endpoint do índice.
• LOCATION: a região em que você está usando a Vertex AI.
• PROJECT_ID: o ID do projeto do Google Cloud.
• PROJECT_NUMBER: o número do projeto gerado automaticamente.

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Console

Use estas instruções para deletar um endpoint de índice.

1. Na seção Vertex AI do console do Google Cloud, acesse a seção Implantar e usar. Selecione Pesquisa de vetor

   Acesse a Pesquisa de vetor

2. Na parte de cima da página, selecione a guia Endpoint de índice.
3. Todos os endpoints de índice atuais serão exibidos.
4. Clique no menu de opções que está na mesma linha do índice que você quer excluir e selecione Excluir.
5. Uma tela de confirmação será aberta. Clique em Excluir. Seu endpoint de índice foi excluído.

Observação: leva de 10 a 20 minutos para que os jobs de back-end do Google limpem a implantação. Não é possível reutilizar o ID do DeployedIndex até que a implantação seja limpa.