Questa pagina è stata tradotta dall'API Cloud Translation.

Generare ed eseguire ricerche di embedding multimodali

Questo tutorial illustra la procedura end-to-end per la creazione di incorporamenti multimodali per immagini e testo, nonché per eseguire una ricerca da testo a immagine cross-modalità.

Questo tutorial spiega le seguenti attività:

Crea una tabella di oggetti BigQuery sui dati delle immagini in un bucket Cloud Storage.
Esplorare i dati delle immagini utilizzando un notebook di Colab Enterprise in BigQuery.
Creazione di un modello remoto BigQuery ML che abbia come target il modello di base multimodalembedding di Vertex AI.
Utilizzo del modello remoto con la funzione ML.GENERATE_EMBEDDING per generare embedding dalle immagini nella tabella degli oggetti.
Correggi eventuali errori di generazione dell'embedding.
Facoltativamente, puoi creare un indice di vettori per indicizzare gli incorporamenti delle immagini.
Creazione di un embedding di testo per una determinata stringa di ricerca.
Utilizza la funzione VECTOR_SEARCH per cercare rappresentazioni distribuite di immagini simili a quella del testo.
Visualizzazione dei risultati utilizzando un notebook.

Questo tutorial utilizza le immagini d'arte di dominio pubblico del Metropolitan Museum of Art disponibili nel gcs-public-data--met bucket Cloud Storage pubblico.

Autorizzazioni obbligatorie

Per eseguire questo tutorial, devi disporre delle seguenti autorizzazioni IAM (Identity and Access Management):

Per creare una connessione, devi disporre del ruolo Amministratore connessione BigQuery (roles/bigquery.connectionAdmin).
Per concedere le autorizzazioni all'account di servizio della connessione, devi disporre dell'autorizzazioneresourcemanager.projects.setIamPolicy.
Per creare ed eseguire i notebook, devi disporre delle seguenti autorizzazioni IAM:
- resourcemanager.projects.get
- resourcemanager.projects.list
- bigquery.config.get
- bigquery.jobs.create
- bigquery.readsessions.create
- bigquery.readsessions.getData
- bigquery.readsessions.update
- resourcemanager.projects.get
- resourcemanager.projects.list
- dataform.locations.get
- dataform.locations.list
- dataform.repositories.create
  
  Nota: gli utenti che dispongono dell'autorizzazione dataform.repositories.create possono eseguire codice utilizzando l'account di servizio Dataform predefinito e tutte le autorizzazioni concesse a quell'account di servizio. Per ulteriori informazioni, consulta Considerazioni sulla sicurezza per le autorizzazioni di Dataform.
- dataform.repositories.list
- dataform.collections.create
- dataform.collections.list
- aiplatform.notebookRuntimeTemplates.apply
- aiplatform.notebookRuntimeTemplates.get
- aiplatform.notebookRuntimeTemplates.list
- aiplatform.notebookRuntimeTemplates.getIamPolicy
- aiplatform.notebookRuntimes.assign
- aiplatform.notebookRuntimes.get
- aiplatform.notebookRuntimes.list
- aiplatform.operations.list
Puoi ottenere queste autorizzazioni dai seguenti ruoli IAM:
- Utente sessione di lettura BigQuery (roles/bigquery.readSessionUser)
- Utente BigQuery Studio (roles/bigquery.studioUser)
Le autorizzazioni IAM necessarie in questo tutorial per le altre operazioni di BigQuery sono incluse nei seguenti due ruoli:
- BigQuery Data Editor (roles/bigquery.dataEditor) per creare modelli, tabelle e indici.
- Utente BigQuery (roles/bigquery.user) per eseguire job BigQuery.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

BigQuery ML: You incur costs for the data that you process in BigQuery.
Vertex AI: You incur costs for calls to the Vertex AI service that's represented by the remote model.

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Per ulteriori informazioni sui prezzi di BigQuery, consulta la sezione Prezzi di BigQuery della documentazione di BigQuery.

Per ulteriori informazioni sui prezzi di Vertex AI, consulta la pagina Prezzi di Vertex AI.

Prima di iniziare

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Make sure that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Enable the APIs
Attiva BigQuery Studio.

Crea un set di dati

Crea un set di dati BigQuery per archiviare il tuo modello ML:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai alla pagina BigQuery
Nel riquadro Explorer, fai clic sul nome del progetto.
Fai clic su Visualizza azioni > Crea set di dati.
Nella pagina Crea set di dati:
- In ID set di dati, inserisci bqml_tutorial.
- Per Tipo di località, seleziona Più regioni e poi Stati Uniti (più regioni negli Stati Uniti).
  
  I set di dati pubblici sono archiviati nella US multiregione. Per semplicità, archivia il set di dati nella stessa posizione.
