Genera rappresentazioni distribuite di testo utilizzando la funzione ML.GENERATE_EMBEDDING

Questo documento mostra come creare un modello remoto BigQuery ML che fa riferimento a un modello di embedding Vertex AI. Poi, utilizza il modello con la funzione ML.GENERATE_EMBEDDING per creare embedding di testo utilizzando i dati di una tabella standard BigQuery.

Ruoli obbligatori

  • Per creare una connessione, devi disporre dell'appartenenza al seguente ruolo IAM (Identity and Access Management):

    • roles/bigquery.connectionAdmin

  • Per concedere le autorizzazioni all'account di servizio della connessione, devi disporre della seguente autorizzazione:

    • resourcemanager.projects.setIamPolicy

  • Per creare il modello utilizzando BigQuery ML, sono necessarie le seguenti autorizzazioni IAM:

    • bigquery.jobs.create
    • bigquery.models.create
    • bigquery.models.getData
    • bigquery.models.updateData
    • bigquery.models.updateMetadata

  • Per eseguire l'inferenza, devi disporre delle seguenti autorizzazioni:

    • bigquery.tables.getData sul tavolo
    • bigquery.models.getData sul modello
    • bigquery.jobs.create

Prima di iniziare

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

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

    Enable the APIs

Crea un set di dati

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

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai alla pagina BigQuery

  2. Nel riquadro Explorer, fai clic sul nome del progetto.

  3. Fai clic su Visualizza azioni > Crea set di dati.

    Crea il set di dati.

  4. 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.

      Pagina Crea set di dati.

Crea una connessione

Crea una connessione risorsa Cloud e recupera l'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

  1. Vai alla pagina BigQuery.

    Vai a BigQuery

  2. Per creare una connessione, fai clic su Aggiungi e poi su Connessioni a origini dati esterne.

  3. Nell'elenco Tipo di connessione, seleziona Modelli remoti di Vertex AI, funzioni remote e BigLake (risorsa Cloud).

  4. Nel campo ID connessione, inserisci un nome per la connessione.

  5. Fai clic su Crea connessione.

  6. Fai clic su Vai alla connessione.

  7. Nel riquadro Informazioni sulla connessione, copia l'ID account di servizio da utilizzare in un passaggio successivo.

bq

  1. 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...

  2. 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ù, consulta 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

  1. Avvia Cloud Shell.

  2. 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).

  1. 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

  2. Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

    Copia il codice campione nel 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.

  3. Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
  4. Salva le modifiche.
  5. 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

  1. 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.

  2. Applica la configurazione di Terraform eseguendo il seguente comando e inserendo yes al prompt: 
    terraform apply

    Attendi che Terraform mostri il messaggio "Applicazione completata".

  3. 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 l'accesso all'account di servizio

Concedi all'account di servizio della connessione il ruolo Utente Vertex AI.

Se prevedi di specificare l'endpoint come URL quando crei il modello remoto, ad esempio endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/text-embedding-004', concedi questo ruolo nello stesso progetto specificato nell'URL.

Se prevedi di specificare l'endpoint utilizzando il nome del modello quando crei il modello remoto, ad esempio endpoint = 'text-embedding-004', concedi questo ruolo nello stesso progetto in cui prevedi di creare il modello remoto.

Se concedi il ruolo 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 il ruolo, segui questi passaggi:

Console

  1. Vai alla pagina IAM e amministrazione.

    Vai a IAM e amministrazione

  2. Fai clic su Concedi accesso.

    Viene visualizzata la finestra di dialogo Aggiungi entità.

  3. Nel campo Nuove entità, inserisci l'ID account di servizio che hai copiato in precedenza.

  4. Nel campo Seleziona un ruolo, seleziona Vertex AI e poi Utente Vertex AI.

  5. Fai clic su Salva.

gcloud

Utilizza il comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero del progetto
  • MEMBER: l'ID account di servizio che hai copiato in precedenza

crea un modello

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Utilizzando l'editor SQL, crea un modello remoto:

    CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `CONNECTION_ID`
OPTIONS (ENDPOINT = 'ENDPOINT');

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto
    • DATASET_ID: l'ID del set di dati che deve contenere il modello
    • MODEL_NAME: il nome del modello
    • 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 completo visualizzato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection

    • ENDPOINT: il nome del modello di embedding da utilizzare. Deve essere un modello text-embedding, text-multilingual-embedding o multimodalembedding. Per ulteriori informazioni sulle versioni e sugli alias del modello supportati, consulta ENDPOINT.

