Cercare utilizzando gli incorporamenti

Per le istanze di negozio online create per l'erogazione online ottimizzata, puoi eseguire una ricerca di similarità vettoriale per recuperare un elenco di entità semanticamente simili o correlate, chiamate anche Approximate Nearest Neighbor. Puoi eseguire ricerche in base a un ID entità o a un embedding.

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 il negozio online è configurato per l'erogazione online ottimizzata da un endpoint pubblico.

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

Prima di iniziare

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

• Configura l'origine dati BigQuery per supportare gli incorporamenti includendo la colonna embedding. (Facoltativo) Includi le colonne di filtro e crowdsourcing. Per saperne di più, consulta le linee guida per la preparazione delle origini dati.

• Crea un'istanza del negozio online per l'erogazione 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 embedding, 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 alla piattaforma dell'agente, a meno che non l'abbia già fatto.

  Seleziona la scheda relativa a come prevedi di utilizzare i campioni in questa pagina:

  Python

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

  1. Installa Google Cloud CLI.

  2. Configura gcloud CLI per utilizzare la tua identità federata.

     Per saperne di più, consulta Accedi a gcloud CLI con la tua identità federata.

  3. Crea le credenziali di autenticazione locali per il tuo account utente:

     gcloud auth application-default login

     Se viene restituito un errore di autenticazione, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.

  Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

  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.

  Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata.

  Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Cloud de Confiance .

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

Se hai configurato l'istanza dell'archivio online per erogare i valori delle caratteristiche utilizzando l'erogazione online ottimizzata da un endpoint pubblico, devi eseguire le seguenti operazioni per recuperare le corrispondenze del vicino più prossimo approssimativo:

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 di negozio online per l'erogazione 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ù prossimi da una visualizzazione delle caratteristiche 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 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 approssimativi di un incorporamento o di un'entità.

Recupera 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 dell'archivio online per erogare i valori delle funzionalità utilizzando l'erogazione online ottimizzata da un endpoint Private Service Connect, devi eseguire le seguenti operazioni per recuperare le corrispondenze del vicino più prossimo approssimativo:

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à

Recuperare la stringa del collegamento al servizio per il negozio online

Quando crei un'istanza di archivio online per l'erogazione 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 del negozio 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 l'erogazione online ottimizzata alla configurazione di rete, svolgi i seguenti passaggi:

1. Nella console Cloud de Confiance , 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.

Recupera 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à.

Recupera i vicini più prossimi approssimativi di un incorporamento

Utilizza il seguente esempio per cercare entità correlate semanticamente specificando un embedding 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 funzionalità in cui vuoi cercare corrispondenze dei vicini più prossimi approssimativi.

• EMBEDDING: l'embedding per cui vuoi recuperare le corrispondenze del vicino più prossimo approssimato. 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ù vicini 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 funzionalità in cui vuoi cercare corrispondenze dei vicini più prossimi approssimativi.

• ENTITY_ID: l'ID entità dell'entità per cui vuoi recuperare corrispondenze approssimative del vicino più prossimo.

• 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ù vicini approssimativi che vuoi recuperare.