Configure 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, equipas, projetos e organizações. Pode publicar e consumir serviços através de endereços IP que define e que são internos à sua rede da VPC, e para que os pontos finais da pesquisa vetorial realizem pesquisas de similaridade vetorial.

A ativação do Private Service Connect num ponto final do Vector Search é adequada para exemplos de utilização que:

  1. Exigir baixa latência e uma ligação segura aos back-ends de serviço da pesquisa vetorial.
  2. Ter espaço de IP limitado para a reserva de peering de VPC exclusivo.
  3. Precisa de aceder aos back-ends de publicação a partir de várias redes VPC do utilizador.

Para saber como configurar o Private Service Connect, aceda ao artigo Vista geral do Private Service Connect na documentação da Virtual Private Cloud (VPC).

Crie o ponto final do índice

Tem de ativar o Private Service Connect quando criar o ponto final. Este procedimento é semelhante à criação de outros pontos finais no Vertex AI.

REST

  • PROJECT: o ID do projeto de serviço onde está a criar recursos do Vertex AI.

  • REGION: a região da rede.

  • DISPLAY_NAME: um nome a apresentar para atribuir ao ponto final. Este nome é usado para criar um ID para o ponto final e não pode ser atualizado posteriormente.

  • VPC_PROJECTS: para a configuração da VPC partilhada, esta é uma lista separada por vírgulas de projetos anfitriões da VPC. Para a configuração de VPC autónoma, isto é o mesmo que PROJECT.

PROJECT=PROJECT_ID
VPC_PROJECT=VPC_PROJECT_ID
REGION=us-central1
VERTEX_ENDPOINT=REGION-aiplatform.googleapis.com
curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/REGION/indexEndpoints \
  -d '{
     "displayName": "DISPLAY_NAME",
     "privateServiceConnectConfig": {
       "enablePrivateServiceConnect": true,
       "projectAllowlist": [ "VPC_PROJECT_1", "VPC_PROJECT_2", "VPC_PROJECT_N"]
     }
   }

Consola

Para criar o seu ponto final:

  1. Clique no botão seguinte para aceder à pesquisa vetorial na Google Cloud consola. É apresentada uma lista dos seus índices ativos.

    Aceda à Vector Search

  2. Selecione o separador Index endpoints. São apresentados os pontos finais do índice.

  3. Clique em Criar novo ponto final. É aberto o painel Criar um novo ponto final de índice.

  4. Em Nome a apresentar, introduza um nome a apresentar para o ponto final do índice. Este nome é usado para criar um ID para o ponto final e não pode ser atualizado posteriormente.

  5. Selecione uma região no menu pendente Região.

  6. Em Acesso, clique em Private Service Connect (pré-visualização).

  7. É apresentado um campo de texto onde pode especificar os projetos de VPC a usar. Adicione os IDs ou os números dos projetos de VPC que quer usar.

  8. Clique em Criar.

Acerca das opções de implementação de índices

Pode implementar o seu índice com conetividade de serviço automática ou manual.

  • Implemente com a automatização do Private Service Connect: configure uma política de ligação de serviço e implemente os seus índices. A configuração de uma política de ligação de serviço permite-lhe implementar numa rede específica sem criar um endereço de computação e uma regra de encaminhamento de cada vez.
  • Implementação com associação manual: implemente o seu índice e crie manualmente um endereço de computação e uma regra de encaminhamento. Pode escolher esta opção se precisar de usar vários endereços IP para o mesmo URI de anexo de serviço, embora não seja um exemplo de utilização comum.

Implemente com a automatização do Private Service Connect

Pode configurar uma política de ligação de serviço para não ter de criar manualmente um endereço de computação e uma regra de encaminhamento após cada implementação de índice.

  1. Primeiro, crie uma política de ligação de serviço que especifique a rede, a classe de serviço e a região para implementar os índices. Esta é uma configuração única. Se já o tiver feito, avance para o procedimento seguinte.
  2. Implemente o índice.

Limitações

A automatização permite apenas um endereço IP por projeto por rede. Se precisar de usar vários endereços IP, consulte o artigo Implemente o índice manualmente.

Crie uma política de ligação de serviço

Tem de ser um administrador de rede para criar uma política de ligação de serviço para automatizar a implementação do índice.

Para automatizar a implementação do índice, siga estes passos:

  1. Crie a política de ligação do serviço.

    • PROJECT: O projeto de serviço onde está a criar recursos da Vertex AI.

    • VPC_PROJECT: o projeto onde se encontra a sua VPC do cliente. Para a configuração de uma única VPC, é igual a $PROJECT. Para a configuração da VPC partilhada, este é o projeto anfitrião da VPC.

    • NETWORK_NAME: o nome da rede para a qual fazer a implementação, no formato projects//global/networks/.

    • REGION: a região da rede.

    • PSC_SUBNETS: as sub-redes do Private Service Connect a usar.

    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>

  2. Veja a sua política de ligação de serviços.

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