- Lascia invariate le restanti impostazioni predefinite e fai clic su Crea set di dati.

Crea una connessione

Crea una connessione risorsa Cloud e recupera l'ID account di servizio della connessione. Crea la connessione nella stessa posizione del set di dati creato nel passaggio precedente.

Seleziona una delle seguenti opzioni:

Console

Vai alla pagina BigQuery.

Vai a BigQuery
Per creare una connessione, fai clic su Aggiungi e poi su Connessioni a origini dati esterne.
Nell'elenco Tipo di connessione, seleziona Modelli remoti di Vertex AI, funzioni remote e BigLake (risorsa Cloud).
Nel campo ID connessione, inserisci un nome per la connessione.
Fai clic su Crea connessione.
Fai clic su Vai alla connessione.
Nel riquadro Informazioni sulla connessione, copia l'ID account di servizio da utilizzare in un passaggio successivo.

bq

In un ambiente a riga di comando, crea una connessione:
```
bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID
```
Il parametro --project_id sostituisce il progetto predefinito.

Sostituisci quanto segue:
- REGION: la regione di connessione
- PROJECT_ID: il tuo ID progetto Google Cloud
- CONNECTION_ID: un ID per la connessione
Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema unico e lo associa alla connessione.

Risoluzione dei problemi: se ricevi il seguente errore di connessione, aggiorna Google Cloud SDK:
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

Recupera e copia l'ID account di servizio per utilizzarlo in un passaggio successivo:

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

L'output è simile al seguente:

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

Utilizza la risorsa google_bigquery_connection.

Per autenticarti in BigQuery, configura le credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.

L'esempio seguente crea una connessione risorsa Cloud denominata my_cloud_resource_connection nella regione US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle seguenti sezioni.

Prepara Cloud Shell

Avvia Cloud Shell.
Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

Devi eseguire questo comando una sola volta per progetto e puoi farlo in qualsiasi directory.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.

Prepara la directory

Ogni file di configurazione di Terraform deve avere una propria directory (chiamata anche modulo principale).

In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

Copia il codice campione nel file main.tf appena creato.

Se vuoi, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.
Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
Salva le modifiche.
Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.
```
terraform init
```
Se vuoi, per utilizzare la versione più recente del provider Google, includi l'opzione -upgrade:
```
terraform init -upgrade
```

Applica le modifiche

Rivedi la configurazione e verifica che le risorse che Terraform sta per creare o aggiornare corrispondano alle tue aspettative:
```
terraform plan
```
Apporta le correzioni necessarie alla configurazione.
Applica la configurazione di Terraform eseguendo il seguente comando e inserendo yes al prompt:
```
terraform apply
```
Attendi che Terraform mostri il messaggio "Applicazione completata".
Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.

Concedi le autorizzazioni all'account di servizio della connessione

Concedi all'account di servizio della connessione i ruoli appropriati per accedere ai servizi Cloud Storage e Vertex AI. Devi concedere questi ruoli nello stesso progetto che hai creato o selezionato nella sezione Prima di iniziare. Se concedi i ruoli in un progetto diverso, viene visualizzato l'errore bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Per concedere i ruoli appropriati:

Vai alla pagina IAM e amministrazione.

Vai a IAM e amministrazione
Fai clic su Concedi l'accesso.
Nel campo Nuove entità, inserisci l'ID account di servizio che hai copiato in precedenza.
Nel campo Seleziona un ruolo, scegli Vertex AI e poi Utente Vertex AI.
Fai clic su Aggiungi un altro ruolo.
Nel campo Seleziona un ruolo, scegli Cloud Storage e poi Visualizzatore oggetti Storage.
Fai clic su Salva.

Crea la tabella degli oggetti

Crea una tabella di oggetti sulle immagini artistiche nel gcs-public-data--met bucket Cloud Storage pubblico. La tabella degli oggetti consente di analizzare le immagini senza spostarle da Cloud Storage.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nell'editor di query, esegui la seguente query:
```
CREATE OR REPLACE EXTERNAL TABLE `bqml_tutorial.met_images`
WITH CONNECTION `LOCATION.CONNECTION_ID`
OPTIONS
  ( object_metadata = 'SIMPLE',
    uris = ['gs://gcs-public-data--met/*']
  );
```
Sostituisci quanto segue:
- LOCATION: la posizione della connessione.
- CONNECTION_ID: l'ID della connessione BigQuery.
  Quando visualizzi i dettagli della connessione nella console Google Cloud, questo è il valore nell'ultima sezione dell'ID connessione visualizzato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.

