Cerca utilizzando gli incorporamenti

Per le istanze di negozi online create per la pubblicazione online ottimizzata, puoi eseguire una ricerca di somiglianza vettoriale per recuperare un elenco di entità semanticamente simili o correlate, chiamate anche vicini più prossimi approssimati. Puoi eseguire la ricerca in base a un ID entità o a un incorporamento.

Per cercare i vicini più prossimi approssimati, devi prima effettuare le seguenti operazioni:

• Configura l'origine dati BigQuery in modo da supportare gli incorporamenti includendo la colonna embedding. Facoltativamente, includi le colonne di filtro e crowding. Per saperne di più, consulta le linee guida per la preparazione dell'origine dati.

• Crea un'istanza del negozio online per la pubblicazione online ottimizzata.

• Specifica la colonna embedding durante la creazione della visualizzazione delle caratteristiche. Per ulteriori informazioni su come creare una visualizzazione caratteristiche che supporti gli incorporamenti, consulta Configurare il recupero vettoriale per una visualizzazione caratteristiche.

In questa pagina viene descritto come effettuare le seguenti operazioni:

• Recuperare il nome di dominio dell'endpoint pubblico per il negozio online

• Recuperare le corrispondenze del vicino più prossimo di un incorporamento

• Recuperare le corrispondenze del vicino più prossimo di un'entità

Prima di iniziare

Autentica in Vertex AI, se non l'hai già fatto.

Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

Installa Google Cloud CLI, quindi initialize eseguendo questo comando:

gcloud init

Per maggiori informazioni, consulta Autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

Recupera il nome di dominio dell'endpoint pubblico per l'archivio online

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

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

REST

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

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

• LOCATION_ID: regione in cui si trova il negozio online, ad esempio us-central1.
• PROJECT_ID: l'ID 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 comando seguente 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 fa accedere automaticamente all'interfaccia a riga di comando di 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 all'interfaccia a riga di comando di 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": {}
}

Avrai bisogno del PUBLIC_ENDPOINT_DOMAIN_NAME della risposta per recuperare i vicini più prossimi approssimati nel passaggio seguente.

Recupera i vicini più prossimi approssimati di un incorporamento

Usa l'esempio seguente per usare un incorporamento per eseguire la ricerca di entità semanticamente correlate specificando un incorporamento.

REST

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

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

• PUBLIC_ENDPOINT_DOMAIN_NAME: il nome di dominio dell'endpoint pubblico per l'istanza del negozio online recuperato utilizzando il metodo featureOnlineStores.get.
• PROJECT_ID: l'ID 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 caratteristiche in cui vuoi cercare le corrispondenze approssimative del vicino più prossimo.
• FEATUREVIEW_NAME: il nome della visualizzazione delle caratteristiche in cui vuoi cercare le corrispondenze approssimative del vicino più prossimo.
• EMBEDDING: incorporamento per il quale vuoi recuperare corrispondenze approssimative del vicino più prossimo. Un incorporamento è rappresentato da un array di valori double.
• BOOLEAN: (facoltativo) specifica se vuoi includere o escludere le caratteristiche 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ù prossimi 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": BOOLEAN
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il comando seguente 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 fa accedere automaticamente all'interfaccia a riga di comando di gcloud. . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json ed esegui questo 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

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

Salva il corpo della richiesta in un file denominato request.json ed esegui questo 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

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

Recupera i vicini più prossimi approssimati di un'entità

Usa l'esempio seguente per usare un incorporamento al fine di eseguire la ricerca di entità semanticamente correlate specificando un ID entità.

REST

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

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

• PUBLIC_ENDPOINT_DOMAIN_NAME: il nome di dominio dell'endpoint pubblico per l'istanza del negozio online recuperato utilizzando il metodo featureOnlineStores.get.
• PROJECT_ID: l'ID 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 caratteristiche in cui vuoi cercare le corrispondenze approssimative del vicino più prossimo.
• FEATUREVIEW_NAME: il nome della visualizzazione delle caratteristiche in cui vuoi cercare le corrispondenze approssimative del vicino più prossimo.
• ENTITY_ID: ID entità dell'entità per cui vuoi recuperare le corrispondenze approssimative del vicino più prossimo.
• BOOLEAN: (facoltativo) specifica se vuoi includere o escludere le caratteristiche 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ù prossimi 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": BOOLEAN
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il comando seguente 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 fa accedere automaticamente all'interfaccia a riga di comando di gcloud. . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json ed esegui questo 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

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

Salva il corpo della richiesta in un file denominato request.json ed esegui questo 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

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