Usar o mecanismo de correspondência da Vertex AI

Neste guia, explicamos como configurar e usar o Vertex AI Matching Engine para realizar pesquisas de similaridade vetorial.

Configurar uma conexão de peering de redes VPC

Para reduzir a latência da rede nas consultas on-line de correspondência de vetores, chame os endpoints do serviço do Vertex AI da sua nuvem privada virtual (VPC) usando o Acesso privado a serviços. Para cada projeto do Google Cloud, apenas uma rede VPC pode ser pareada com o Matching Engine. Se você já tiver uma VPC com acesso particular a serviços configurado, use-a para fazer peering com o Vertex AI Matching Engine.

A configuração de uma conexão de peering de redes VPC é uma tarefa inicial obrigatória somente uma vez por projeto do Google Cloud. Após a conclusão dessa configuração, é possível fazer chamadas para o índice do mecanismo de correspondência a partir de qualquer cliente em execução na VPC.

A conexão de peering de redes VPC é obrigatória somente para consultas on-line de correspondência vetorial. As chamadas de API para criar, implantar e excluir índices não exigem uma conexão de peering de rede VPC.

As etapas a seguir são concluídas pelo administrador do projeto do Cloud ou pelo administrador da rede:

  1. Para configurar seus projetos do Cloud, ativar o faturamento e ativar APIs, siga as etapas Antes de começar.

  2. Para evitar conflitos de endereço IP entre sua rede VPC e a rede do produtor de serviços, você precisa alocar um intervalo de endereços IP para o serviço do Mecanismo de comparação em que os índices do Mecanismo de correspondência são implantados. Para mais informações, consulte Como alocar intervalos de endereços IP.

    # Note: `prefix-length=16` means a CIDR block with mask /16 is reserved for
    # use by Google services. Make sure to enable the Service Networking API.
    gcloud compute addresses create $PEERING_RANGE_NAME \
        --global \
        --prefix-length=16 \
        --description="peering range for Matching Engine service" \
        --network=$NETWORK_NAME \
        --purpose=VPC_PEERING \
        --project=$PROJECT_ID
    
    # Create the VPC connection.
    gcloud services vpc-peerings connect \
        --service=servicenetworking.googleapis.com \
        --network=$NETWORK_NAME \
        --ranges=$PEERING_RANGE_NAME \
        --project=$PROJECT_ID
    

Depois de criar uma conexão particular, você pode fazer chamadas on-line para um índice do Mecanismo de correspondência em qualquer instância de máquina virtual (VM, na sigla em inglês) em execução na VPC com peering.

Notebook de exemplo

Depois de concluir a configuração inicial do peering de rede VPC, crie uma instância de notebooks gerenciados pelo usuário nessa VPC e execute comandos no notebook.

Iniciar o notebook de exemplo no Vertex AI Workbench ou visualizar o notebook no GitHub.

Controle de acesso com o IAM

A Vertex AI usa o Identity and Access Management (IAM) para gerenciar o acesso aos recursos. Para conceder acesso a um recurso, atribua um ou mais papéis a um usuário, um grupo ou uma conta de serviço.

Para usar o Matching Engine, use estes papéis predefinidos para conceder níveis variados de acesso aos recursos no nível do projeto.

Estrutura e formato dos dados de entrada

Para criar um novo índice ou atualizar um índice existente, forneça vetores ao Matching Engine no formato e na estrutura descritos nas seções a seguir.

Armazenamento de dados de entrada

Armazene os dados de entrada em um bucket do Cloud Storage no projeto do Cloud.

Estrutura de diretórios de entrada

