Ricerca utilizzando gli embedding

Per le istanze di 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 vicini più prossimi approssimati. Puoi eseguire ricerche in base a un ID entità o un incorporamento.

A seconda del tipo di endpoint configurato per l'istanza del tuo negozio online, puoi eseguire una delle seguenti operazioni:

• Cerca le corrispondenze del vicino più prossimo utilizzando un endpoint pubblico: Scegli questa opzione solo se lo store online è configurato per la pubblicazione online ottimizzata da un endpoint pubblico.

• Cerca corrispondenze del vicino più prossimo utilizzando un endpoint Private Service Connect: Scegli questa opzione solo se l'archivio online è configurato per la pubblicazione online ottimizzata da un endpoint di pubblicazione dedicato tramite Private Service Connect.

Prima di iniziare

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

• Configura l'origine dati BigQuery per supportare gli incorporamenti includendo la colonna embedding. (Facoltativo) Includi le colonne di filtraggio e affollamento. Per saperne di più, consulta le 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 supporti gli incorporamenti associando direttamente l'origine dati BigQuery. Durante la creazione della vista delle caratteristiche, specifica la colonna embedding. Per saperne di più su come creare una vista delle funzionalità che supporta gli incorporamenti, consulta Configurare il recupero dei vettori per una vista delle funzionalità.

• Se vuoi cercare corrispondenze del vicino più prossimo utilizzando un endpoint Private Service Connect, installa o esegui l'upgrade all'ultima versione dell'SDK Python. Esegui questo comando:
  pip3 install --upgrade --quiet google-cloud-aiplatform

• Segui queste istruzioni per l'autenticazione a Vertex AI, a meno che non l'abbia già fatto.

  Select the tab for how you plan to use the samples on this page:

  Python

  Per utilizzare gli esempi di Python questa pagina in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command:

     gcloud init

  4. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

     If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Per ulteriori informazioni, vedi Set up authentication for a local development environment.

  REST

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

  After installing the Google Cloud CLI, initialize it by running the following command:

  gcloud init

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

Cercare le corrispondenze del vicino più prossimo utilizzando un endpoint pubblico

Se hai configurato l'istanza dell'archivio online per pubblicare i valori delle caratteristiche utilizzando la pubblicazione online ottimizzata da un endpoint pubblico, devi eseguire le seguenti operazioni per recuperare le corrispondenze dei vicini più prossimi approssimativi:

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

2. Recuperare le corrispondenze del vicino più prossimo di un incorporamento o di un'entità

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

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

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

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

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"

$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

