Pesquisar usando embeddings

Para instâncias de armazenamento on-line criadas para exibição on-line otimizada, é possível realizar uma pesquisa por similaridade vetorial para recuperar uma lista de objetos semanticamente parecidos ou relacionados também chamadas de vizinhos mais próximos. É possível pesquisar com base em um ID de entidade ou em um embedding.

Dependendo do tipo de endpoint configurado para sua instância de loja on-line, você pode fazer uma das seguintes ações:

Antes de começar

Para pesquisar vizinhos mais próximos aproximados, primeiro você precisa fazer o seguinte:

  • Configure a fonte de dados do BigQuery para oferecer suporte a embeddings, incluindo a coluna embedding. Opcionalmente, inclua filtros e agrupamento de colunas. Para mais informações, consulte Diretrizes de preparação de fontes de dados.

  • Crie uma instância de loja on-line para veiculação on-line otimizada.

  • Crie uma visualização de recursos que ofereça suporte a embeddings associando diretamente a fonte de dados do BigQuery. Ao criar a visualização do elemento, especifique a coluna embedding. Para mais informações sobre como criar uma visualização de recurso compatível com embeddings, consulte Configurar a recuperação de vetor para uma visualização de recurso.

  • Se você quiser pesquisar correspondências de vizinhos mais próximos usando um endpoint do Private Service Connect, instale ou faça upgrade para a versão mais recente do SDK do Python. Execute este comando:
    pip3 install --upgrade --quiet google-cloud-aiplatform

  • Siga estas instruções para fazer a autenticação na Vertex AI, a menos que já tenha feito isso.

    Select the tab for how you plan to use the samples on this page:

    Python

    Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

      Instale a CLI do Google Cloud.

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

      If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    Confira mais informações em Set up authentication for a local development environment.

    REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      Instale a CLI do Google Cloud.

      Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

    Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud .

Pesquisar correspondências de vizinhos mais próximos usando um endpoint público

Se você configurou a instância da loja on-line para veicular valores de atributos usando a veiculação on-line otimizada de um endpoint público, faça o seguinte para recuperar correspondências aproximadas de vizinhos mais próximos:

  1. Recuperar o nome de domínio do endpoint público da loja on-line

  2. Recuperar correspondências de vizinhos mais próximos de um embedding ou entidade.

Recuperar o nome de domínio do endpoint público da loja on-line

Ao criar uma instância de loja on-line para veiculação on-line otimizada, O Feature Store da Vertex AI gera endpoint para o armazenamento on-line. Antes de começar a pesquisar vizinhos mais próximos em uma visualização de recursos na loja on-line, recupere o nome de domínio do endpoint público nos detalhes da loja on-line.

Use o exemplo a seguir para recuperar os detalhes de uma instância de loja on-line.

REST

Para recuperar os detalhes de umFeatureOnlineStore recurso em seu projeto, envie umGET usando a featureOnlineStores.get.

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

  • LOCATION_ID: região em que a loja on-line está localizada, como us-central1.
  • PROJECT_ID: o ID do projeto.
  • FEATUREONLINESTORE_NAME: o nome da instância da loja on-line.

Método HTTP e URL: 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

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

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1",
  "createTime": "2023-09-06T23:25:04.256314Z",
  "updateTime": "2023-09-06T23:25:04.256314Z",
  "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=",
  "state": "STABLE",
  "dedicatedServingEndpoint": {
    "publicEndpointDomainName": "PUBLIC_ENDPOINT_DOMAIN_NAME"
  },
  "optimized": {}
}

Você precisará do PUBLIC_ENDPOINT_DOMAIN_NAME da resposta para recuperar os vizinhos mais próximos próximos na etapa a seguir.

Recuperar vizinhos mais próximos aproximados usando um endpoint público

Depois de recuperar o nome de domínio do endpoint público da loja on-line, você pode usá-lo para pesquisar vizinhos mais próximos aproximados de um embedding ou entidade.

Recuperar vizinhos mais próximos aproximados de um embedding

Use o exemplo a seguir para pesquisar entidades semanticamente relacionadas especificando um embedding ao usar um endpoint público.

REST