Estruture seu diretório de dados de entrada da seguinte maneira:

  • Diretório raiz do lote: crie um diretório raiz para cada lote de arquivos de dados de entrada. Use um único diretório do Cloud Storage como diretório raiz. No exemplo a seguir, o diretório raiz é denominado batch_root.
  • Nomenclatura de arquivos: coloque arquivos de dados individuais diretamente em batch_root e nomeie-os usando o sufixo .csv, .json ou .avro, dependendo de em qual formato de arquivo você usa.

    • O Matching Engine interpreta cada arquivo de dados como um conjunto de registros.

      O formato do registro é determinado pelo sufixo do nome do arquivo e é descrito em uma das seções a seguir.

    • Cada registro precisa ter um código e um vetor de recurso, opcionalmente com campos adicionais, como restrições e agrupamento.

  • Excluir diretório: é possível criar um subdiretório delete em batch_root. Esse diretório é opcional.

    • Cada arquivo diretamente em batch_root/delete é um arquivo de texto de códigos de registro, com um código em cada linha. Cada ID precisa ser uma string UTF-8 válida.
  • Todos os outros diretórios e arquivos são ignorados.

  • Todos os registros de todos os arquivos de dados, incluindo aqueles em delete, compõem um único lote de entrada. A ordem relativa dos registros em um arquivo de dados é imaterial.

  • Um único código pode aparecer apenas uma vez por lote.

    • Observação: um código não pode aparecer em um arquivo de dados comum e em um arquivo de dados delete.
  • Todos os IDs de um arquivo de dados em delete são removidos da próxima versão do índice. Os registros de arquivos de dados regulares estão incluídos na próxima versão, podendo substituir um valor em uma versão de índice anterior.

Formatos de arquivo de dados

Os arquivos de dados podem estar no formato CSV, JSON ou Avro.

CSV

  • Codifique o arquivo usando UTF-8.
  • Torne cada linha um CSV válido a ser interpretado como um único registro.
  • Transforme o primeiro valor em id e o id em uma string UTF-8 válida.
  • Faça com que os próximos N valores a dimensão do vetor de atributo, que é configurado ao criar um índice. Torne cada valor um literal de ponto flutuante, conforme definido na especificação da linguagem Java.

JSON

  • Codifique o arquivo usando UTF-8.
  • Torne cada linha um objeto JSON válido para ser interpretado como um registro.
  • Inclua em cada registro um campo chamado id que exija uma string UTF-8 válida que seja o ID do vetor.
  • Inclua em cada registro um campo chamado embedding que requer uma matriz de números. Este é o vetor do recurso.

AVRO

  • Use um arquivo Avro válido.
  • Faça registros que estejam em conformidade com o seguinte esquema:

    {
      "type": "record",
      "name": "FeatureVector",
      "fields": [
        {
          "name": "id",
          "type": "string"
        },
        {
          "name": "embedding",
          "type": {
            "type": "array",
            "items": "float"
          }
        },
        {
          "name": "restricts",
          "type": [
            "null",
            {
              "type": "array",
              "items": {
                "type": "record",
                "name": "Restrict",
                "fields": [
                  {
                    "name": "namespace",
                    "type": "string"
                  },
                  {
                    "name": "allow",
                    "type": [
                      "null",
                      {
                        "type": "array",
                        "items": "string"
                      }
                    ]
                  },
                  {
                    "name": "deny",
                    "type": [
                      "null",
                      {
                        "type": "array",
                        "items": "string"
                      }
                    ]
                  }
                ]
              }
            }
          ]
        },
        {
          "name": "crowding_tag",
          "type": [
            "null",
            "string"
          ]
        }
      ]
    }
    

Gerenciar índices

As seções a seguir descrevem como criar, excluir ou atualizar índices. Para mais informações, consulte os documentos da API sobre índices.

Arquivo de metadados do índice

Antes de criar um índice, é preciso configurar os parâmetros do seu índice.

Por exemplo, crie um arquivo chamado index_metadata.json:

{
  "contentsDeltaUri": "gs://BUCKET_NAME/path",
  "config": {
    "dimensions": 100,
    "approximateNeighborsCount": 150,
    "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
    "algorithm_config": {
      "treeAhConfig": {
        "leafNodeEmbeddingCount": 500,
        "leafNodesToSearchPercent": 7
      }
    }
  }
}

