Questa pagina è stata tradotta dall'API Cloud Translation.

Ricerca utilizzando gli embedding

Per le istanze dei negozi online create per la pubblicazione online ottimizzata, puoi eseguire una ricerca di similarità vettoriale per recuperare un elenco di entità semanticamente simili o correlate, chiamate anche risultati più simili approssimativi. Puoi eseguire ricerche in base a un ID entità o a un'evidenziazione.

Per cercare i vicini più prossimi approssimativi, devi prima svolgere i seguenti passaggi:

Configura l'origine dati BigQuery in modo da supportare gli embedding includendo la colonna embedding. Se vuoi, puoi includere colonne di filtro e di aggregazione. Per saperne di più, consulta Linee guida per la preparazione delle origini dati.
Crea un'istanza del negozio online per la distribuzione online ottimizzata.
Crea una vista delle funzionalità che supporta gli incorporamenti associando direttamente l'origine dati BigQuery. Durante la creazione della visualizzazione delle funzionalità, puoi utilizzare la configurazione predefinita dell'account di servizio o specificare una configurazione dell'account di servizio (anteprima).

Devi anche specificare la colonna embedding per la visualizzazione delle funzionalità. Per ulteriori informazioni su come creare una vista elemento che supporti gli embedding, consulta Configurare il recupero di vettori per una vista elemento.

Questa pagina descrive come eseguire le seguenti operazioni:

Recupero del nome di dominio dell'endpoint pubblico per il negozio online
Recupero delle corrispondenze del vicino più prossimo di un'espressione incorporata
Recupero delle corrispondenze più vicine di un'entità

Prima di iniziare

Esegui l'autenticazione su Vertex AI, se non l'hai ancora fatto.

Per utilizzare gli esempi dell'API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali fornite a gcloud CLI.

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

gcloud init

Per saperne di più, consulta Eseguire l'autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

Recupera il nome di dominio dell'endpoint pubblico per il negozio online

Quando crei un'istanza del negozio online per la pubblicazione online ottimizzata, Vertex AI Feature Store genera un nome di dominio dell'endpoint pubblico per il negozio online. Prima di poter iniziare a cercare i vicini più vicini da una visualizzazione delle funzionalità nel negozio online, devi recuperare il nome di dominio dell'endpoint pubblico dai dettagli del negozio online.

Utilizza il seguente esempio per recuperare i dettagli di un'istanza del negozio online.

REST

Per recuperare i dettagli di una risorsa FeatureOnlineStore nel progetto, invia una richiesta GET utilizzando il metodo featureOnlineStores.get.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

LOCATION_ID: regione in cui si trova il negozio online, ad esempio us-central1.
PROJECT_ID: l'ID del tuo progetto.
FEATUREONLINESTORE_NAME: il nome dell'istanza del negozio online.

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Nel passaggio successivo avrai bisogno del valore PUBLIC_ENDPOINT_DOMAIN_NAME della risposta per recuperare i vicini più vicini approssimativi.

Recupera i vicini più prossimi approssimativi di un'evidenziazione

Utilizza il seguente esempio per utilizzare un embedding per eseguire la ricerca di entità semanticamente correlate specificando un embedding.

REST

Per cercare i vicini più prossimi di un incorporamento, invia una richiesta POST utilizzando il metodo featureViews.searchNearestEntities.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

PUBLIC_ENDPOINT_DOMAIN_NAME: il nome di dominio dell'endpoint pubblico per l'istanza del negozio online recuperata utilizzando il metodo featureOnlineStores.get.
PROJECT_ID: l'ID del tuo progetto.
LOCATION_ID: regione in cui si trova l'istanza del negozio online, ad esempio us-central1.
FEATUREONLINESTORE_NAME: il nome dell'istanza del negozio online contenente la visualizzazione delle funzionalità in cui vuoi cercare corrispondenze approssimative del vicino più vicino.
FEATUREVIEW_NAME: il nome della visualizzazione delle caratteristiche in cui vuoi cercare corrispondenze approssimative con il vicino più vicino.
EMBEDDING: l'embedding per cui vuoi recuperare le corrispondenze approssimative del vicino più prossimo. Un embedding è rappresentato da un array di valori double.
RETURN_FULL_ENTITY: facoltativo. Specifica se vuoi includere o escludere le funzionalità per le entità nella risposta. Per includere le funzionalità insieme alle entità nella risposta, inserisci true. Il valore predefinito è false.
NEIGHBOR_COUNT: numero di vicini più vicini approssimativi che vuoi recuperare.

Metodo 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 della richiesta:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Recuperare i vicini più prossimi approssimativi di un'entità

Utilizza il seguente esempio per utilizzare un'evidenziazione per eseguire la ricerca di entità semanticamente correlate specificando un ID entità.

REST

Per cercare i vicini più prossimi di un ID entità, invia una richiesta POST utilizzando il metodo featureViews.searchNearestEntities.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

PUBLIC_ENDPOINT_DOMAIN_NAME: il nome di dominio dell'endpoint pubblico per l'istanza del negozio online recuperata utilizzando il metodo featureOnlineStores.get.
PROJECT_ID: l'ID del tuo progetto.
LOCATION_ID: regione in cui si trova l'istanza del negozio online, ad esempio us-central1.
FEATUREONLINESTORE_NAME: il nome dell'istanza del negozio online contenente la visualizzazione delle funzionalità in cui vuoi cercare corrispondenze approssimative del vicino più vicino.
FEATUREVIEW_NAME: il nome della visualizzazione delle caratteristiche in cui vuoi cercare corrispondenze approssimative del vicino più vicino.
ENTITY_ID: l'ID entità per cui vuoi recuperare le corrispondenze approssimative del vicino più vicino.
RETURN_FULL_ENTITY: facoltativo. Specifica se vuoi includere o escludere le funzionalità per le entità nella risposta. Per includere le funzionalità insieme alle entità nella risposta, inserisci true. Il valore predefinito è false.
NEIGHBOR_COUNT: numero di vicini più vicini approssimativi che vuoi recuperare.

Metodo 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 della richiesta:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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