Usar o Vertex Matching Engine

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

Configurar conexão de peering de rede VPC

Para reduzir a latência da rede em consultas on-line de correspondência vetorial, chame os endpoints do serviço Vertex AI da sua VPC por meio do 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 Matching Engine.

Configurar uma conexão de peering de rede VPC é uma tarefa inicial obrigatória apenas uma vez por projeto do Google Cloud. Após a conclusão dessa configuração, é possível fazer chamadas para o índice do Matching Engine 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.

Peça ao administrador do projeto ou ao administrador da rede do Google Cloud para concluir estas etapas:

  1. Siga estas etapas para configurar seus projetos do Google Cloud, ativar o faturamento e ativar as APIs.

  2. Antes de criar uma conexão particular, é preciso alocar um intervalo de endereços IP que será usado pelo Matching Engine. Isso garante que não haja colisão de endereços IP entre sua rede VPC e a rede do produtor de serviços em que os índices do mecanismo de correspondência são implantados. Veja mais documentos aqui.

    # NOTE: `prefix-length=16` means a CIDR block with mask /16 will be reserved
    # for use by Google services. Make sure to enable 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
    

Notebook de exemplo

Depois de concluir a configuração inicial do peering de rede VPC, crie uma instância de notebooks nessa VPC e execute comandos a partir do notebook.

Inicie o exemplo de notebook no Notebooks ou visualize o notebook no GitHub.

Controle de acesso

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.

Formato e estrutura dos dados de entrada

Nesta seção, descrevemos a estrutura e o formato em que os vetores precisam ser fornecidos ao Matching Engine, seja para criar um novo índice ou para atualizar um índice existente.

Armazenamento de dados de entrada

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

Estrutura de diretórios de entrada

Nesta seção, explicamos como estruturar o diretório de dados de entrada.

  • Diretório raiz do lote: crie um diretório raiz para cada lote de arquivos de dados de entrada. Precisa ser um único diretório do Cloud Storage, chamado batch_root neste exemplo.
  • Nomenclatura de arquivos: coloque arquivos de dados individuais diretamente em batch_root e nomeie-os com os seguintes sufixos: .csv, .json ou .avro, dependendo do formato de arquivo que 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 lotação.

  • 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 só deve aparecer uma vez em um lote.

    • Observação: um código também não pode aparecer em um arquivo de dados comum e em um arquivo de dados delete.
  • Todos os códigos de um arquivo de dados em delete farão com que ele seja removido da próxima versão do índice. Os registros de arquivos de dados regulares serão incluídos na próxima versão, possivelmente substituindo um valor em uma versão de índice mais antiga.

Formatos de arquivo de dados

Esta seção descreve os requisitos de formato para cada arquivo de dados individual. Os arquivos de dados podem ser arquivos CSV, JSON ou Avro.

CSV

  • Codifique o arquivo usando UTF-8.
  • Cada linha precisa ser um CSV válido e será interpretada como um único registro.
  • O primeiro valor será o id. Ele deve ser uma string UTF-8 válida.
  • Os próximos N valores devem ser o vetor de atributo. N é a dimensão do vetor de recurso e deve ser configurada ao criar um índice. Cada valor precisa ser um literal de ponto flutuante, conforme definido na especificação da linguagem Java.

JSON

  • O arquivo precisa ser codificado usando UTF-8.
  • Cada linha precisa ser um objeto JSON válido, interpretado como um registro.
  • Cada registro precisa ter um campo chamado id, que é o ID do vetor. Ele deve ser uma string UTF-8 válida.
  • Cada registro precisa ter um campo chamado embedding e ser uma matriz de números. Este é o vetor do recurso.

AVRO

  • O arquivo precisa ser um Avro válido.
  • Os registros Avro precisam ter uma estrutura semelhante, conforme definido no formato JSON. Especificamente, ele precisa seguir o seguinte esquema:

    {
       "type": "record",
       "name": "FeatureVector",
       "fields": [
          {"name": "id", "type": "string"},
          {"name": "embedding",
           "type": {
              "type": "array",
              "items": "float"
            }
          }
       ]
    }
    