Encontre a definição para cada um desses campos em Como configurar índices ou veja as definições no seguinte esquema:

title: NearestNeighborSearch
type: object
properties:
  contentsDeltaUri:
    type: string
    description: >
      Allows inserting, updating  or deleting the contents of the Matching Engine Index.
      The string must be a valid Cloud Storage directory path. If this
      field is set when calling IndexService.UpdateIndex, then no other
      Index field can be also updated as part of the same call.
      The expected structure and format of the files this URI points to is
      described at https://cloud.google.com/vertex-ai/docs/matching-engine/using-matching-engine#input-data-format
    writeOnly: true
  isCompleteOverwrite:
    type: boolean
    description: >
      If this field is set together with contentsDeltaUri when calling IndexService.UpdateIndex,
      then existing content of the Index will be replaced by the data from the contentsDeltaUri.
    default: false
  config:
    type: object
    description: >
      The configuration of the Matching Engine Index.
    required:
    - dimensions
    - algorithmConfig
    properties:
      dimensions:
        type: integer
        format: int32
        description: >
          The number of dimensions of the input vectors.
      approximateNeighborsCount:
        type: integer
        format: int32
        description: >
          The default number of neighbors to find via approximate search before exact reordering is
          performed. Exact reordering is a procedure where results returned by an
          approximate search algorithm are reordered via a more expensive distance computation.
          Required if tree-AH algorithm is used.
      distanceMeasureType:
        description: >
          The distance measure used in nearest neighbor search.
        oneOf:
        - enum: [SQUARED_L2_DISTANCE]
          description: >
            Euclidean (L_2) Distance
        - enum: [L1_DISTANCE]
          description: >
            Manhattan (L_1) Distance
        - enum: [COSINE_DISTANCE]
          description: >
            Cosine Distance. Defined as 1 - cosine similarity.
        - enum: [DOT_PRODUCT_DISTANCE]
          description: >
            Dot Product Distance. Defined as a negative of the dot product
        default: DOT_PRODUCT_DISTANCE
      featureNormType:
        description: >
          Type of normalization to be carried out on each vector.
        oneOf:
        - enum: [UNIT_L2_NORM]
          description: >
            Unit L2 normalization type.
        - enum: [NONE]
          description: >
            No normalization type is specified.
        default: NONE
      algorithmConfig:
        description: >
          The configuration with regard to the algorithms used for efficient search.
        oneOf:
        - type: object
          description: >
             Configuration options for using the tree-AH algorithm (Shallow tree + Asymmetric Hashing).
             Please refer to this paper for more details: https://arxiv.org/abs/1908.10396
          properties:
            type:
              type: string
              enum: [treeAhConfig]
            leafNodeEmbeddingCount:
              type: integer
              format: int64
              description: >
                 Number of embeddings on each leaf node. The default value is 1000 if not set.
            leafNodesToSearchPercent:
              type: number
              format: int32
              description: >
                 The default percentage of leaf nodes that any query may be searched. Must be in
                 range 1-100, inclusive. The default value is 10 (means 10%) if not set.
        - type: object
          description: >
             Configuration options for using brute force search, which simply implements the
             standard linear search in the database for each query.
          properties:
            type:
              type: string
              enum: [bruteForceConfig]
        discriminator:
          propertyName: type

Este arquivo de esquema de metadados está disponível para download no Cloud Storage.

Criar um índice

Para criar um índice:

gcloud

  1. Defina os metadados do índice.
  2. Use o comando gcloud ai indexes create :
gcloud ai indexes create \
  --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
  --display-name=INDEX_NAME \
  --project=PROJECT_ID \
  --region=LOCATION

Substitua:

  • LOCAL_PATH_TO_METADATA_FILE: o caminho do arquivo local para o arquivo de metadados.
  • INDEX_NAME: nome de exibição do índice.
  • PROJECT_ID: o ID do projeto
  • LOCATION: a região em que você está usando a Vertex AI.