Para mais informações sobre as políticas de ligação de serviços, aceda a Configure as políticas de ligação de serviços.

Implemente o índice

REST

  • PROJECT: O projeto de serviço onde está a criar recursos da Vertex AI.

  • VPC_PROJECT: o projeto onde se encontra a sua VPC do cliente. Para a configuração da VPC partilhada, este é o projeto anfitrião da VPC.

  • DISPLAY_NAME: um nome a apresentar para atribuir ao ponto final. Este nome é usado para criar um ID para o ponto final e não pode ser atualizado posteriormente.

  • NETWORK_NAME: o nome da rede para a qual fazer a implementação, no formato projects//global/networks/.

  • REGION: a região da rede.

  • PSC_SUBNETS: a sub-rede do Private Service Connect a usar.

PROJECT=PROJECT
VPC_PROJECTS=VPC_PROJECTS
REGION=REGION
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json; charset=utf-8" "https://LOCATIONAL_ENDPOINT.googleapis.com/v1/projects/PROJECT_NUMBER/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:deployIndex"
-d '{
  "deployedIndex": {
    "id": "DEPLOYED_INDEX_ID",
    "index": "projects/PROJECT/locations/us-central1/indexes/INDEX_ID ",
    "displayName": "DISPLAY_NAME",
    "psc_automation_configs": [
      { "project_id": "PROJECT_1", "network": "NETWORK_NAME_1" },
      { "project_id": "PROJECT_2", "network": "NETWORK_NAME_2" },
      { "project_id": "PROJECT_N", "network": "NETWORK_NAME_N" }]
    }
}'

Consola

Para implementar o seu ponto final:

  1. Clique no botão seguinte para aceder à pesquisa vetorial na Google Cloud consola. É apresentada uma lista dos seus índices ativos.

    Aceda à Vector Search

  2. Clique no botão Implementar para o ponto final de pesquisa vetorial ativado para o Private Service Connect que quer implementar. É apresentado o painel deslizante Implementar índice.

  3. Em Nome a apresentar, introduza um nome a apresentar para o índice implementado. Este nome é usado para criar o ID e não pode ser atualizado posteriormente.

  4. Clique em Ponto final e escolha o ponto final do índice para o qual quer fazer a implementação.

  5. Opcionalmente, clique em Tipo de máquina para escolher manualmente o tipo de máquina para implementar o índice. Por predefinição, o tipo de máquina é selecionado automaticamente com base no tamanho do fragmento do índice.

Agora, tem de adicionar configurações de automatização do Private Service Connect. Para isso:

  1. Na secção Configurações de automatização do PSC, clique em Adicionar nova configuração.

  2. Introduza o nome do projeto da VPC ao qual se quer ligar.

  3. Introduza o nome da rede do projeto da VPC ao qual se quer ligar. Tem de estar no formato projects/<project_number>/global/networks/<network_name>.

  4. Opcionalmente, clique em Adicionar nova configuração e continue a adicionar configurações de automatização do Private Service Connect.

  5. Clique em Implementar para concluir.

Elimine a política de ligação de serviço

Se precisar de eliminar a política de ligação de serviço, execute o seguinte comando:

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

Para mais informações sobre as políticas de ligação de serviços, aceda a Configure as políticas de ligação de serviços.

Implemente com uma associação manual

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

Implemente o índice

Agora que o índice está pronto, neste passo, implementa o índice no ponto final que criou com o Private Service Connect ativado.

gcloud

Este exemplo usa o comando gcloud ai index-endpoints deploy-index.

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • INDEX_ENDPOINT_ID: o ID do ponto final do índice.
  • DEPLOYED_INDEX_ID: uma string especificada pelo utilizador para identificar exclusivamente o índice implementado. Tem de começar com uma letra e conter apenas letras, números ou carateres de sublinhado. Consulte DeployedIndex.id para ver as diretrizes de formato.
  • DEPLOYED_INDEX_ENDPOINT_NAME: nome a apresentar do ponto final do índice implementado.
  • INDEX_ID: o ID do índice.
  • LOCATION: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu Google Cloud ID do projeto.

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 qualquer um dos dados do pedido, faça as seguintes substituições:

  • INDEX_ENDPOINT_ID: o ID do ponto final do índice.
  • DEPLOYED_INDEX_ID: uma string especificada pelo utilizador para identificar exclusivamente o índice implementado. Tem de começar com uma letra e conter apenas letras, números ou carateres de sublinhado. Consulte DeployedIndex.id para ver as diretrizes de formato.
  • DEPLOYED_INDEX_ENDPOINT_NAME: nome a apresentar do ponto final do índice implementado.
  • INDEX_ID: o ID do índice.
  • LOCATION: a região onde está a usar o Vertex AI.
  • PROJECT_ID: o seu Google Cloud ID do projeto.
  • PROJECT_NUMBER: o número do projeto gerado automaticamente para o seu projeto.

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

