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.

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.
Especifique a coluna embedding ao criar a visualização do elemento. Para saber mais sobre como criar uma visualização de recursos compatível com embeddings, consulte Configurar recuperação de vetor para uma visualização de recurso.

Nesta página, descrevemos como você pode fazer o seguinte:

Recuperar o nome de domínio do endpoint público da loja on-line
Recuperar correspondências de vizinhos mais próximos de um embedding.
Recuperar correspondências de vizinhos mais próximos de uma entidade.

Antes de começar

Faça a autenticação na Vertex AI, a menos que já tenha feito isso.

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

Install the Google Cloud CLI, then initialize it by running the following command:

gcloud init

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

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

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

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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 de um embedding

Use o exemplo a seguir para usar um embedding para realizar pesquisa de entidades semanticamente relacionadas com a especificação de um embedding.

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 usar um embedding para realizar pesquisa de entidades semanticamente relacionadas com a especificação de um ID de entidade.

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