REST e LINHA DE CMD

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • INDEX_NAME: nome de exibição do índice.
  • INPUT_DIR: o caminho do diretório do Cloud Storage do conteúdo do índice.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes

Corpo JSON da solicitação:

{
  "display_name": "INDEX_NAME",
  "metadata": {
    "contentsDeltaUri": "INPUT_DIR",
    "config": {
      "dimensions": 100,
      "approximateNeighborsCount": 150,
      "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
      "algorithm_config": {
        "treeAhConfig": {
          "leafNodeEmbeddingCount": 500,
          "leafNodesToSearchPercent": 7
        }
      }
    }
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T01:21:10.147035Z",
      "updateTime": "2022-01-08T01:21:10.147035Z"
    }
  }
}
Pesquise o status da operação até que a resposta inclua "done": true.

Listar índices

gcloud

Use o comando gcloud ai indexes list :

gcloud ai indexes list \
  --project=PROJECT_ID \
  --region=LOCATION

Substitua:

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

REST e LINHA DE CMD

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • INDEX_NAME: nome de exibição do índice.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes

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

Você receberá uma resposta JSON semelhante a esta:

{
  "indexes": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID",
      "displayName": "INDEX_NAME",
      "metadataSchemaUri": "gs://google-cloud-aiplatform/schema/matchingengine/metadata/nearest_neighbor_search_1.0.0.yaml",
      "metadata": {
        "config": {
          "dimensions": 100,
          "approximateNeighborsCount": 150,
          "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
          "featureNormType": "NONE",
          "algorithmConfig": {
            "treeAhConfig": {
              "maxLeavesToSearch": 50,
              "leafNodeCount": 10000
            }
          }
        }
      },
      "etag": "AMEw9yNU8YX5IvwuINeBkVv3yNa7VGKk11GBQ8GkfRoVvO7LgRUeOo0qobYWuU9DiEc=",
      "createTime": "2020-11-08T21:56:30.558449Z",
      "updateTime": "2020-11-08T22:39:25.048623Z"
    }
  ]
}

Atualizar conteúdo do índice

Para atualizar o conteúdo de um Index existente, use o método IndexService.UpdateIndex.

Para substituir o conteúdo existente de um Index:

  • Defina Index.metadata.contentsDeltaUri como o URI do Cloud Storage que inclui os vetores que você quer atualizar.
  • isCompleteOverwrite: definido como verdadeiro

Se você definir o campo contentsDeltaUri ao chamar IndexService.UpdateIndex, nenhum outro campo de índice (como displayName, description ou userLabels) também serão atualizados como parte da mesma chamada.

gcloud

  1. Atualize o arquivo de metadados de índices.
  2. Use o comando gcloud ai indexes update :
gcloud ai indexes update INDEX_ID \
  --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
  --project=PROJECT_ID \
  --region=LOCATION

Substitua:

  • INDEX_ID: o ID do índice.
  • LOCAL_PATH_TO_METADATA_FILE: o caminho do arquivo local para o arquivo de metadados.
  • PROJECT_ID: o ID do projeto
  • LOCATION: a região em que você está usando a Vertex AI.

REST e LINHA DE CMD

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • INPUT_DIR: o caminho do diretório do Cloud Storage do conteúdo do índice.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes/INDEX_ID

Corpo JSON da solicitação:

{
  "metadata": {
    "contentsDeltaUri": "INPUT_DIR",
    "isCompleteOverwrite": true
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UpdateIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-12T23:56:14.480948Z",
      "updateTime": "2022-01-12T23:56:14.480948Z"
    }
  }
}
Pesquise o status da operação até que a resposta inclua "done": true.

Se o Index tiver implantações associadas (consulte o campo Index.deployed_indexes), quando certas alterações no Index original estiverem sendo feitas, o DeployedIndex é atualizado de forma assíncrona em segundo plano para refletir essas alterações.