Generare rappresentazioni distribuite di testo utilizzando i dati di una tabella

Genera embedding di testo con la funzione ML.GENERATE_EMBEDDING utilizzando i dati di testo di una colonna della tabella.

In genere, è consigliabile utilizzare un modello text-embedding o text-multilingual-embedding per i casi d'uso di solo testo e un modello multimodalembedding per i casi d'uso di ricerca cross-modale, in cui gli embedding per i contenuti di testo e visivi vengono generati nello stesso spazio semantico.

text embedding

Genera embedding di testo utilizzando un modello remoto su un modello di embedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • DATASET_ID: l'ID del set di dati che contiene il modello.
  • MODEL_NAME: il nome del modello remoto su un modello di embedding.
  • TABLE_NAME: il nome della tabella che contiene il testo da incorporare. Questa tabella deve avere una colonna denominata content oppure puoi utilizzare un alias per utilizzare una colonna con un nome diverso.
  • FLATTEN_JSON: un valore BOOL che indica se analizzare l'embedding in una colonna separata. Il valore predefinito è TRUE.
  • TASK_TYPE: un valore letterale STRING che specifica l'applicazione a valle prevista per aiutare il modello a produrre incorporamenti di qualità migliore. TASK_TYPE accetta i seguenti valori:
    • RETRIEVAL_QUERY: specifica che il testo specificato è una query in un'impostazione di ricerca o recupero.
    • RETRIEVAL_DOCUMENT: specifica che il testo specificato è un documento in un'impostazione di ricerca o recupero.

      Quando utilizzi questo tipo di attività, è utile includere il titolo del documento nell'istruzione di query per migliorare la qualità dell'embedding. Puoi utilizzare l'opzione title per specificare il nome della colonna che contiene il titolo del documento, altrimenti il titolo del documento deve trovarsi in una colonna denominata title o con alias title, ad esempio: 

            SELECT *
      FROM
        ML.GENERATE_EMBEDDING(
          MODEL mydataset.embedding_model,
          (SELECT abstract as content, header as title, publication_number
          FROM mydataset.publications),
          STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
      );
    • SEMANTIC_SIMILARITY: specifica che il testo specificato verrà utilizzato per la somiglianza testuale semantica (STS).
    • CLASSIFICATION: specifica che le rappresentazioni distribuite verranno impiegate per la classificazione.
    • CLUSTERING: specifica che gli incorporamenti verranno utilizzati per il clustering.
  • OUTPUT_DIMENSIONALITY: un valore INT64 che specifica il numero di dimensioni da utilizzare per la generazione degli embedding. Ad esempio, se specifichi 256 AS output_dimensionality, la colonna di output ml_generate_embedding_result contiene 256 embedding per ogni valore di input.

    Puoi utilizzare questo argomento solo se il modello remoto specificato nell'argomento model utilizza uno dei seguenti modelli come endpoint:

    • text-embedding-004 o versioni successive
    • text-multilingual-embedding-002 o versioni successive

embedding multimodale

Genera rappresentazioni distribuite di testo utilizzando un modello remoto sul modello multimodalembedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output，
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • DATASET_ID: l'ID del set di dati che contiene il modello.
  • MODEL_NAME: il nome del modello remoto su un modello multimodalembedding@001.
  • TABLE_NAME: il nome della tabella che contiene il testo da incorporare. Questa tabella deve avere una colonna denominata content oppure puoi utilizzare un alias per utilizzare una colonna con un nome diverso.
  • FLATTEN_JSON: un BOOL che indica se analizzare l'embedding in una colonna separata. Il valore predefinito è TRUE.
  • OUTPUT_DIMENSIONALITY: un valore INT64 che specifica il numero di dimensioni da utilizzare per la generazione degli embedding. I valori validi sono 128, 256, 512 e 1408. Il valore predefinito è 1408. Ad esempio, se specifichi 256 AS output_dimensionality, la colonna di output ml_generate_embedding_result contiene 256 embedding per ogni valore di input.

Genera embedding di testo utilizzando i dati di una query

Genera incorporamenti di testo con la funzione ML.GENERATE_EMBEDDING utilizzando i dati di testo forniti da una query e da un modello remoto su un modello di incorporamento.

In genere, è consigliabile utilizzare un modello text-embedding o text-multilingual-embedding per i casi d'uso di solo testo e un modello multimodalembedding per i casi d'uso di ricerca cross-modale, in cui gli embedding per i contenuti di testo e visivi vengono generati nello stesso spazio semantico.

