Pesquise através de incorporações

Para instâncias de lojas online criadas para o serviço online otimizado, pode fazer uma pesquisa de similaridade de vetores para obter uma lista de entidades semanticamente semelhantes ou relacionadas, também denominadas vizinhos mais próximos aproximados. Pode pesquisar com base num ID de entidade ou numa incorporação.

Consoante o tipo de ponto final configurado para a instância da sua loja online, pode fazer uma das seguintes ações:

Antes de começar

Para pesquisar os vizinhos mais próximos aproximados, primeiro tem de fazer o seguinte:

  • Configure a origem de dados do BigQuery para suportar incorporações incluindo a coluna embedding. Opcionalmente, inclua colunas de filtragem e crowdsourcing. Para mais informações, consulte as diretrizes de preparação de origens de dados.

  • Crie uma instância de loja online para a publicação online otimizada.

  • Crie uma visualização de recursos que suporte incorporações associando diretamente a origem de dados do BigQuery. Ao criar a vista de recursos, especifique a coluna embedding. Para mais informações sobre como criar uma visualização de propriedade de funcionalidades que suporte incorporações, consulte o artigo Configure a obtenção de vetores para uma visualização de propriedade de funcionalidades.

  • Se quiser pesquisar correspondências de vizinhos mais próximos através de um ponto final do Private Service Connect, instale ou atualize para a versão mais recente do SDK Python. Execute o seguinte comando:
    pip3 install --upgrade --quiet google-cloud-aiplatform

  • Siga estas instruções para se autenticar no Vertex AI, a menos que já o tenha feito.

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

    Python

    Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a 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.

    Para mais informações, consulte Set up authentication for a local development environment.

    REST

    Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

      Instale a CLI Google Cloud.

      Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

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

Pesquise correspondências de vizinhos mais próximos através de um ponto final público

Se configurou a instância da sua loja online para publicar valores de atributos através da publicação online otimizada a partir de um ponto final público, tem de fazer o seguinte para obter correspondências de vizinhos mais próximos aproximadas:

  1. Recupere o nome do domínio do ponto final público da loja online

  2. Obtenha as correspondências de vizinhos mais próximos de uma incorporação ou de uma entidade

Obtenha o nome do domínio do ponto final público para a loja online

Quando cria uma instância da loja online para o serviço online otimizado, a Vertex AI Feature Store gera um nome de domínio do ponto final público para a loja online. Antes de poder começar a pesquisar os vizinhos mais próximos a partir de uma vista de funcionalidades na loja online, tem de obter o nome do domínio do ponto final público a partir dos detalhes da loja online.

Use o exemplo seguinte para obter os detalhes de uma instância de loja online.

REST

Para obter os detalhes de um recurso FeatureOnlineStore no seu projeto, envie um pedido através do método featureOnlineStores.get.GET

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

  • LOCATION_ID: região onde a loja online está localizada, como us-central1.
  • PROJECT_ID: o ID do seu projeto.
  • FEATUREONLINESTORE_NAME: o nome da instância da loja online.

Método HTTP e URL: 

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

Para enviar o seu pedido, 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

Deve receber uma resposta JSON semelhante à seguinte:

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

Precisa do PUBLIC_ENDPOINT_DOMAIN_NAME da resposta para obter os vizinhos mais próximos aproximados no passo seguinte.

Recupere os vizinhos mais próximos aproximados através de um ponto final público

Depois de obter o nome do domínio do ponto final público da loja online, pode usá-lo para pesquisar os vizinhos mais próximos aproximados de uma incorporação ou de uma entidade.

Obtenha os vizinhos mais próximos aproximados de uma incorporação

Use o exemplo seguinte para pesquisar entidades semanticamente relacionadas especificando uma incorporação enquanto usa um ponto final público.

REST