Para verificar se a alteração foi propagada, compare o horário de término da operação de índice de atualização e o DeployedIndex.index_sync_time.

Excluir um índice

Não é possível excluir o Index até que toda a implantação de Index.deployed_indexes seja cancelada.

gcloud

Use o comando gcloud ai indexes delete :

gcloud ai indexes delete INDEX_ID \
  --project=PROJECT_ID \
  --region=LOCATION

Substitua:

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

REST e LINHA DE CMD

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • INDEX_ID: o ID do índice.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/indexes/INDEX_ID

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T02:35:56.364956Z",
      "updateTime": "2022-01-08T02:35:56.364956Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Implantar e gerenciar índices

A implantação de um índice inclui as três tarefas a seguir:

  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 na sua rede VPC.

Se você estiver implantando um Index em um IndexEndpoint, pule esta etapa.

Antes de usar um índice para exibir consultas de correspondência de vetores on-line, é preciso implantar o Index em um IndexEndpoint na Rede de peering de rede VPC. A primeira etapa é criar um IndexEndpoint. É possível implantar mais de um índice em um IndexEndpoint que compartilha a mesma rede VPC.

gcloud

O exemplo a seguir usa o comando gcloud ai index-endpoints create:

gcloud ai index-endpoints create \
  --display-name=INDEX_ENDPOINT_NAME \
  --network=VPC_NETWORK_NAME \
  --project=PROJECT_ID \
  --region=LOCATION

Substitua:

  • INDEX_ENDPOINT_NAME: nome de exibição do endpoint do índice.
  • VPC_NETWORK_NAME: o nome da rede do Google Compute Engine em que o endpoint do índice precisa ser pareado.
  • PROJECT_ID: o ID do projeto
  • LOCATION: a região em que você está usando a Vertex AI.

A ferramenta de linha de comando gcloud pode levar alguns minutos para criar o IndexEndpoint.

REST e LINHA DE CMD

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • INDEX_ENDPOINT_NAME: nome de exibição do endpoint do índice.
  • VPC_NETWORK_NAME: o nome da rede do Google Compute Engine em que o endpoint do índice precisa ser pareado.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "display_name": "INDEX_ENDPOINT_NAME",
  "network": "VPC_NETWORK_NAME"
}

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

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.

Implantar um índice

gcloud

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

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

Substitua:

  • INDEX_ENDPOINT_ID: o ID do endpoint do índice.
  • DEPLOYED_INDEX_ID: o ID do índice implantado.
  • DEPLOYED_INDEX_NAME: nome de exibição do índice implantado.
  • INDEX_ID: o ID do índice.
  • PROJECT_ID: o ID do projeto
  • LOCATION: a região em que você está usando a Vertex AI.

REST e LINHA DE CMD

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: o ID ou o número do projeto;
  • INDEX_ENDPOINT_ID: o ID do endpoint do índice.
  • DEPLOYED_INDEX_ID: o ID do índice implantado.
  • DEPLOYED_INDEX_NAME: nome de exibição do índice implantado.
  • INDEX_ID: o ID do índice.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/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"
  }
}
Pesquise o status da operação até que a resposta inclua "done": true.

Ativar o escalonamento automático

O Matching Engine é compatível com o 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:

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 \
  --project=PROJECT_ID \
  --region=LOCATION

Substitua:

  • INDEX_ENDPOINT_ID: o ID do endpoint do índice.
  • DEPLOYED_INDEX_ID: o ID do índice implantado.
  • 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.
  • PROJECT_ID: o ID do projeto
  • LOCATION: a região em que você está usando a Vertex AI.

REST e LINHA DE CMD

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: o ID ou o número do projeto;
  • INDEX_ENDPOINT_ID: o ID do endpoint do índice.
  • DEPLOYED_INDEX_ID: o ID do índice implantado.
  • 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.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "deployedIndex": {
    "id": "DEPLOYED_INDEX_ID",
    "index": "projects/PROJECT/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:

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/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"
  }
}
Pesquise o status da operação até que a resposta inclua "done": true.
  • 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.

