Questa pagina è stata tradotta dall'API Cloud Translation.

Generare testo utilizzando un modello aperto Gemma e la funzione ML.GENERATE_TEXT

Questo tutorial mostra come creare un modello remoto basato sul modello Gemma, e poi come utilizzarlo con la funzione ML.GENERATE_TEXT per estrarre le parole chiave ed eseguire l'analisi del sentiment sulle recensioni dei film dalla tabella pubblica bigquery-public-data.imdb.reviews.

Autorizzazioni obbligatorie

Per creare il set di dati, devi disporre dell'autorizzazione bigquery.datasets.create Identity and Access Management (IAM).
Per creare la risorsa di connessione, sono necessarie le seguenti autorizzazioni IAM:
- bigquery.connections.create
- bigquery.connections.get
Per concedere le autorizzazioni all'account di servizio della connessione, devi disporre della seguente autorizzazione:
- resourcemanager.projects.setIamPolicy
Per creare il modello, devi disporre delle seguenti autorizzazioni:
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.connections.delegate
Per eseguire l'inferenza, devi disporre delle seguenti autorizzazioni:
- bigquery.models.getData
- bigquery.jobs.create

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 model that's represented by the remote model.

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi Google Cloud utenti potrebbero avere diritto a una prova gratuita.

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

I modelli aperti di cui esegui il deployment in Vertex AI vengono addebitati per ora macchina. Ciò significa che la fatturazione inizia non appena l'endpoint è completamente configurato e continua fino a quando non viene annullato il deployment. 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

Esegui il deployment di un modello Gemma su Vertex AI

Esegui il deployment del gemma-2-27b-it modello in Vertex AI seguendo le istruzioni riportate in Eseguire il deployment dei modelli di Model Garden.

Crea un set di dati

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

Console

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 tuo set di dati nella stessa posizione.
- Lascia invariate le restanti impostazioni predefinite e fai clic su Crea set di dati.

bq

Per creare un nuovo set di dati, utilizza il comando bq mk con il flag --location. Per un elenco completo dei possibili parametri, consulta la documentazione di riferimento del comando bq mk --dataset.

Crea un set di dati denominato bqml_tutorial con la posizione dei dati impostata su US e una descrizione di BigQuery ML tutorial dataset:
```
bq --location=US mk -d \
 --description "BigQuery ML tutorial dataset." \
 bqml_tutorial
```
Anziché utilizzare il flag --dataset, il comando utilizza la scorciatoia -d. Se ometti -d e --dataset, il comando crea per impostazione predefinita un set di dati.
Verifica che il set di dati sia stato creato:
```
bq ls
```

API

Chiama il metodo datasets.insert con una risorsa set di dati definita.

{
  "datasetReference": {
     "datasetId": "bqml_tutorial"
  }
}

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

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ù, 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

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 di esempio in ogni sezione o passaggio.

Copia il codice di esempio 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.
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 il ruolo Utente Vertex AI. Devi concedere questo ruolo nello stesso progetto che hai creato o selezionato nella sezione Prima di iniziare. 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:

Vai alla pagina IAM e amministrazione.

Vai a IAM e amministrazione
Fai clic su Concedi 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 Ruolo utente Vertex AI.
Fai clic su Salva.

Crea il modello remoto

Crea un modello remoto che rappresenti un modello Vertex AI ospitato:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nell'editor di query, esegui la seguente istruzione:

