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