Mudar 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 têm permissão para mudar o machineType depois que o índice é implantado.
  • Se maxReplicaCount não for especificado na solicitação, o DeployedIndex continuará usando a maxReplicaCount atual.

gcloud

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

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 \
  --project=PROJECT_ID \
  --region=LOCATION

Substitua:

  • INDEX_ENDPOINT_ID: o ID do endpoint do índice.
  • DEPLOYED_INDEX_ID: o ID do índice implantado.
  • 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.
  • PROJECT_ID: o ID do projeto
  • LOCATION: a região em que você está usando a Vertex AI.

REST e LINHA DE CMD

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: o ID ou o número do projeto;
  • INDEX_ENDPOINT_ID: o ID do endpoint do índice.
  • DEPLOYED_INDEX_ID: o ID do índice implantado.
  • 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.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "id": "DEPLOYED_INDEX_ID",
  "automaticResources": {
    "minReplicaCount": MIN_REPLICA_COUNT,
    "maxReplicaCount": MAX_REPLICA_COUNT
  }
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.MutateDeployedIndexOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-24T20:36:37.902782Z",
      "updateTime": "2022-01-24T20:36:37.902782Z"
    },
    "deployedIndexId": "gcloud_deployed_index_2"
  }
}
Pesquise o status da operação até que a resposta inclua "done": true.

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:

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

Substitua:

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

REST e LINHA DE CMD

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

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

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

Você receberá uma resposta JSON semelhante a esta:

{
  "indexEndpoints": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID",
      "displayName": "INDEX_ENDPOINT_NAME",
      "deployedIndexes": [
        {
          "id": "DEPLOYED_INDEX_ID",
          "index": "projects/PROJECT_NUMBER/locations/LOCATION/indexes/INDEX_ID",
          "displayName": "DEPLOYED_INDEX_ID",
          "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"
    }
  ]
}

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

Cancelar a implantação de um índice

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

gcloud

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

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

Substitua:

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

REST e LINHA DE CMD

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • INDEX_ENDPOINT_ID: o ID do endpoint do índice.
  • DEPLOYED_INDEX_ID: o ID do índice implantado.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/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:

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

Excluir um IndexEndpoint

Antes de excluir um IndexEndpoint, remova a implantação de todos os índices associados a ele.

gcloud

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

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

Substitua:

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

REST e LINHA DE CMD

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

  • LOCATION: Sua região.
  • PROJECT: o ID ou o número do projeto;
  • INDEX_ENDPOINT_ID: o ID do endpoint do índice.
  • PROJECT_NUMBER: número do seu projeto (aparece na resposta).

Método HTTP e URL:

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

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

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

Consultar índices para ver vizinhos mais próximos

Cada DeployedIndex tem um DEPLOYED_INDEX_SERVER_IP, que pode ser recuperado listando IndexEndpoints. Para consultar um DeployedIndex, conecte-se ao DEPLOYED_INDEX_SERVER_IP na porta 10000 e chame o método MatchRequest ou BatchMatchRequest.

O exemplo a seguir usa grpc_cli:

./grpc_cli call ${DEPLOYED_INDEX_SERVER_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "", requests: [{deployed_index_id: "", float_val: [-0.1,..]}, {deployed_index_id: "", float_val: [-0.1,..]}]}]'

Faça chamadas para essas APIs a partir de um cliente em execução na mesma VPC com que o serviço fez peering.

Para mais informações sobre como construir as consultas, inicie um notebook de amostra e execute-o no Vertex AI Workbench.

Como ajustar o índice

O ajuste do índice requer a configuração dos parâmetros de configuração que afetam o desempenho dos índices implantados, especialmente o recall e a latência. Esses parâmetros são definidos quando o índice é criado. Você pode usar índices de força bruta para avaliar o recall.