Para pesquisar um embedding nos vizinhos mais próximos, envie uma solicitação POST usando o método featureViews.searchNearestEntities.

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

  • PUBLIC_ENDPOINT_DOMAIN_NAME: o nome de domínio do endpoint público da instância de loja on-line recuperada usando o método featureOnlineStores.get.
  • PROJECT_ID: o ID do projeto.
  • LOCATION_ID: região em que a instância da loja on-line está localizada, como us-central1.
  • FEATUREONLINESTORE_NAME: o nome da instância da loja on-line que contém a visualização do recurso em que você quer pesquisar correspondências aproximadas de vizinhos mais próximos.
  • FEATUREVIEW_NAME: o nome da visualização do elemento onde você quer pesquisar correspondências aproximadas de vizinhos mais próximos.
  • EMBEDDING: embedding para o qual você quer recuperar correspondências vizinhas mais próximas. Um embedding é representado por uma matriz de valores double.
  • RETURN_FULL_ENTITY (opcional): especifica se você quer incluir ou excluir os recursos das entidades na resposta. Para incluir os recursos com as entidades na resposta, digite true. O valor padrão é false.
  • NEIGHBOR_COUNT: número de vizinhos mais próximos aproximados que você quer recuperar.

Método HTTP e URL: 

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

Corpo JSON da solicitação:

{
  "query": {
    "embedding": {
      "value": EMBEDDING
    },
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

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

curl

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

PowerShell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}

Recuperar vizinhos mais próximos de uma entidade

Use o exemplo a seguir para pesquisar entidades semanticamente relacionadas especificando um ID de entidade ao usar um endpoint público.

REST

Para pesquisar um ID de entidade nos vizinhos mais próximos, envie uma solicitação POST usando o método featureViews.searchNearestEntities.

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

  • PUBLIC_ENDPOINT_DOMAIN_NAME: o nome de domínio do endpoint público da instância de loja on-line recuperada usando o método featureOnlineStores.get.
  • PROJECT_ID: o ID do projeto.
  • LOCATION_ID: região em que a instância da loja on-line está localizada, como us-central1.
  • FEATUREONLINESTORE_NAME: o nome da instância da loja on-line que contém a visualização do recurso em que você quer pesquisar correspondências aproximadas de vizinhos mais próximos.
  • FEATUREVIEW_NAME: o nome da visualização do elemento onde você quer pesquisar correspondências aproximadas de vizinhos mais próximos.
  • ENTITY_ID: ID da entidade para a qual você quer recuperar correspondências vizinhas mais próximas.
  • RETURN_FULL_ENTITY (opcional): especifica se você quer incluir ou excluir os recursos das entidades na resposta. Para incluir os recursos com as entidades na resposta, digite true. O valor padrão é false.
  • NEIGHBOR_COUNT: número de vizinhos mais próximos aproximados que você quer recuperar.

Método HTTP e URL: 

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

Corpo JSON da solicitação:

{
  "query": {
    "entity_id": ENTITY_ID,
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

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

curl

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

PowerShell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}

Pesquisar correspondências de vizinho mais próximo usando um endpoint do Private Service Connect

Se você configurou a instância da loja on-line para veicular valores de atributos usando a veiculação on-line otimizada de um endpoint do Private Service Connect, faça o seguinte para recuperar correspondências aproximadas de vizinhos mais próximos:

  1. Recupere a string de anexo de serviço da loja on-line.

  2. Adicione um endpoint do Private Service Connect à configuração de sua rede.

  3. Conecte-se ao endpoint do Private Service Connect por gRPC.

  4. Recuperar correspondências de vizinhos mais próximos de um embedding ou entidade.

Recupere a string de anexo de serviço da loja on-line

Quando você cria uma instância de loja on-line para disponibilização on-line otimizada com um endpoint do Private Service Connect, o Feature Store da Vertex AI gera uma string de anexo de serviço. Você pode recuperar a string de anexo de serviço nos detalhes da loja on-line e usá-la para configurar o endpoint do Private Service Connect.

Use o exemplo a seguir para recuperar os detalhes de uma instância de loja on-line.

REST

Para recuperar os detalhes de umFeatureOnlineStore recurso em seu projeto, envie umGET usando a featureOnlineStores.get.

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

  • LOCATION_ID: região em que a loja on-line está localizada, como us-central1.
  • PROJECT_ID: o ID do projeto.
  • FEATUREONLINESTORE_NAME: o nome da instância da loja on-line.

Método HTTP e URL: 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

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

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1",
  "createTime": "2023-09-06T23:25:04.256314Z",
  "updateTime": "2023-09-06T23:25:04.256314Z",
  "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=",
  "state": "STABLE",
  "dedicatedServingEndpoint": {
    "privateServiceConnectConfig": {
      "enablePrivateServiceConnect": "true",
      "projectAllowlist": [
        "PROJECT_NAME"
      ]
    },
    serviceAttachment: "SERVICE_ATTACHMENT_STRING"
  },
  "optimized": {}
}

Você vai precisar do SERVICE_ATTACHMENT_STRING da resposta para buscar valores de recursos na etapa a seguir.

Adicionar um endpoint ao Private Service Connect

Para adicionar um endpoint do Private Service Connect para exibição on-line otimizada à configuração de rede, siga estas etapas:

  1. No console do Google Cloud , selecione o projeto que contém a instância de loja on-line.

  2. Crie um endpoint para o Private Service Connect especificando SERVICE_ATTACHMENT_STRING como o serviço de destino.

Depois de criar o endpoint, ele aparece na guia Endpoints conectados na página Private Service Connect. O endereço IP do endpoint aparece na coluna Endereços IP.

Acessar a guia "Endpoints conectados"

Você precisará usar esse endereço IP para se conectar ao endpoint da sua instância de loja on-line ao endpoint do Private Service Connect pelo gRPC na próxima etapa.

Conecte-se ao endpoint do Private Service Connect pelo gRPC

Use o exemplo de código a seguir para se conectar ao endpoint do Private Service Connect criado para sua loja on-line por gRPC.

Python 

from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient
from google.cloud.aiplatform_v1.services.feature_online_store_service.transports.grpc import FeatureOnlineStoreServiceGrpcTransport
import grpc

data_client = FeatureOnlineStoreServiceClient(
  transport = FeatureOnlineStoreServiceGrpcTransport(
    # Add the IP address of the Endpoint you just created.
    channel = grpc.insecure_channel("ENDPOINT_IP:10002")
  )
)

Substitua:

  • ENDPOINT_IP: o endereço IP do endpoint na coluna Endereços IP na página Private Service Connect.

Recuperar vizinhos mais próximos aproximados usando um endpoint do Private Service Connect

Depois de se conectar ao endpoint do Private Service Connect pelo gRPC, é possível pesquisar os vizinhos mais próximos aproximados de um embedding ou entidade.

Recuperar vizinhos mais próximos aproximados de um embedding

Use o exemplo a seguir para pesquisar entidades semanticamente relacionadas especificando um embedding ao usar um endpoint particular.

Python 

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          embedding = "EMBEDDING",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))

