Pesquisar usando embeddings

Se você configurou seu armazenamento on-line para oferecer suporte a incorporações, é possível executar uma pesquisa de similaridade vetorial para recuperar uma lista de entidades semanticamente parecidas ou relacionadas, também chamadas de vizinhos mais próximos aproximados. É 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:

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

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

Ao criar e configurar uma instância de armazenamento on-line para gerenciamento de incorporação, o Vertex AI Feature Store gera um nome de domínio de endpoint público 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 http://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)" \
     "http://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 "http://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.
  • BOOLEAN (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 http://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": BOOLEAN
}

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 \
     "http://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 "http://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.
  • BOOLEAN (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 http://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": BOOLEAN
}

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 \
     "http://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 "http://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
    } ]
  }
}