Para pesquisar os vizinhos mais próximos de uma incorporação, envie um pedido POST através do método featureViews.searchNearestEntities.

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

  • PUBLIC_ENDPOINT_DOMAIN_NAME: o nome do domínio do ponto final público da instância da loja online que recuperou através do método featureOnlineStores.get.
  • PROJECT_ID: o ID do seu projeto.
  • LOCATION_ID: região onde a instância da loja online está localizada, como us-central1.
  • FEATUREONLINESTORE_NAME: o nome da instância da loja online que contém a visualização de caraterísticas onde quer pesquisar correspondências de vizinhos mais próximos aproximadas.
  • FEATUREVIEW_NAME: o nome da vista de funcionalidades onde quer pesquisar correspondências de vizinhos mais próximos aproximadas.
  • EMBEDDING: incorporação para a qual quer obter correspondências de vizinhos mais próximos aproximadas. Uma incorporação é representada por uma matriz de valores double.
  • RETURN_FULL_ENTITY: opcional: especifique se quer incluir ou excluir as funcionalidades para as entidades na resposta. Para incluir as funcionalidades juntamente com as entidades na resposta, introduza true. O valor predefinido é false.
  • NEIGHBOR_COUNT: número de vizinhos mais próximos aproximados que quer obter.

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 do pedido: 

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

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

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Deve receber uma resposta JSON semelhante à seguinte:

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

Obtenha os vizinhos mais próximos aproximados de uma entidade

Use o exemplo seguinte para pesquisar entidades semanticamente relacionadas especificando um ID de entidade enquanto usa um ponto final público.

REST

Para pesquisar os vizinhos mais próximos de um ID de entidade, envie um pedido POST através do método featureViews.searchNearestEntities.

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

  • PUBLIC_ENDPOINT_DOMAIN_NAME: o nome do domínio do ponto final público da instância da loja online que recuperou através do método featureOnlineStores.get.
  • PROJECT_ID: o ID do seu projeto.
  • LOCATION_ID: região onde a instância da loja online está localizada, como us-central1.
  • FEATUREONLINESTORE_NAME: o nome da instância da loja online que contém a visualização de caraterísticas onde quer pesquisar correspondências de vizinhos mais próximos aproximadas.
  • FEATUREVIEW_NAME: o nome da vista de funcionalidades onde quer pesquisar correspondências de vizinhos mais próximos aproximadas.
  • ENTITY_ID: ID da entidade para a qual quer obter correspondências de vizinhos mais próximos aproximadas.
  • RETURN_FULL_ENTITY: opcional: especifique se quer incluir ou excluir as funcionalidades para as entidades na resposta. Para incluir as funcionalidades juntamente com as entidades na resposta, introduza true. O valor predefinido é false.
  • NEIGHBOR_COUNT: número de vizinhos mais próximos aproximados que quer obter.

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 do pedido: 

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

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

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

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

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$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

Deve receber uma resposta JSON semelhante à seguinte:

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

Pesquise correspondências de vizinhos mais próximos através de um ponto final do Private Service Connect

Se configurou a instância da sua loja online para publicar valores de funcionalidades através da publicação online otimizada a partir de um ponto final do Private Service Connect, tem de fazer o seguinte para obter correspondências de vizinhos mais próximos aproximadas:

  1. Obtenha a string de associação de serviços para a loja online.

  2. Adicione um ponto final para o Private Service Connect à configuração de rede.

  3. Estabeleça ligação ao ponto final do Private Service Connect através de gRPC.

  4. Obtenha as correspondências de vizinhos mais próximos de uma incorporação ou de uma entidade

Recupere a string de anexo do serviço para a loja online

Quando cria uma instância da loja online para o serviço online otimizado com um ponto final do Private Service Connect, o Vertex AI Feature Store gera uma string de associação do serviço. Pode obter a string do anexo de serviço a partir dos detalhes da loja online e usar esta string para configurar o ponto final do Private Service Connect.

Use o exemplo seguinte para obter os detalhes de uma instância de loja online.

REST

Para obter os detalhes de um recurso FeatureOnlineStore no seu projeto, envie um pedido através do método featureOnlineStores.get.GET

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

  • LOCATION_ID: região onde a loja online está localizada, como us-central1.
  • PROJECT_ID: o ID do seu projeto.
  • FEATUREONLINESTORE_NAME: o nome da instância da loja online.