text embedding

Genera rappresentazioni distribuite di testo utilizzando un modello remoto sul modello di embedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • DATASET_ID: l'ID del set di dati che contiene il modello.
  • MODEL_NAME: il nome del modello remoto su un modello di embedding.
  • CONTENT_QUERY: una query il cui risultato contiene una colonna STRING denominata content.
  • FLATTEN_JSON: un valore BOOL che indica se analizzare l'embedding in una colonna separata. Il valore predefinito è TRUE.
  • TASK_TYPE: un valore letterale STRING che specifica l'applicazione a valle prevista per aiutare il modello a produrre incorporamenti di qualità migliore. TASK_TYPE accetta i seguenti valori:
    • RETRIEVAL_QUERY: specifica che il testo specificato è una query in un'impostazione di ricerca o recupero.
    • RETRIEVAL_DOCUMENT: specifica che il testo specificato è un documento in un'impostazione di ricerca o recupero.

      Quando utilizzi questo tipo di attività, è utile includere il titolo del documento nell'istruzione di query per migliorare la qualità dell'embedding. Puoi utilizzare l'opzione title per specificare il nome della colonna che contiene il titolo del documento, altrimenti il titolo del documento deve essere in una colonna denominata title o con alias title, ad esempio: 

                SELECT *
          FROM
            ML.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.publications),
              STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
          );
    • SEMANTIC_SIMILARITY: specifica che il testo specificato verrà utilizzato per la somiglianza testuale semantica (STS).
    • CLASSIFICATION: specifica che le rappresentazioni distribuite verranno utilizzate per la classificazione.
    • CLUSTERING: specifica che gli incorporamenti verranno utilizzati per il clustering.
  • OUTPUT_DIMENSIONALITY: un valore INT64 che specifica il numero di dimensioni da utilizzare per la generazione degli embedding. Ad esempio, se specifichi 256 AS output_dimensionality, la colonna di output ml_generate_embedding_result contiene 256 embedding per ogni valore di input.

    Puoi utilizzare questo argomento solo se il modello remoto specificato nell'argomento model utilizza uno dei seguenti modelli come endpoint:

    • text-embedding-004 o versioni successive
    • text-multilingual-embedding-002 o versioni successive

embedding multimodale

Genera rappresentazioni distribuite di testo utilizzando un modello remoto sul modello multimodalembedding:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto.
  • DATASET_ID: l'ID del set di dati che contiene il modello.
  • MODEL_NAME: il nome del modello remoto su un modello multimodalembedding@001.
  • CONTENT_QUERY: una query il cui risultato contiene una colonna STRING denominata content.
  • FLATTEN_JSON: un BOOL che indica se analizzare l'embedding in una colonna separata. Il valore predefinito è TRUE.
  • OUTPUT_DIMENSIONALITY: un valore INT64 che specifica il numero di dimensioni da utilizzare per la generazione degli embedding. I valori validi sono 128, 256, 512 e 1408. Il valore predefinito è 1408. Ad esempio, se specifichi 256 AS output_dimensionality, la colonna di output ml_generate_embedding_result contiene 256 embedding per ogni valore di input.

Esempi

Gli esempi riportati di seguito mostrano come chiamare la funzione ML.GENERATE_EMBEDDING su una tabella e una query.

Incorporare il testo in una tabella

L'esempio seguente mostra una richiesta di incorporamento della colonna content della tabella text_data:

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT(TRUE AS flatten_json_output, 'CLASSIFICATION' AS task_type)
  );

Utilizzare gli embedding per classificare la somiglianza semantica

L'esempio seguente incorpora una raccolta di recensioni di film e le ordina in base alla distanza di coseno rispetto alla recensione "Questo film era nella media" utilizzando la funzione ML.DISTANCE. Una distanza minore indica una maggiore somiglianza semantica.

WITH movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "Movie 1" AS title, "This movie was fantastic" AS content
        UNION ALL
        SELECT "Movie 2" AS title, "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "Movie 3" AS title, "This movie was just okay..." AS content
        UNION ALL
        SELECT "Movie 4" AS title, "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
),
average_review_embedding AS (
  SELECT ml_generate_embedding_result
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content),
      STRUCT(TRUE AS flatten_json_output)
    )
)
SELECT
  content,
  ML.DISTANCE(
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    ml_generate_embedding_result,
    'COSINE'
  ) AS distance_to_average_review
FROM
  movie_review_embeddings
ORDER BY distance_to_average_review;

Il risultato è il seguente:

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+