Parâmetros de configuração que afetam o recall e a latência

  1. distanceMeasureType

    Os valores a seguir são compatíveis:

    • SQUARED_L2_DISTANCE - Distância euclidiana L2
    • L1_DISTANCE - Distância de Manhattan L1
    • COSINE_DISTANCE - Distância de cosseno definida como '1 similarity similaridade de cosseno'
    • DOT_PRODUCT_DISTANCE - Distância do produto vDot, definida como um negativo do produto escalar. Esse é o valor padrão.

    Na maioria dos casos, os vetores de incorporação usados para correspondência por similaridade são calculados usando modelos de aprendizado métrico (também chamados de redes Siamese ou modelos de duas torres). Esses modelos usam uma métrica de distância para calcular a função de perda contrastante. O ideal é que o valor do parâmetro distanceMeasureType do índice correspondente corresponda à medida de distância usada pelo modelo que produziu os vetores de incorporação.

  2. approximateNeighborsCount

    O número padrão de vizinhos a ser encontrado usando a pesquisa aproximada antes de executar a reordenação exata. A reordenação exata é um procedimento em que os resultados retornados por um algoritmo de pesquisa aproximado são reordenados por meio de um cálculo de distância mais caro. Aumentar esse valor aumenta o recall, o que pode criar um aumento proporcional na latência.

  3. treeAhConfig.leafNodesToSearchPercent

    A porcentagem de saídas a serem pesquisadas cada consulta. Aumentar esse valor aumenta o recall, o que também pode criar um aumento proporcional na latência. O valor padrão é 10 ou 10% das folhas.

  4. treeAhConfig.leafNodeEmbeddingCount

    O número de embeddings para cada nó de folha. Por padrão, esse número é definido como 1000.

    Este parâmetro não tem uma correlação linear a ser recuperada. Aumentar ou diminuir o valor do parâmetro treeAhConfig.leafNodeEmbeddingCount nem sempre aumenta ou diminui o recall. Faça testes para encontrar o valor ideal. Alterar o valor do parâmetro treeAhConfig.leafNodeEmbeddingCount geralmente tem menos efeito do que mudar o valor dos outros parâmetros.

Como usar um índice de força bruta para medir o recall

Para ver os vizinhos mais próximos, use índices com o algoritmo de força bruta. O algoritmo de força bruta fornece 100% de recall em detrimento da maior latência. Usar um índice de força bruta para medir o recall geralmente não é uma boa escolha para a exibição de produção, mas pode ser útil avaliar o recall de várias opções de indexação off-line.

Para criar um índice com o algoritmo de força bruta, especifique brute_force_config nos metadados do índice:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \
-d '{
    displayName: "'${DISPLAY_NAME}'",
    description: "'${DESCRIPTION}'",
    metadata: {
       contentsDeltaUri: "'${INPUT_DIR}'",
       config: {
          dimensions: 100,
          approximateNeighborsCount: 150,
          distanceMeasureType: "DOT_PRODUCT_DISTANCE",
          featureNormType: "UNIT_L2_NORM",
          algorithmConfig: {
             bruteForceConfig: {}
          }
       },
    },
}'

O notebook de exemplo mostra como usar um índice de força bruta para medir o recall.

Monitorar o IndexEndpoint

O Google fornece duas métricas para monitorar IndexEndpoint:

  • aiplatform.googleapis.com/matching_engine/current_shards

    O número de fragmentos de DeployedIndex. data medida que os dados são adicionados e excluídos, o Matching Engine refragmenta automaticamente o índice para atingir o desempenho ideal. Essa métrica indica o número atual de fragmentos do índice implantado.

  • aiplatform.googleapis.com/matching_engine/current_replicas

    O número total de servidores de réplica ativos que estão sendo usados pelo DeployedIndex. Para corresponder ao volume de consultas, o Matching Engine aumenta ou diminui automaticamente os servidores de réplica com base nas configurações mínima e máxima de réplica especificadas ao implantar o índice.

    Se o índice tiver vários fragmentos, cada um deles poderá ser veiculado usando um número diferente de servidores de réplica. Essa métrica é o número total de servidores de réplica em todos os fragmentos do índice especificado.

