Generare incorporamenti di testo utilizzando la funzione ML.GENERATE_YOURDING

Questo documento mostra come creare un modello remoto di BigQuery ML che fa riferimento a un model di incorporamento di Vertex AI. Potrai quindi utilizzare questo modello con la funzione ML.GENERATE_EMBEDDING per creare incorporamenti di testo utilizzando i dati di una tabella standard BigQuery.

Ruoli obbligatori

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

  • 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, devi disporre delle 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 in tavola
  • 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.

   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

2. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

3. Abilita le API BigQuery, BigQuery Connection, and Vertex AI.

   Abilita le API

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 di BigQuery

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

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

   

4. Nella pagina Crea set di dati, segui questi passaggi:

   • 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 vengono archiviati in US più regioni. Per semplicità, archivia il tuo set di dati nella stessa località.

   • Lascia invariate le restanti impostazioni predefinite e fai clic su Crea set di dati.

     

Crea una connessione

Crea una connessione alle risorse Cloud e recupera l'account di servizio della connessione. Crea la connessione nella stessa località del set di dati che hai 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 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 per utilizzarlo 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 tua regione di connessione
   • PROJECT_ID: l'ID del tuo progetto Google Cloud
   • CONNECTION_ID: un ID per la tua connessione

   Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco e lo associa alla connessione.

   Risoluzione dei problemi: se viene visualizzato 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": "[e-mail]"}
   

Terraform

Aggiungi la seguente sezione al tuo file main.tf.

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}        

Sostituisci quanto segue:

• CONNECTION_ID: un ID per la tua connessione
• PROJECT_ID: l'ID del tuo progetto Google Cloud
• REGION: la tua regione di connessione

Concedi all'account di servizio l'accesso

Concedi al tuo account di servizio l'autorizzazione per utilizzare la connessione. Se non concedi l'autorizzazione, verrà visualizzato un errore. Seleziona una delle seguenti opzioni:

Console

1. Vai alla pagina IAM e amministrazione.

   Vai a IAM e amministrazione

2. Fai clic su Concedi l'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, quindi Utente Vertex AI.

5. Fai clic su Salva.

gcloud

Usa 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 tuo 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 `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (ENDPOINT = 'ENDPOINT');
   

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto
   • DATASET_ID: l'ID del set di dati che conterrà il modello
   • MODEL_NAME: il nome del modello
   • REGION: la regione utilizzata dalla connessione
   • CONNECTION_ID: l'ID della tua connessione BigQuery

     Quando visualizzi i dettagli della connessione nella console Google Cloud, si tratta del valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection

   • ENDPOINT: il model di incorporamento da utilizzare. Ad esempio: ENDPOINT='multimodalembedding'.

     Per alcuni tipi di modelli, puoi specificare una particolare versione del modello. Per informazioni sulle versioni dei modelli supportate per i diversi tipi di modelli, consulta ENDPOINT.

Nota: puoi creare un modello remoto su un modello Vertex AI textembedding-gecko specificando il valore REMOTE_SERVICE_TYPE come "CLOUD_AI_TEXT_YOURDING_MODEL_V1". Tuttavia, il metodo preferito per la creazione di un modello remoto rispetto a un modello è specificare il modello come endpoint, come mostrato qui.

Genera incorporamenti di testo utilizzando i dati di una tabella

Generare incorporamenti di testo con la funzione ML.GENERATE_EMBEDDING utilizzando i dati di testo di una colonna della tabella.

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

incorporamento del testo

Genera incorporamenti di testo utilizzando un modello remoto sul modello text-embedding o text-multilingual-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 rispetto a un modello text-embedding o text-multilingual-embedding.
• TABLE_NAME: il nome della tabella che contiene il testo da incorporare. Questa tabella deve avere una colonna denominata content. In alternativa, puoi utilizzare un alias per utilizzare una colonna con un nome diverso.
• FLATTEN_JSON: un valore BOOL che indica se analizzare l'incorporamento in una colonna separata. Il valore predefinito è TRUE.
• TASK_TYPE: un valore letterale STRING che specifica l'applicazione downstream 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 fornito è un documento in un'impostazione di ricerca o recupero.

    Quando utilizzi questo tipo di attività, è utile includere il titolo del documento nell'istruzione della query per migliorare la qualità dell'incorporamento. 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 gli incorporamenti verranno utilizzati 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 durante la generazione degli incorporamenti. Ad esempio, se specifichi 256 AS output_dimensionality, la colonna di output ml_generate_embedding_result contiene 256 incorporamenti 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

incorporamento multimodale

Genera incorporamenti 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)
);

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 rispetto a un modello multimodalembedding@001.
• TABLE_NAME: il nome della tabella che contiene il testo da incorporare. Questa tabella deve avere una colonna denominata content. In alternativa, puoi utilizzare un alias per utilizzare una colonna con un nome diverso.
• FLATTEN_JSON: un BOOL che indica se analizzare l'incorporamento in una colonna separata. Il valore predefinito è TRUE.

Genera incorporamenti 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 un modello remoto sul modello text-embedding o text-multilingual-embedding:

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

incorporamento del testo

Genera incorporamenti di testo utilizzando un modello remoto sul modello text-embedding o text-multilingual-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 rispetto a un modello textembedding-gecko o text-multilingual-embedding.
• CONTENT_QUERY: una query il cui risultato contiene una colonna STRING denominata content.
• FLATTEN_JSON: un valore BOOL che indica se analizzare l'incorporamento in una colonna separata. Il valore predefinito è TRUE.
• TASK_TYPE: un valore letterale STRING che specifica l'applicazione downstream 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 fornito è un documento in un'impostazione di ricerca o recupero.

    Quando utilizzi questo tipo di attività, è utile includere il titolo del documento nell'istruzione della query per migliorare la qualità dell'incorporamento. 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 gli incorporamenti verranno utilizzati 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 durante la generazione degli incorporamenti. Ad esempio, se specifichi 256 AS output_dimensionality, la colonna di output ml_generate_embedding_result contiene 256 incorporamenti 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

incorporamento multimodale

Genera incorporamenti 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)
);

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 rispetto a 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'incorporamento in una colonna separata. Il valore predefinito è TRUE.

Esempi

Gli esempi seguenti mostrano come chiamare la funzione ML.GENERATE_EMBEDDING su una tabella e una query.

Incorporare testo in una tabella

L'esempio seguente mostra una richiesta per incorporare la 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)
  );

Utilizzare gli incorporamenti per classificare la somiglianza semantica

L'esempio seguente incorpora una raccolta di recensioni di film e le ordina in base alla distanza in base 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 fantastic                 | 0.10028859431058901        |
| This movie was terrible.                 |   0.142427236973374        |
| This was the best movie I've ever seen!! | 0.46742391210381995        |
| This movie was just okay...              | 0.47399255715360622        |
+------------------------------------------+----------------------------+