Esplorare i dati delle immagini

Crea un blocco note di Colab Enterprise in BigQuery per esplorare i dati delle immagini.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Crea un notebook utilizzando l'editor di BigQuery.
Collega il notebook al runtime predefinito.
Configura il notebook:
1. Aggiungi una cella di codice al notebook.
2. Copia e incolla il seguente codice nella cella di codice:
```
#@title Set up credentials

from google.colab import auth
auth.authenticate_user()
print('Authenticated')

PROJECT_ID='PROJECT_ID'
from google.cloud import bigquery
client = bigquery.Client(PROJECT_ID)
```
  Sostituisci PROJECT_ID con il nome del progetto che utilizzi per questo tutorial.
3. Esegui la cella di codice.
Attiva la visualizzazione della tabella:
1. Aggiungi una cella di codice al notebook.
2. Copia e incolla il seguente codice nella cella di codice:
```
#@title Enable data table display
%load_ext google.colab.data_table
```
3. Esegui la cella di codice.

Crea una funzione per visualizzare le immagini:

Aggiungi una cella di codice al notebook.

Copia e incolla il seguente codice nella cella di codice:

#@title Util function to display images
import io
from PIL import Image
import matplotlib.pyplot as plt
import tensorflow as tf

def printImages(results):
 image_results_list = list(results)
 amt_of_images = len(image_results_list)

 fig, axes = plt.subplots(nrows=amt_of_images, ncols=2, figsize=(20, 20))
 fig.tight_layout()
 fig.subplots_adjust(hspace=0.5)
 for i in range(amt_of_images):
   gcs_uri = image_results_list[i][0]
   text = image_results_list[i][1]
   f = tf.io.gfile.GFile(gcs_uri, 'rb')
   stream = io.BytesIO(f.read())
   img = Image.open(stream)
   axes[i, 0].axis('off')
   axes[i, 0].imshow(img)
   axes[i, 1].axis('off')
   axes[i, 1].text(0, 0, text, fontsize=10)
 plt.show()

Esegui la cella di codice.

Visualizza le immagini:

Aggiungi una cella di codice al notebook.

Copia e incolla il seguente codice nella cella di codice:

#@title Display Met images

inspect_obj_table_query = """
SELECT uri, content_type
FROM bqml_tutorial.met_images
WHERE content_type = 'image/jpeg'
Order by uri
LIMIT 10;
"""
printImages(client.query(inspect_obj_table_query))

Esegui la cella di codice.

I risultati dovrebbero essere simili ai seguenti:

Salva il notebook come met-image-analysis.

Crea il modello remoto

Crea un modello remoto che rappresenti un modello di embedding multimodale Vertex AI ospitato:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nell'editor di query, esegui la seguente query:
```
CREATE OR REPLACE MODEL `bqml_tutorial.multimodal_embedding_model`
  REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
  OPTIONS (ENDPOINT = 'multimodalembedding@001');
```
Sostituisci quanto segue:
- LOCATION: la posizione della connessione.
- CONNECTION_ID: l'ID della connessione BigQuery.
  Quando visualizzi i dettagli della connessione nella console Google Cloud, questo è il valore nell'ultima sezione dell'ID connessione visualizzato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection.
Il completamento della query richiede diversi secondi, dopodiché il modello multimodal_embedding_model viene visualizzato nel set di dati bqml_tutorial nel riquadro Explorer. Poiché la query utilizza un'istruzione CREATE MODEL per creare un modello, non ci sono risultati della query.

Genera embedding di immagini

Genera gli embedding dalle immagini nella tabella degli oggetti utilizzando la funzione ML.GENERATE_EMBEDDING, quindi scrivili in una tabella per usarli in un passaggio successivo. La generazione di incorporamenti è un'operazione dispendiosa, pertanto la query utilizza una sottoquery che include la clausola LIMIT per limitare la generazione di incorporamenti a 10.000 immagini anziché incorporare l'intero set di dati di 601.294 immagini. In questo modo,il numero di immagini rimane al di sotto del limite di 25.000 per la funzione ML.GENERATE_EMBEDDING. L'esecuzione di questa query richiede circa 40 minuti.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery

Nell'editor di query, esegui la seguente query:

CREATE OR REPLACE TABLE `bqml_tutorial.met_image_embeddings`
AS
SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `bqml_tutorial.multimodal_embedding_model`,
    (SELECT * FROM `bqml_tutorial.met_images` WHERE content_type = 'image/jpeg' LIMIT 10000))

Correggi eventuali errori di generazione dell'embedding