Gerenciar índices

Nesta seção, descrevemos como criar, excluir ou atualizar índices. 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:

  1. Definir os metadados do índice
  2. Envie a solicitação usando gcloud beta ai indexes create:

    gcloud beta ai indexes create \
      --display-name=INDEX_NAME \
      --description=test \
      --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
      --project=PROJECT_ID \
      --region=us-central1
    

Como alternativa, veja um exemplo de chamada da API curl com os metadados de índice transmitidos diretamente:

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",
          algorithm_config: {
          treeAhConfig: {
            leafNodeEmbeddingCount: 500,
            leafNodesToSearchPercent: 7
            }
          }
       }
    }
}'

Veja um exemplo de saída:

{
  "name": "projects/xxx/locations/us-central1/indexes/xxxx/operations/yyyy",
  "metadata": {...}
}

Analise a saída da operação e encontre a linha com "name": "projects/xxxx/locations/us-central1/indexes/xxx/operations/yyyy". A parte yyyy é o ID da operação. Pesquise a operação até que ela seja concluída. Aguarde até "done": true estar na resposta.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/xxxx/operations/yyyy"

Listar índices

Para listar índices, execute gcloud beta ai indexes list:

gcloud beta ai indexes list \
  --project=PROJECT_ID \
  --region=us-central1

Atualizar conteúdo do índice

Para atualizar o conteúdo de um índice atual, use o método IndexService.UpdateIndex.

Para substituir o conteúdo existente de uma 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 poderá ser atualizado. como parte da mesma chamada.

Veja um exemplo de chamada da API curl:

curl -X PATCH -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/${INDEX_ID} \
-d '{
   metadata: {
       contentsDeltaUri: "'${INPUT_DIR}'",
       isCompleteOverwrite: <true|false>
    },
}'

Da mesma forma que criar um índice, pesquise a operação retornada da chamada UpdateIndex até que ela seja concluída.

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

Não é possível excluir o Index até que a Index.deployed_indexes seja removida.

curl -X DELETE -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/${INDEX_ID}

Implantar e gerenciar índices

A implantação de um índice consiste nas 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.

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. Portanto, a primeira etapa é criar um IndexEndpoint. É possível implantar mais de um índice em um IndexEndpoint que compartilha a mesma rede VPC.

Veja um exemplo de chamada da API curl:

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/indexEndpoints \
-d '{
    display_name: "'${DISPLAY_NAME}'",
    network: "'${VPC_NETWORK_NAME}'",
}'

Veja um exemplo de saída:

{
  "name": "projects/xxx/locations/us-central1/indexEndpoints/xxxx/operations/yyyy",
  "metadata": {...}
}

Veja a saída da operação. Encontre a linha com "name": "projects/xxxx/locations/us-central1/indexEndpoints/xxx/operations/yyyy". A parte yyyy é o ID da operação. Pesquise a operação até que ela seja concluída. Aguarde até "done": true estar na resposta.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/xxxx/operations/yyyy"

Implantar um índice

Para implantar um índice:

curl -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/indexEndpoints/${INDEX_ENDPOINT_ID}:deployIndex \
-d '{
  deployedIndex: {
    id: "'${DEPLOYED_INDEX_ID}'",
    index: "'${INDEX_RESOURCE_NAME}'",
    displayName: "'${DISPLAY_NAME}'"
  }
}'

Assim como em outras operações, consiga o código da operação na resposta e use-o para pesquisar a operação até que ela seja concluída.

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:

curl -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/indexEndpoints/${INDEX_ENDPOINT_ID}:deployIndex \
-d '{
  deployedIndex: {
    id: "'${DEPLOYED_INDEX_ID}'",
    index: "'${INDEX_RESOURCE_NAME}'",
    displayName: "'${DISPLAY_NAME}'"
    automaticResources: {
      minReplicaCount: 2,
      maxReplicaCount: 5
    }
  }
}'
  • Se minReplicaCount e maxReplicaCount não estiverem definidos, eles serão definidos como 1 por padrão.
  • Se apenas maxReplicaCount for definido, minReplicaCount será definido como 1 por padrão.
  • Se apenas minReplicaCount estiver definido, maxReplicaCount será definido como igual a minReplicaCount.

Listar IndexEndpoints

Para listar seu IndexEndpoints e visualizar as informações de qualquer instância DeployedIndex associada, execute:

curl -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/indexEndpoints

Esta é a resposta:

{
  "indexEndpoints": [
    {
      "name": "projects/<ProjectId>/locations/us-central1/indexEndpoints/<IndexEndpoingId>",
      "displayName": "...",
      "deployedIndexes": [
        {
          "id": "<user specified deployed index id>",
          "index": "projects/<ProjectId>/locations/us-central1/indexes/<IndexId>",
          "displayName": "demo",
          "createTime": "2021-06-18T00:19:13.242212Z",
          "privateEndpoints": {
            "matchGrpcAddress": "10.29.2.5"
          },
          "indexSyncTime": "2021-08-13T19:52:48.671205Z",
          "automaticResources": {
            "minReplicaCount": 1,
            "maxReplicaCount": 1
          }
        }
        ...
      ],
      "etag": "AMEw9yP9cMX3cjWFRuyLqI6YbB2UQcb-OU3tMwx9_B2p_MUiMlsMKPWX5KCphr1vbyiv",
      "createTime": "2021-06-18T00:16:59.320793Z",
      "updateTime": "2021-06-18T00:16:59.850034Z",
      "network": "projects/<ProjectId>/global/networks/<NetworkId>"
    },
    ...
  ]
}

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

Cancelar a implantação de um índice

Para remover a implantação de um índice, execute:

curl -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/indexEndpoints/${INDEX_ENDPOINT_ID}:undeployIndex \
-d '{
  deployed_index_id: "'${DEPLOYED_INDEX_ID}'",
}'

Excluir um IndexEndpoint

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

curl -X DELETE -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/indexEndpoints/${INDEX_ENDPOINT_ID}

Consultar índices para ver vizinhos mais próximos

Cada DeployedIndex tem um DEPLOYED_INDEX_SERVER_IP que é possível recuperar listando o IndexEndpoints. Para consultar um DeployedIndex, conecte-se ao DEPLOYED_INDEX_SERVER_IP na porta 10000 e invoque 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: "<deployed index id 1>", requests: [{deployed_index_id: "<deployed index id 1>", float_val: [-0.1,..<your query input>]}, {deployed_index_id: "<deployed index id 1>", float_val: [-0.1,..<your query input>]}]}]'

As chamadas para essas APIs precisam ser feitas por um cliente em execução na mesma VPC com que o serviço esteve em peering.

É possível iniciar um notebook de exemplo com instruções adicionais sobre como construir as consultas e executá-las no Notebooks.

Como ajustar o índice

Nesta seção, descrevemos os parâmetros de configuração que afetam o desempenho, em especificamente recall e latência, dos índices implantados. Esses parâmetros são definidos quando o índice é criado. Também descreveremos como usar índices de força bruta para medir o recall.

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

1) 'distanceMeasureType'

Os valores compatíveis são:

  • 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 embedding usados para a correspondência por similaridade são calculados por meio de modelos de aprendizado de métrica (também chamados de "Siamese Networks" ou "Two-Tower Models"). Esses modelos usam uma métrica de distância para calcular a função de perda contrastante. O ideal é que o parâmetro distanceMeasureType para o índice correspondente corresponda à medida de distância usada pelo modelo que produziu os vetores de embedding.

2) approximateNeighborsCount

O número padrão de vizinhos que será encontrado por meio da pesquisa de aproximação antes da reordenação exata ser realizada. 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 aumentará o recall, mas também poderá ter um aumento proporcional na latência.