Método HTTP e URL: 

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

Para enviar o seu pedido, 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

Deve receber uma resposta JSON semelhante à seguinte:

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

Precisa do SERVICE_ATTACHMENT_STRING da resposta para obter os valores das funcionalidades no passo seguinte.

Adicione um ponto final para o Private Service Connect

Para adicionar um ponto final do Private Service Connect para o serviço online otimizado à configuração da sua rede, execute os seguintes passos:

  1. Na Google Cloud consola, selecione o projeto que contém a instância da loja online.

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

Depois de criar o ponto final, este é apresentado no separador Pontos finais ligados na página Private Service Connect. O endereço IP do ponto final aparece na coluna Endereços IP.

Aceda ao separador Pontos finais ligados

Tem de usar este endereço IP para estabelecer ligação ao ponto final da instância da loja online ao ponto final do Private Service Connect através de gRPC no passo seguinte.

Estabeleça ligação ao ponto final do Private Service Connect através do gRPC

Use o seguinte exemplo de código para estabelecer ligação ao ponto final do Private Service Connect criado para a sua loja online através do 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 o seguinte:

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

Obtenha os vizinhos mais próximos aproximados através de um ponto final do Private Service Connect

Depois de se ligar ao ponto final do Private Service Connect através do gRPC, pode pesquisar os vizinhos mais próximos aproximados de uma incorporação ou de uma entidade.

Obtenha os vizinhos mais próximos aproximados de uma incorporação

Use o exemplo seguinte para pesquisar entidades semanticamente relacionadas especificando uma incorporação enquanto usa um ponto final privado.

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 o seguinte:

  • LOCATION_ID: região onde a loja online está localizada, como us-central1.

  • PROJECT_ID: o ID do seu projeto.

  • FEATUREONLINESTORE_NAME: o nome da loja online que contém a visualização da funcionalidade.

  • FEATUREVIEW_NAME: o nome da vista de recursos onde quer pesquisar correspondências de vizinhos mais próximos aproximadas.

  • EMBEDDING: Incorporação para a qual quer obter correspondências aproximadas de vizinhos mais próximos. Uma incorporação é representada por uma matriz de valores double.

  • FORMAT: opcional: o formato no qual quer obter os valores das caraterísticas. Os formatos suportados incluem o par de chave-valor JSON e os formatos proto.Struct Tenha em atenção que o formato proto Struct não suporta o tipo de valor da funcionalidade de bytes. Se quiser obter valores de funcionalidades formatados como bytes, use o formato de resposta JSON.

  • RETURN_FULL_ENTITY: Opcional: especifique se quer incluir ou excluir as funcionalidades para as entidades na resposta. Para incluir as funcionalidades juntamente com as entidades na resposta, introduza true. O valor predefinido é false.

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

Obtenha os vizinhos mais próximos aproximados de uma entidade

Use o exemplo seguinte para pesquisar entidades semanticamente relacionadas especificando um ID de entidade enquanto usa um ponto final privado.

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 o seguinte:

  • LOCATION_ID: região onde a loja online está localizada, como us-central1.

  • PROJECT_ID: o ID do seu projeto.

  • FEATUREONLINESTORE_NAME: o nome da loja online que contém a visualização da funcionalidade.

  • FEATUREVIEW_NAME: o nome da vista de recursos onde quer pesquisar correspondências de vizinhos mais próximos aproximadas.

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

  • FORMAT: opcional: o formato no qual quer obter os valores das caraterísticas. Os formatos suportados incluem o par de chave-valor JSON e os formatos proto.Struct Tenha em atenção que o formato proto Struct não suporta o tipo de valor da funcionalidade de bytes. Se quiser obter valores de caraterísticas formatados como bytes, use JSON como formato de resposta.

  • RETURN_FULL_ENTITY: Opcional: especifique se quer incluir ou excluir as funcionalidades para as entidades na resposta. Para incluir as funcionalidades juntamente com as entidades na resposta, introduza true. O valor predefinido é false.

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