Controlla e correggi eventuali errori di generazione dell'embedding. La generazione di embedding può non riuscire a causa delle quote dell'IA generativa su Vertex AI o della mancata disponibilità del servizio.

La funzione ML.GENERATE_EMBEDDING restituisce i dettagli dell'errore nella colonna ml_generate_embedding_status. Questa colonna è vuota se la generazione di incorporamento è andata a buon fine o contiene un messaggio di errore se la generazione di incorporamento non è riuscita.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery

Nell'editor di query, esegui la seguente query per verificare se si sono verificati errori di generazione dell'embedding:

SELECT DISTINCT(ml_generate_embedding_status),
  COUNT(uri) AS num_rows
FROM bqml_tutorial.met_image_embeddings
GROUP BY 1;

Se vengono restituite righe con errori, elimina le righe in cui la generazione di embedding non è riuscita:

DELETE FROM `bqml_tutorial.met_image_embeddings`
WHERE ml_generate_embedding_status = 'A retryable error occurred: RESOURCE_EXHAUSTED error from remote service/endpoint.';

Creare un indice di vettori

Facoltativamente, puoi utilizzare l'istruzione CREATE VECTOR INDEX per creare l'indice vettoriale met_images_index nella colonna ml_generate_embedding_result della tabella met_images_embeddings. Un indice vettoriale ti consente di eseguire una ricerca vettoriale più rapidamente, con il compromesso di ridurre il richiamo e quindi restituire risultati più approssimativi.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery

Nell'editor di query, esegui la seguente query:

CREATE OR REPLACE
  VECTOR INDEX `met_images_index`
ON
  bqml_tutorial.met_image_embeddings(ml_generate_embedding_result)
  OPTIONS (
    index_type = 'IVF',
    distance_type = 'COSINE');

L'indice vettoriale viene creato in modo asincrono. Per verificare se l'indice del vettore è stato creato, esegui una query sulla visualizzazione INFORMATION_SCHEMA.VECTOR_INDEXES e verifica che il valore coverage_percentage sia maggiore di 0 e che il valore last_refresh_time non sia NULL:
```
SELECT table_name, index_name, index_status,
  coverage_percentage, last_refresh_time, disable_reason
FROM bqml_tutorial.INFORMATION_SCHEMA.VECTOR_INDEXES
WHERE index_name = 'met_images_index';
```

Genera un embedding per il testo di ricerca

Per cercare le immagini corrispondenti a una stringa di ricerca di testo specificata, devi prima creare un'evidenziazione del testo per quella stringa. Utilizza lo stesso modello remoto per creare l'embedding di testo che hai utilizzato per creare gli embedding di immagini, quindi scrivi l'embedding di testo in una tabella per utilizzarlo in un passaggio successivo. La stringa di ricerca è pictures of white or cream colored dress from victorian era.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery

Nell'editor di query, esegui la seguente query:

CREATE OR REPLACE TABLE `bqml_tutorial.search_embedding`
AS
SELECT * FROM ML.GENERATE_EMBEDDING(
  MODEL `bqml_tutorial.multimodal_embedding_model`,
  (
    SELECT 'pictures of white or cream colored dress from victorian era' AS content
  )
);

Esegui una ricerca di testo a immagine cross-modalità

Utilizza la funzione VECTOR_SEARCH per cercare le immagini che corrispondono meglio alla stringa di ricerca rappresentata dall'embedding del testo, quindi scrivitele in una tabella per usarle in un passaggio successivo.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery

Nell'editor di query, esegui la seguente query:

CREATE OR REPLACE TABLE `bqml_tutorial.vector_search_results` AS
SELECT base.uri AS gcs_uri, distance
FROM
  VECTOR_SEARCH(
    TABLE `bqml_tutorial.met_image_embeddings`,
    'ml_generate_embedding_result',
    TABLE `bqml_tutorial.search_embedding`,
    'ml_generate_embedding_result',
    top_k => 3);

Visualizza i risultati di ricerca vettoriale

Visualizza i risultati di ricerca di vettori utilizzando un notebook.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Apri il notebook met-image-analysis che hai creato in precedenza.
Visualizza i risultati di ricerca vettoriale:
1. Aggiungi una cella di codice al notebook.
2. Copia e incolla il seguente codice nella cella di codice:
```
query = """
  SELECT * FROM `bqml_tutorial.vector_search_results`
  ORDER BY distance;
"""

printImages(client.query(query))
```
3. Esegui la cella di codice.
  
  I risultati dovrebbero essere simili ai seguenti:

Esegui la pulizia

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un appspot.com URL, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.