{
  "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 di PUBLIC_ENDPOINT_DOMAIN_NAME dalla risposta per recuperare i vicini più prossimi approssimativi nel passaggio successivo.

Recuperare i vicini più prossimi approssimati utilizzando un endpoint pubblico

Dopo aver recuperato il nome di dominio dell'endpoint pubblico per il negozio online, puoi utilizzarlo per cercare i vicini più prossimi approssimati di un incorporamento o di un'entità.

Recuperare i vicini più prossimi approssimativi di un incorporamento

Utilizza il seguente esempio per cercare entità correlate semanticamente specificando un incorporamento durante l'utilizzo di un endpoint pubblico.

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

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

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"

$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

{
  "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 approssimati di un'entità

Utilizza il seguente esempio per cercare entità correlate semanticamente specificando un ID entità durante l'utilizzo di un endpoint pubblico.

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

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

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"

$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

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

Cercare corrispondenze del vicino più prossimo utilizzando un endpoint Private Service Connect

Se hai configurato l'istanza del tuo negozio online per pubblicare i valori delle funzionalità utilizzando la pubblicazione online ottimizzata da un endpoint Private Service Connect, devi eseguire le seguenti operazioni per recuperare le corrispondenze approssimative del vicino più prossimo:

1. Recupera la stringa dell'allegato di servizio per il negozio online.

2. Aggiungi un endpoint per Private Service Connect alla configurazione di rete.

3. Connettiti all'endpoint Private Service Connect tramite gRPC.

4. Recuperare le corrispondenze del vicino più prossimo di un incorporamento o di un'entità

Recupera la stringa dell'allegato di servizio per il negozio online

Quando crei un'istanza di negozio online per la pubblicazione online ottimizzata con un endpoint Private Service Connect, Vertex AI Feature Store genera una stringa di collegamento al servizio. Puoi recuperare la stringa del collegamento al servizio dai dettagli dello store online e utilizzarla per configurare l'endpoint Private Service Connect.

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

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

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"

$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

{
  "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": {
    "privateServiceConnectConfig": {
      "enablePrivateServiceConnect": "true",
      "projectAllowlist": [
        "PROJECT_NAME"
      ]
    },
    serviceAttachment: "SERVICE_ATTACHMENT_STRING"
  },
  "optimized": {}
}

Avrai bisogno di SERVICE_ATTACHMENT_STRING dalla risposta per recuperare i valori delle funzionalità nel passaggio successivo.

Aggiungi un endpoint per Private Service Connect

Per aggiungere un endpoint Private Service Connect per la pubblicazione online ottimizzata alla configurazione di rete, esegui i seguenti passaggi:

1. Nella Google Cloud console, seleziona il progetto contenente l'istanza del negozio online.

2. Crea un endpoint per Private Service Connect specificando SERVICE_ATTACHMENT_STRING come servizio di destinazione.

Dopo aver creato l'endpoint, questo viene visualizzato nella scheda Endpoint connessi della pagina Private Service Connect. L'indirizzo IP dell'endpoint viene visualizzato nella colonna Indirizzi IP.

Vai alla scheda Endpoint connessi

Dovrai utilizzare questo indirizzo IP per connetterti all'endpoint per la tua istanza del negozio online all'endpoint Private Service Connect tramite gRPC nel passaggio successivo.

Connettiti all'endpoint Private Service Connect tramite gRPC

Utilizza il seguente esempio di codice per connetterti all'endpoint Private Service Connect creato per il tuo negozio online tramite gRPC.

from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient
from google.cloud.aiplatform_v1.services.feature_online_store_service.transports.grpc import FeatureOnlineStoreServiceGrpcTransport
import grpc

data_client = FeatureOnlineStoreServiceClient(
  transport = FeatureOnlineStoreServiceGrpcTransport(
    # Add the IP address of the Endpoint you just created.
    channel = grpc.insecure_channel("ENDPOINT_IP:10002")
  )
)

Sostituisci quanto segue:

• ENDPOINT_IP: l'indirizzo IP dell'endpoint nella colonna Indirizzi IP della pagina Private Service Connect.

Recuperare i vicini più prossimi approssimativi utilizzando un endpoint Private Service Connect

Dopo aver effettuato la connessione all'endpoint Private Service Connect tramite gRPC, puoi cercare i vicini più prossimi approssimativi di un embedding o di un'entità.

Recuperare i vicini più prossimi approssimativi di un incorporamento

Utilizza il seguente esempio per cercare entità correlate semanticamente specificando un incorporamento durante l'utilizzo di un endpoint privato.

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          embedding = "EMBEDDING",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))

Sostituisci quanto segue:

• LOCATION_ID: la regione in cui si trova il negozio online, ad esempio us-central1.

• PROJECT_ID: il tuo ID progetto.

• FEATUREONLINESTORE_NAME: Il nome del negozio online contenente la visualizzazione delle funzionalità.

• FEATUREVIEW_NAME: il nome della visualizzazione delle caratteristiche in cui vuoi cercare corrispondenze del vicino più prossimo approssimato.

• EMBEDDING: l'incorporamento per il quale vuoi recuperare corrispondenze approssimative del vicino più prossimo. Un incorporamento è rappresentato da un array di valori double.

• FORMAT: (facoltativo) il formato in cui vuoi recuperare i valori delle funzionalità. I formati supportati includono la coppia chiave-valore JSON e i formati proto Struct. Tieni presente che il formato proto Struct non supporta il tipo di valore della funzionalità byte. Se vuoi recuperare valori delle funzionalità formattati come byte, utilizza JSON come formato di risposta.

• 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: il numero di vicini più prossimi approssimativi che vuoi recuperare.

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

Utilizza il seguente esempio per cercare entità correlate semanticamente specificando un ID entità durante l'utilizzo di un endpoint privato.

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          entity_id = "ENTITY_ID",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))
 ```

Sostituisci quanto segue:

• LOCATION_ID: la regione in cui si trova il negozio online, ad esempio us-central1.

• PROJECT_ID: il tuo ID progetto.

• FEATUREONLINESTORE_NAME: Il nome del negozio online contenente la visualizzazione delle funzionalità.

• FEATUREVIEW_NAME: il nome della visualizzazione delle caratteristiche in cui vuoi cercare corrispondenze del vicino più prossimo approssimato.

• ENTITY_ID: l'ID entità dell'entità per cui vuoi recuperare corrispondenze di vicini più prossimi approssimative.

• FORMAT: (facoltativo) il formato in cui vuoi recuperare i valori delle funzionalità. I formati supportati includono la coppia chiave-valore JSON e i formati proto Struct. Tieni presente che il formato proto Struct non supporta il tipo di valore della funzionalità byte. Se vuoi recuperare valori delle funzionalità formattati come byte, utilizza JSON come formato di risposta.

• 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: il numero di vicini più prossimi approssimativi che vuoi recuperare.