3) treeAhConfig.leafNodesToSearchPercent

A porcentagem de saídas a serem pesquisadas cada consulta. Aumentar esse valor aumentará o recall, mas também poderá ter um aumento proporcional na latência. O valor padrão é 10, o que significa que pesquisamos por 10% das folhas.

4) treeAhConfig.leafNodeEmbeddingCount

O número de embeddings para cada nó de folha. Por padrão, essa opção é definida como 1.000.

Este parâmetro não tem uma correlação linear a ser recuperada. Aumentar ou diminuir o valor nem sempre aumentará ou diminuirá o recall. Para cada caso de uso, geralmente há um ponto ideal que pode exigir alguma experimentação. No entanto, geralmente, o impacto desse parâmetro é menor do que o impacto dos outros parâmetros.

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

Os índices com o algoritmo de força bruta podem ser usados para conseguir os vizinhos mais próximos, o que dá 100% de recall à custa de uma latência maior. Isso geralmente não é uma boa escolha para exibição de produção, mas pode ser útil, por exemplo, para 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 demonstra como usar um índice de "Força bruta" para medir o recall.

Monitorar o IndexEndpoint

Fornecemos duas métricas para monitorar o 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 de réplicas ativas usadas pelo DeployedIndex. O Matching Engine ativa e reduz automaticamente os servidores de réplicas (sujeito às configurações de réplica mínima e máxima especificadas pelo usuário ao implantar o índice) para corresponder ao volume de consultas. Essa métrica indica o número total de servidores de réplica. Observe que, se o índice tiver vários fragmentos, cada um deles poderá ser veiculado usando um número diferente de réplicas. Essa métrica é o número total de réplicas em todos os fragmentos do índice fornecido.

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

Cotas

Saiba mais sobre as cotas do Vertex 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 seja possível alocar, recomendamos que você reserve um grande intervalo de IP, como /16, para evitar problemas de IP esgotado no futuro.

No entanto, 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 atender a cerca de 800~1k 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 descobrir o número exato. O total de nós de índice implantados é necessário (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 dois fragmentos e duas réplicas por fragmento, um total de quatro nós de índice implantados.

Depois de estimar o total de nós de índice implantados, é possível escolher o prefixo do intervalo de IP com base na tabela abaixo.

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

O que posso fazer se receber um erro de IP esgotado?

Primeiro, é possível verificar se há algum ImplantouIndex não utilizado e cancelar a implantação para liberar alguns espaços de IP.

Além disso, é possível ampliar intervalos de IP reservados existentes ou alocar mais intervalos de IP. Veja instruções detalhadas aqui.

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

Sempre retornamos uma operação bem-sucedida para UndeployIndex para que nossos clientes não precisem se preocupar com o tratamento de falhas de não implantação. No entanto, leva pelo menos de 10 a 20 minutos para que o job de limpeza subjacente seja concluído. Recomendamos que você aguarde de 10 a 20 minutos antes de reutilizar o mesmo ID ou usar um ID diferente.

Como receber suporte

Se você tiver um problema ao usar o Vertex 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 que 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 de suporte do Cloud

Se você tiver um pacote de suporte do Google, envie um tíquete de suporte. Para informações sobre como receber um pacote de suporte do Google, consulte Suporte do Google Cloud.

No Console do Cloud, navegue até Casos na seção Suporte e clique em Abrir caso.

  • Inclua "Veiculação do mecanismo correspondente" no campo Título.
  • Selecione "Machine Learing" como a Categoria.
  • Selecione "Vertex: outros" como Componente.
  • Coloque a frase "Mecanismo de correspondência Vertex" na parte superior do campo de descrição.
  • Preencha a descrição restante e os outros campos da melhor forma possível.

envie um e-mail;

Se você não tiver um pacote de suporte do Google, envie um e-mail para o seguinte endereço:

gcp-ann-feedback@google.com

A seguir