CREATE OR REPLACE MODEL `bqml_tutorial.gemma_model`
  REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID`
  OPTIONS (ENDPOINT = 'https://ENDPOINT_REGION-aiplatform.googleapis.com/v1/projects/ENDPOINT_PROJECT_ID/locations/ENDPOINT_REGION/endpoints/ENDPOINT_ID');

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.
ENDPOINT_REGION: la regione in cui è stato eseguito il deployment del modello aperto.
ENDPOINT_PROJECT_ID: il progetto in cui è disegnato il modello aperto.
ENDPOINT_ID: l'ID dell'endpoint HTTPS utilizzato dal modello aperto. Puoi ottenere l'ID endpoint individuando il modello aperto nella pagina Previsione online e copiando il valore nel campo ID.

L'esempio seguente mostra il formato di un endpoint HTTP valido:

https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234.

Il completamento della query richiede alcuni secondi, dopodiché il modello gemma_model viene visualizzato nel set di dati bqml_tutorial nel riquadro Esplorazione. Poiché la query utilizza un'istruzione CREATE MODEL per creare un modello, non esistono risultati della query.

Eseguire l'estrazione delle parole chiave

Esegui l'estrazione delle parole chiave dalle recensioni dei film di IMDB utilizzando il modello remoto e la funzione ML.GENERATE_TEXT:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery

Nell'editor di query, inserisci la seguente istruzione per eseguire l'estrazione delle parole chiave da cinque recensioni di film:

SELECT
  *
FROM
  ML.GENERATE_TEXT(
    MODEL `bqml_tutorial.gemma_model`,
    (
      SELECT
        CONCAT('Extract the key words from the movie review below: ', review) AS prompt,
        *
      FROM
        `bigquery-public-data.imdb.reviews`
      LIMIT 10
    ),
    STRUCT(
      0.2 AS temperature,
      100 AS max_output_tokens,
      TRUE AS flatten_json_output));

L'output è simile al seguente, con le colonne non generate omesse per chiarezza:

+----------------------------------------------+-------------------------+-----------------------------+-----+
| generated_text                               | ml_generate_text_status | prompt                      | ... |
+----------------------------------------------+-------------------------------------------------------+-----+
| Here are some key words from the             |                         | Extract the key words from  |     |
| movie review: * **Romance:**                 |                         | the movie review below:     |     |
| "romantic tryst," "elope" * **Comedy:**      |                         | Linda Arvidson (as Jennie)  |     |
| "Contrived Comedy" * **Burglary:**           |                         | and Harry Solter (as Frank) |     |
| "burglar," "rob," "booty" * **Chase:**       |                         | are enjoying a romantic     |     |
| "chases," "escape" * **Director:** "D.W.     |                         | tryst, when in walks her    |     |
| Griffith" * **Actors:** "Linda Arvidson,"... |                         | father Charles Inslee;...   |     |
+----------------------------------------------+-------------------------+-----------------------------+-----+
| Here are some key words from the             |                         | Extract the key words from  |     |
| movie review: * **Elderbush Gilch:** The     |                         | the movie review below:     |     |
| name of the movie being reviewed. *          |                         | This is the second addition |     |
| **Disappointment:** The reviewer's           |                         | to Frank Baum's personally  |     |
| overall feeling about the film. *            |                         | produced trilogy of Oz      |     |
| **Dim-witted:** Describes the story          |                         | films. It's essentially the |     |
| line negatively. * **Moronic, sadistic,...   |                         | same childishness as the... |     |
+----------------------------------------------+-------------------------+-----------------------------+-----+

I risultati includono le seguenti colonne:

generated_text: il testo generato.
ml_generate_text_status: lo stato della risposta dell'API per la riga corrispondente. Se l'operazione è andata a buon fine, questo valore è vuoto.
prompt: il prompt utilizzato per l'analisi del sentiment.
Tutte le colonne della tabella bigquery-public-data.imdb.reviews.

Esegui l'analisi del sentiment

Esegui l'analisi del sentiment sulle recensioni dei film di IMDB utilizzando il modello remoto e la funzione ML.GENERATE_TEXT:

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery

Nell'editor di query, esegui la seguente istruzione per eseguire l'analisi del sentiment su cinque recensioni di film:

SELECT
  *
FROM
  ML.GENERATE_TEXT(
    MODEL `bqml_tutorial.gemma_model`,
    (
      SELECT
        CONCAT('Analyze the sentiment of the following movie review and classify it as either POSITIVE or NEGATIVE. \nMovie Review: ', review) AS prompt,
        *
      FROM
        `bigquery-public-data.imdb.reviews`
      LIMIT 10
    ),
    STRUCT(
      0.2 AS temperature,
      128 AS max_output_tokens,
      TRUE AS flatten_json_output));

L'output è simile al seguente, con le colonne non generate omesse per chiarezza:

+----------------------------------------------+-------------------------+-----------------------------+-----+
| generated_text                               | ml_generate_text_status | prompt                      | ... |
+----------------------------------------------+-------------------------------------------------------+-----+
| **Sentiment:** NEGATIVE **Justification:**   |                         | Analyze the sentiment of    |     |
| * **Negative Language:** The reviewer uses   |                         | movie review and classify   |     |
| phrases like "don't quite make it," "come to |                         | it as either POSITIVE or    |     |
| mind," "quite disappointing," and "not many  |                         | NEGATIVE. Movie Review:     |     |
| laughs." * **Specific Criticisms:** The      |                         | Although Charlie Chaplin    |     |
| reviewer points out specific flaws in the    |                         | made some great short       |     |
| plot and humor, stating that the manager...  |                         | comedies in the late...     |     |
+----------------------------------------------+-------------------------+-----------------------------+-----+
| **Sentiment:** NEGATIVE **Reasoning:**       |                         | Analyze the sentiment of    |     |
| * **Negative Language:** The reviewer uses   |                         | movie review and classify   |     |
| phrases like "poor writing," "static camera- |                         | it as either POSITIVE or    |     |
| work," "chews the scenery," "all surface and |                         | NEGATIVE. Movie Review:     |     |
| no depth," "sterile spectacles," which all   |                         | Opulent sets and sumptuous  |     |
| carry negative connotations. * **Comparison  |                         | costumes well photographed  |     |
| to a More Successful Film:**...              |                         | by Theodor Sparkuhl, and... |     |
+----------------------------------------------+-------------------------+-----------------------------+-----+

I risultati includono le stesse colonne descritte per Eseguire l'estrazione delle parole chiave.

Annulla il deployment del modello

Se scegli di non eliminare il progetto come consigliato, assicurati di annullare il deployment del modello Gemma in Vertex AI per evitare la fatturazione continua.

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 URL appspot.com, 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.