Esta página foi traduzida pela API Cloud Translation.

Configurar a Pesquisa vetorial com o Private Service Connect

O Private Service Connect permite o consumo privado de serviços em redes VPC que pertencem a diferentes grupos, equipes, projetos ou organizações. É possível publicar e consumir serviços usando endereços IP definidos por você e internos à sua rede VPC para que os endpoints do Vector Search realizem pesquisas de semelhança vetorial.

A ativação do Private Service Connect em um endpoint do Vector Search é adequada para casos de uso que:

Exigem baixa latência e uma conexão segura com os back-ends de exibição do Vector Search.
Têm espaço IP limitado para reservas exclusivas de peering de VPC.
É preciso acessar os back-ends de exibição em redes VPC de vários usuários.

Para saber mais sobre como configurar o Private Service Connect, consulte a Visão geral do Private Service Connect na documentação da nuvem privada virtual (VPC).

Criar o endpoint do índice

Para criar um endpoint com o Private Service Connect ativado, defina-o ao criar o endpoint. Isso é semelhante à criação de outros endpoints na Vertex AI.

REST

PROJECT: o projeto de serviço em que você está criando recursos da Vertex AI.

VPC_PROJECT: o projeto em que a VPC do cliente reside. Para a configuração independente da VPC, é o mesmo que $PROJECT. Para a configuração da VPC compartilhada, será o projeto host da VPC.

PROJECT=<your-service-project>
VPC_PROJECT=<your-vpc-project>
REGION=us-central1
VERTEX_ENDPOINT=$REGION-aiplatform.googleapis.com
curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  https://$VERTEX_ENDPOINT/v1/projects/$PROJECT/locations/$REGION/indexEndpoints \
  -d '{displayName: "<your-index-endpoint-name>", privateServiceConnectConfig:
  { enablePrivateServiceConnect: true, projectAllowlist: ["'$VPC_PROJECT'", "'$PROJECT'"] }}'

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_private_service_connect(
    project: str, location: str, display_name: str, project_allowlist: list[str]
) -> aiplatform.MatchingEngineIndexEndpoint:
    """Create a vector search index endpoint with Private Service Connect enabled.

    Args:
        project (str): Required. Project ID
        location (str): Required. The region name
        display_name (str): Required. The index endpoint display name
        project_allowlist (list[str]): Required. A list of projects from which
            the forwarding rule will be able to target the service attachment.

    Returns:
        aiplatform.MatchingEngineIndexEndpoint - The created index endpoint.
    """
    # Initialize the Vertex AI client
    aiplatform.init(project=project, location=location)

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

    return index_endpoint

Sobre as opções de implantação de índice

É possível implantar o índice com conectividade de serviço automática ou manual.

Implantar com a automação do Private Service Connect: configure uma política de conexão de serviço e implante seus índices. A configuração de uma política de conexão de serviço permite implantar em uma rede específica sem criar um endereço de computação e uma regra de encaminhamento a cada vez.
Implantar com conexão manual: implante seu índice e crie manualmente um endereço de computação e uma regra de encaminhamento. Escolha essa opção se precisar usar vários endereços IP.

Implantar com a automação do Private Service Connect

É possível configurar uma política de conexão de serviço para que você não precise criar manualmente um endereço de computação e uma regra de encaminhamento após cada implantação de índice.

Primeiro, crie uma política de conexão de serviço que especifique a rede, a classe de serviço e a região para implantar índices. Esta é uma configuração de uma só vez. Se você já fez isso, pule para o próximo procedimento.
Implantar o índice.

Limitações

A automação permite apenas um endereço IP por projeto e por rede. Se você precisar usar vários endereços IP, consulte Implantar o índice manualmente.

Criar uma política de conexão de serviço

Você precisa ser um administrador de rede para criar uma política de conexão de serviço para automatizar a implantação do índice.

Para automatizar a implantação de índices, siga estas etapas:

Crie sua política de conexão de serviço.
- PROJECT: o projeto de serviço em que você está criando recursos da Vertex AI.
- VPC_PROJECT: o projeto em que a VPC do cliente reside. Para a configuração simples da VPC, será o mesmo que $PROJECT. Para a configuração da VPC compartilhada, esse é o projeto host da VPC.
- NETWORK_NAME: o nome da rede a ser implantada, no formato projects//global/networks/.
- REGION: a região da rede.
- PSC_SUBNETS: a sub-rede do Private Service Connect a ser usada.
```
gcloud network-connectivity service-connection-policies create <policy_name> \
--project=<vpc_project> --network=<network_name> # in the format projects/<project_id>/global/networks/<network_name> \
--service-class=gcp-vertexai --region=<region> --subnets=<psc subnets>
```

Acesse a política de conexão de serviço.

gcloud network-connectivity service-connection-policies list --project=<vpc_project> -–region=<region>

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_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.
NETWORK_1: o nome da rede do Compute Engine em que o endpoint do índice será implantado.
NETWORK_2: (opcional) um nome de rede do Compute Engine adicional para implantar este endpoint.

Execute o seguinte comando:

Linux, macOS ou 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 \
    --psc-automation-configs=project-id=PROJECT_ID,network=NETWORK_1 \
    --psc-automation-configs=project-id=PROJECT_ID,network=NETWORK_2

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 `
    --psc-automation-configs=project-id=PROJECT_ID,network=NETWORK_1 `
    --psc-automation-configs=project-id=PROJECT_ID,network=NETWORK_2

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 ^
    --psc-automation-configs=project-id=PROJECT_ID,network=NETWORK_1 ^
    --psc-automation-configs=project-id=PROJECT_ID,network=NETWORK_2

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.
NETWORK_1: o nome da rede do Compute Engine em que o endpoint do índice será implantado.
NETWORK_2: (opcional) um nome de rede do Compute Engine adicional para implantar este endpoint.
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"
   "psc_automation_configs": [
          {"project_id": "PROJECT_ID", "network": "NETWORK_1"},
          {"project_id": "PROJECT_ID", "network": "NETWORK_2" }]
 }
}

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_psc_automation_index(
    project: str,
    location: str,
    index_name: str,
    index_endpoint_name: str,
    deployed_index_id: str,
    psc_automation_configs: Sequence[Tuple[str, str]],
) -> None:
    """Deploy a vector search index to an index endpoint using PSC automation.

    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.
        psc_automation_config (Sequence[Tuple[str, str]]): Required. A list of
          (project_id, network) pairs where PSC endpoints will be setup for the
          deployed index. Example:
          [("123", "{projects/123/global/networks/my-network1"),
          ("123", "{projects/123/global/networks/my-network2")]
    """
    # 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 with PSC automation enabled.
    index_endpoint.deploy_index(
        index=index,
        deployed_index_id=deployed_index_id,
        psc_automation_configs=psc_automation_configs,
    )

Excluir política de conexão de serviço

Se você precisar excluir a política de conexão de serviço, execute o seguinte comando:

gcloud network-connectivity service-connection-policies delete --project=<vpc_project> –-region=<region> <policy_name>

Implantar com conexão manual

Implante o índice e crie uma regra de encaminhamento no projeto VPC.

Implantar o índice

Agora que o índice está pronto, nesta etapa, implante o índice no endpoint criado com o Private Service Connect ativado.

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

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

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)

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)

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 seu índice.

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
Uma lista dos índices ativos será exibida.
Selecione o nome do índice que você quer implantar. A página de detalhes do índice é aberta.
Na página de detalhes do índice, clique em Implantar no endpoint. O painel de implantação do índice será aberto.
Insira um nome de exibição. Ele funciona como um ID e não pode ser atualizado.
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.
Opcional: no campo Tipo de máquina, selecione "Padrão" ou "Alta memória".
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.
Clique em Implantar para implantar o modelo no endpoint. Observação: a implantação leva cerca de 30 minutos.

Criar uma regra de encaminhamento no projeto VPC

Após a conclusão da implantação do índice, o endpoint do índice retorna um URI de anexo de serviço em vez de um endereço IP. Você precisa criar um endereço de computação e uma regra de encaminhamento no projeto de VPC direcionado ao anexo de serviço usando o endereço de computação criado. Para criar um endereço de computação, use o exemplo a seguir:

gcloud compute addresses create ${ADDRESS_NAME:?} \
    --region=${REGION:?} \
    --subnet=${SUBNET_NAME:?} \
    --project=${VPC_PROJECT:?}

Para criar uma regra de encaminhamento que segmenta o URI do anexo de serviço usando o endereço de computação criado, use o exemplo a seguir:

SERVICE_ATTACHMENT_URI=`gcloud ai index-endpoints describe {INDEX_ENDPOINT_ID}
--format="value(deployedIndexes.privateEndpoints.serviceAttachment)"`

gcloud compute forwarding-rules create ${ENDPOINT_NAME:?} \
    --network=${NETWORK_NAME:?} \
    --address=${ADDRESS_NAME:?} \
    --target-service-attachment=${SERVICE_ATTACHMENT_URI:?} \
    --project=${VPC_PROJECT:?} \
    --region=${REGION:?}

(Opcional) Criar um registro DNS para o endereço IP

Se você quiser se conectar e carregar sem memorizar o endereço IP real, crie um registro DNS. Esta etapa é opcional.

DNS_NAME_SUFFIX=matchingengine.vertexai.goog. # Don't forget the "." in the end.
DNS_NAME=${INDEX_ENDPOINT_ID:?}.${REGION:?}.${DNS_NAME_SUFFIX:?}

gcloud dns managed-zones create ${DNS_ZONE_NAME:?} \
    --dns-name=${DNS_NAME_SUFFIX:?} \
    --visibility=private \
    --project=${VPC_PROJECT:?} \
    --region=${REGION:?}

gcloud dns record-sets create ${DNS_NAME:?} \
    --rrdatas=${IP_ADDRESS:?} \
    --type=A --ttl=60 \
    --zone=${DNS_ZONE_NAME:?} \
    --project=${VPC_PROJECT:?} \
    --region=${REGION:?}

Enviar consultas para o endpoint do índice

Agora que você criou um endpoint com o Private Service Connect e criou o índice, é possível começar a executar consultas.

Para consultar o índice, acesse Consultar índices para saber os vizinhos mais próximos.

A seguir

Saiba como atualizar e recriar o índice
Saiba como monitorar o endpoint do índice