Substitua:

  • LOCATION_ID: região em que a loja on-line está localizada, como us-central1.

  • PROJECT_ID: o ID do projeto.

  • FEATUREONLINESTORE_NAME: o nome da loja on-line que contém a visualização do recurso.

  • FEATUREVIEW_NAME: o nome da visualização do recurso em que você quer pesquisar correspondências aproximadas de vizinhos mais próximos.

  • EMBEDDING: embedding para o qual você quer recuperar correspondências aproximadas de vizinhos mais próximos. Um embedding é representado por uma matriz de valores double.

  • FORMAT: opcional. O formato em que você quer buscar os valores dos recursos. Os formatos compatíveis incluem par de chave-valor JSON e formatos proto Struct. O formato proto Struct não é aceito com o tipo de valor de recurso bytes. Se você quiser buscar valores de recursos formatados como bytes, use JSON como formato de resposta.

  • RETURN_FULL_ENTITY (opcional): especifica se você quer incluir ou excluir os recursos das entidades na resposta. Para incluir os recursos com as entidades na resposta, digite true. O valor padrão é false.

  • NEIGHBOR_COUNT: número de vizinhos mais próximos aproximados que você quer recuperar.

Recuperar vizinhos mais próximos de uma entidade

Use o exemplo a seguir para pesquisar entidades semanticamente relacionadas especificando um ID de entidade ao usar um endpoint particular.

Python 

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          entity_id = "ENTITY_ID",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))
 ```

Substitua:

  • LOCATION_ID: região em que a loja on-line está localizada, como us-central1.

  • PROJECT_ID: o ID do projeto.

  • FEATUREONLINESTORE_NAME: o nome da loja on-line que contém a visualização do recurso.

  • FEATUREVIEW_NAME: o nome da visualização do recurso em que você quer pesquisar correspondências aproximadas de vizinhos mais próximos.

  • ENTITY_ID: ID da entidade para a qual você quer recuperar correspondências aproximadas de vizinhos mais próximos.

  • FORMAT: opcional. O formato em que você quer buscar os valores dos recursos. Os formatos compatíveis incluem par de chave-valor JSON e formatos proto Struct. O formato proto Struct não é aceito com o tipo de valor de recurso bytes. Se você quiser buscar valores de recursos formatados como bytes, use JSON como formato de resposta.

  • RETURN_FULL_ENTITY (opcional): especifica se você quer incluir ou excluir os recursos das entidades na resposta. Para incluir os recursos com as entidades na resposta, digite true. O valor padrão é false.

  • NEIGHBOR_COUNT: número de vizinhos mais próximos aproximados que você quer recuperar.

.