Saiba como selecionar, consultar e exibir essas métricas no Metrics Explorer.

Cotas

Saiba mais sobre as cotas do Vertex AI Matching Engine e como solicitar aumento de cota.

Perguntas frequentes

Quantos endereços IP é preciso reservar?

Se não houver restrições no intervalo de IP que pode ser alocado, recomendamos que você reserve um intervalo de IPs grande, como /16, para evitar um problema de esgotamento de IP no futuro.

Se você não quiser alocar os intervalos de IP em excesso, faça uma estimativa aproximada com base no tamanho dos dados e no tráfego. Cada fragmento pode hospedar cerca de 20 GB de dados no formato Avro e cada réplica do fragmento pode exibir cerca de 800 a 1.000 consultas por segundo (QPS). O qps preciso que cada réplica pode atender depende, por exemplo, do tamanho de incorporação, dimensões e configurações de algoritmo. Recomendamos que você faça um teste de carga para determinar um número preciso.

O número total de nós de índice implantados necessários é (o número de fragmentos * o número de réplicas por fragmento). Por exemplo, se o tamanho dos dados for 30 GB e o QPS for 1.200, você precisará de pelo menos 2 fragmentos e 2 réplicas por fragmento, o total de 4 nós de índice implantados.

Depois de estimar o total de nós de índice implantados, será possível escolher o prefixo do intervalo de IP com base na tabela a seguir:

Total de nós de índice implantados Prefixo IP reservado recomendado
1 - 10 /21
11 - 25 /20
26 - 50 /19
51 - 120 /18

Como resolvo um erro de IP esgotado?

Para resolver um erro de IP esgotado, conclua as seguintes etapas:

  1. Verifique se há códigos Deploy não utilizados e cancele a implantação para liberar alguns espaços de IP.

  2. Expanda intervalos de IP reservados existentes ou aloque mais intervalos de IP.

Para mais informações, consulte Exaustão do intervalo de endereços IP.

Por que não posso reutilizar o ID do índice implantado quando o DeployedIndex anterior é cancelado?

A limpeza do UndeployIndex requer pelo menos 10 a 20 minutos para ser concluída mesmo depois de receber uma confirmação de operação bem-sucedida. Recomendamos que você aguarde de 10 a 20 minutos antes de reutilizar o mesmo ID ou use um ID diferente.

Como receber suporte

Se você tiver um problema ao usar o Matching Engine, há duas maneiras de receber suporte. Nos dois casos, inclua os detalhes a seguir na sua comunicação:

  • O ID do projeto.
  • O comando ou código que você executou e acionou o problema.
  • O ambiente em que você executou o comando ou o código. Por exemplo, você o executou em uma instância do Compute Engine ou em um computador local?
  • O comportamento observado e como ele difere do que você esperava.

Criar um tíquete do Cloud Customer Care

Se você tiver um pacote de atendimento ao cliente, conseguirá registrar um tíquete de suporte. Para informações sobre como receber um pacote do Cloud Customer Care, consulte Customer Care.

  1. No Console do Google Cloud, acesse a página Casos.

    Acessar "Casos"

  2. Clique em Criar caso.

    • No campo Título, digite Matching Engine serving.
    • No campo Categoria, selecione Machine learning.
    • No campo Componente, selecione Vertex AI Matching Engine.
    • No campo Descrição, insira as informações solicitadas e responda às perguntas.
    • Clique em Enviar.

envie um e-mail;

Se você não tiver um pacote de atendimento ao cliente, envie uma mensagem para o seguinte endereço de e-mail:

gcp-ann-feedback@google.com

A seguir