Terraform

O exemplo seguinte usa o recurso do Terraform vertex_ai_index_endpoint_deployed_index para criar um ponto final do índice implementado.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

provider "google" {
  region = "us-central1"
}

resource "google_vertex_ai_index_endpoint_deployed_index" "default" {
  depends_on        = [google_vertex_ai_index_endpoint.default]
  index_endpoint    = google_vertex_ai_index_endpoint.default.id
  index             = google_vertex_ai_index.default.id
  deployed_index_id = "deployed_index_for_psc"
}

resource "google_vertex_ai_index_endpoint" "default" {
  display_name = "sample-endpoint"
  description  = "A sample index endpoint with Private Service Connect enabled"
  region       = "us-central1"
  private_service_connect_config {
    enable_private_service_connect = true
    project_allowlist = [
      data.google_project.project.project_id,
    ]
  }
}

data "google_project" "project" {}

# Cloud Storage bucket name must be unique
resource "random_id" "default" {
  byte_length = 8
}

# Create a Cloud Storage bucket
resource "google_storage_bucket" "bucket" {
  name                        = "vertex-ai-index-bucket-${random_id.default.hex}"
  location                    = "us-central1"
  uniform_bucket_level_access = true
}

# Create index content
resource "google_storage_bucket_object" "data" {
  name    = "contents/data.json"
  bucket  = google_storage_bucket.bucket.name
  content = <<EOF
{"id": "42", "embedding": [0.5, 1.0], "restricts": [{"namespace": "class", "allow": ["cat", "pet"]},{"namespace": "category", "allow": ["feline"]}]}
{"id": "43", "embedding": [0.6, 1.0], "restricts": [{"namespace": "class", "allow": ["dog", "pet"]},{"namespace": "category", "allow": ["canine"]}]}
EOF
}

resource "google_vertex_ai_index" "default" {
  region       = "us-central1"
  display_name = "sample-index-batch-update"
  description  = "A sample index for batch update"
  labels = {
    foo = "bar"
  }

  metadata {
    contents_delta_uri = "gs://${google_storage_bucket.bucket.name}/contents"
    config {
      dimensions                  = 2
      approximate_neighbors_count = 150
      distance_measure_type       = "DOT_PRODUCT_DISTANCE"
      algorithm_config {
        tree_ah_config {
          leaf_node_embedding_count    = 500
          leaf_nodes_to_search_percent = 7
        }
      }
    }
  }
  index_update_method = "BATCH_UPDATE"

  timeouts {
    create = "2h"
    update = "1h"
  }
}

Python

Para saber como instalar ou atualizar o SDK Vertex AI para Python, consulte o artigo Instale o SDK Vertex AI para Python. Para mais informações, consulte a Python documentação de referência da 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)

Consola

Siga estas instruções para implementar o seu índice.

  1. Na secção do Vertex AI da Google Cloud consola, aceda à secção Implementar e usar. Selecione Vector Search.

    Aceda a Vector Search. É apresentada uma lista dos seus índices ativos.

  2. Selecione o nome do índice que quer implementar. É apresentada a página de detalhes do índice.
  3. Na página de detalhes do índice, clique em Implementar no ponto final. É aberto o painel de implementação do índice.
  4. Introduza um nome a apresentar. Este nome funciona como um ID e não pode ser atualizado.
  5. No menu pendente Ponto final, selecione o ponto final no qual quer implementar este índice. Nota: o ponto final não está disponível se o índice já estiver implementado no mesmo.
  6. Opcional: no campo Tipo de máquina, selecione padrão ou memória elevada.
  7. Opcional. Selecione Ativar o dimensionamento automático para redimensionar automaticamente o número de nós com base nas exigências das suas cargas de trabalho. O número predefinido de réplicas é 2 se o dimensionamento automático estiver desativado.
  8. Clique em Implementar para implementar o índice no ponto final. Nota: a implementação demora cerca de 30 minutos.

Crie uma regra de encaminhamento no projeto de VPC

Após a implementação do índice, o ponto final do índice devolve um URI de anexo de serviço em vez de um endereço IP. Tem de criar um endereço de computação, bem como uma regra de encaminhamento no projeto de VPC que tenha como destino a associação de serviço, usando o endereço de computação criado. Para criar um endereço de cálculo, use o exemplo seguinte:

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 com o endereço de computação criado, use o exemplo seguinte:

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) Crie um registo DNS para o endereço IP

Se quiser estabelecer ligação e carregar sem memorizar o endereço IP real, pode criar um registo DNS. Este passo é 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:?}

Envie consultas para o ponto final do índice

Agora que criou um ponto final com o Private Service Connect e criou o índice, pode começar a executar consultas.

Para consultar o seu índice, consulte o artigo Consulte índices para obter os vizinhos mais próximos.

O que se segue?