gemini-2.5-flash
e come utilizzare questo modello con la
funzione AI.GENERATE_TEXT
per estrarre parole chiave ed eseguire l'analisi del sentiment.
Costi
In questo documento vengono utilizzati 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 in base all'utilizzo previsto,
utilizza il calcolatore prezzi.
Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per saperne di più, consulta Esegui la pulizia.
Prima di iniziare
Console
- Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
Assicurati di disporre dei seguenti ruoli nel progetto: Amministratore BigQuery, Amministratore IAM progetto
Controlla i ruoli
-
Nella console Google Cloud vai alla pagina IAM.
Vai a IAM - Seleziona il progetto.
-
Nella colonna Entità, trova tutte le righe che identificano te o un gruppo di cui fai parte. Per scoprire a quali gruppi appartieni, contatta il tuo amministratore.
- Per tutte le righe che ti specificano o ti includono, controlla la colonna Ruolo per verificare se l'elenco dei ruoli include i ruoli richiesti.
Concedi i ruoli
-
Nella console Google Cloud vai alla pagina IAM.
Vai a IAM - Seleziona il progetto.
- Fai clic su Concedi l'accesso.
-
Nel campo Nuove entità, inserisci il tuo identificatore dell'utente. In genere si tratta dell'indirizzo email di un Account Google.
- Fai clic su Seleziona un ruolo, quindi cerca il ruolo.
- Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.
- Fai clic su Salva.
-
gcloud
- Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
-
Installa Google Cloud CLI.
-
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
-
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init -
Crea o seleziona un Google Cloud progetto.
Ruoli richiesti per selezionare o creare un progetto
- Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
-
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto
(
roles/resourcemanager.projectCreator), che contiene l'autorizzazioneresourcemanager.projects.create. Scopri come concedere i ruoli.
-
Creare un progetto Google Cloud :
gcloud projects create PROJECT_ID
Sostituisci
PROJECT_IDcon un nome per il progetto Google Cloud che stai creando. -
Seleziona il progetto Google Cloud che hai creato:
gcloud config set project PROJECT_ID
Sostituisci
PROJECT_IDcon il nome del progetto Google Cloud .
-
Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .
Abilita le API BigQuery, BigQuery Connection e Vertex AI:
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (
roles/serviceusage.serviceUsageAdmin), che include l'autorizzazioneserviceusage.services.enable. Scopri come concedere i ruoli.gcloud services enable bigquery.googleapis.com
bigqueryconnection.googleapis.com aiplatform.googleapis.com -
Installa Google Cloud CLI.
-
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.
-
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init -
Crea o seleziona un Google Cloud progetto.
Ruoli richiesti per selezionare o creare un progetto
- Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
-
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto
(
roles/resourcemanager.projectCreator), che contiene l'autorizzazioneresourcemanager.projects.create. Scopri come concedere i ruoli.
-
Creare un progetto Google Cloud :
gcloud projects create PROJECT_ID
Sostituisci
PROJECT_IDcon un nome per il progetto Google Cloud che stai creando. -
Seleziona il progetto Google Cloud che hai creato:
gcloud config set project PROJECT_ID
Sostituisci
PROJECT_IDcon il nome del progetto Google Cloud .
-
Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .
Abilita le API BigQuery, BigQuery Connection e Vertex AI:
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (
roles/serviceusage.serviceUsageAdmin), che include l'autorizzazioneserviceusage.services.enable. Scopri come concedere i ruoli.gcloud services enable bigquery.googleapis.com
bigqueryconnection.googleapis.com aiplatform.googleapis.com -
Concedi ruoli al tuo account utente. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM:
roles/bigquery.admin, roles/resourcemanager.projectIamAdmingcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto.USER_IDENTIFIER: l'identificatore del tuo account utente . Ad esempio:myemail@example.com.ROLE: il ruolo IAM che concedi al tuo account utente.
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.
Nel riquadro Explorer, fai clic sul nome del progetto.
Fai clic su Visualizza azioni > Crea set di dati.
Nella pagina Crea set di dati, segui questi passaggi:
In ID set di dati, inserisci
bqml_tutorial.Per Tipo di località, seleziona Multi-regione e poi Stati Uniti.
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 --dataset.
Crea un set di dati denominato
bqml_tutorialcon la località dei dati impostata suUS.bq mk --dataset \ --location=US \ --description "BigQuery ML tutorial dataset." \ bqml_tutorial
Verifica che il set di dati sia stato creato:
bq ls
API
Chiama il metodo datasets.insert con una risorsa dataset definita.
{ "datasetReference": { "datasetId": "bqml_tutorial" } }
Crea una connessione
Crea una
connessione risorsa Cloud nella
multiregione US, in cui hai creato il set di dati. Poi recupera il account di servizio della connessione.
Console
Vai alla pagina BigQuery.
Nel riquadro a sinistra, fai clic su Explorer:

Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro a sinistra per aprirlo.
Nel riquadro Explorer, espandi il nome del progetto e fai clic su Connessioni.
Nella pagina Connessioni, fai clic su Crea connessione.
Per Tipo di connessione, scegli Modelli remoti di Vertex AI, funzioni remote, BigLake e Spanner (risorsa Cloud).
Nel campo ID connessione, inserisci un nome per la connessione.
Per Tipo di località, seleziona una località per la connessione. La connessione deve essere collocata insieme alle altre risorse, ad esempio i set di dati.
Fai clic su Crea connessione.
Fai clic su Vai alla connessione.
Nel riquadro Informazioni sulla connessione, copia l'ID dell'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_idsostituisce il progetto predefinito.Sostituisci quanto segue:
REGION: la tua regione di connessionePROJECT_ID: il tuo Google Cloud ID progettoCONNECTION_ID: un ID per la connessione
Quando crei una risorsa di connessione, BigQuery crea un account di serviziot 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...
Recupera e copia l'ID dell'account di servizio da utilizzare 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"}
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Terraform
Utilizza la risorsa
google_bigquery_connection.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
L'esempio seguente crea una connessione di risorsa Cloud denominata
my_cloud_resource_connection nella regione US:
Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi nelle sezioni seguenti.
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 eseguirlo 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 Terraform deve avere la propria directory (chiamata anche modulo radice).
-
In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione
.tf, ad esempiomain.tf. In questo tutorial, il file è denominatomain.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
main.tfappena creato.(Facoltativo) Copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.
- Rivedi 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
(Facoltativo) Per utilizzare l'ultima versione del provider Google, includi l'opzione
-upgrade:terraform init -upgrade
Applica le modifiche
-
Rivedi la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:
terraform plan
Apporta le correzioni necessarie alla configurazione.
-
Applica la configurazione Terraform eseguendo questo comando e inserendo
yesal prompt:terraform apply
Attendi che Terraform visualizzi il messaggio "Apply complete!".
- Apri il tuo Google Cloud progetto 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 al account di servizio della connessione
Concedi al 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. La concessione del ruolo in un progetto diverso genera 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.
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 seleziona Ruolo utente Vertex AI.
Fai clic su Salva.
Crea il modello remoto
Utilizza l'istruzione
CREATE MODEL
per creare un modello remoto che rappresenti un modello Vertex AI ospitato:
Nella console Google Cloud , vai alla pagina BigQuery.
Nell'editor di query, esegui la seguente istruzione:
CREATE OR REPLACE MODEL `bqml_tutorial.gemini_model` REMOTE WITH CONNECTION `LOCATION.CONNECTION_ID` OPTIONS (ENDPOINT = 'gemini-2.5-flash');
Sostituisci quanto segue:
LOCATION: la posizione della connessioneCONNECTION_ID: l'ID della tua connessione BigQueryQuando visualizzi i dettagli della connessione nella console Google Cloud , questo è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio
projects/myproject/locations/connection_location/connections/myconnection
Il completamento della query richiede diversi secondi, dopodiché il modello
gemini_model viene visualizzato nel set di dati bqml_tutorial. Non ci sono 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 AI.GENERATE_TEXT:
Nella console Google Cloud , vai alla pagina BigQuery.
Nell'editor di query, inserisci la seguente istruzione per eseguire l'estrazione delle parole chiave da cinque recensioni di film:
SELECT title, result, review FROM AI.GENERATE_TEXT( MODEL `bqml_tutorial.gemini_model`, ( SELECT CONCAT( """Extract a list of only 3 key words from this review. List only the key words, nothing else. Review: """, review) AS prompt, * FROM `bigquery-public-data.imdb.reviews` LIMIT 5 ), STRUCT( 0.2 AS temperature, 100 AS max_output_tokens));
L'output è simile al seguente:
+--------------+------------------+----------------------------------------+ | title | result | review | +--------------+------------------+----------------------------------------+ | The Guardian | * Costner | Once again Mr. Costner has dragged out | | | * Kutcher | a movie for far longer than necessary. | | | * Rescue | Aside from the terrific sea rescue... | | | | | | Trespass | * Generic | This is an example of why the majority | | | * Waste | of action films are the same. Generic | | | * Cinematography | and boring, there's really nothing... | | ... | ... | ... | +--------------+------------------+----------------------------------------+
Eseguire l'analisi del sentiment
Esegui l'analisi del sentiment sulle recensioni di film di IMDB utilizzando il modello remoto e la funzione AI.GENERATE_TEXT:
Nella console Google Cloud , vai alla pagina BigQuery.
Nell'editor di query, esegui la seguente istruzione per eseguire l'analisi del sentiment sulle recensioni di film:
SELECT title, result, review FROM AI.GENERATE_TEXT( MODEL `bqml_tutorial.gemini_model`, ( SELECT CONCAT( """Perform sentiment analysis on the following text and return one the following categories: positive, negative: """, review) AS prompt, * FROM `bigquery-public-data.imdb.reviews` LIMIT 5 ), STRUCT( 0.2 AS temperature, 100 AS max_output_tokens));
L'output è simile al seguente:
+----------+----------+------------------------------------------------+ | title | result | review | +----------+----------+------------------------------------------------+ | Quitting | Positive | This movie is amazing because the fact that... | | Trespass | Negative | This is an example of why the majority of ... | | ... | ... | ... | +----------+----------+------------------------------------------------+
Esegui la pulizia
Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.
Elimina il progetto
Elimina un progetto Google Cloud :
gcloud projects delete PROJECT_ID
Elimina singole risorse
Se vuoi riutilizzare il progetto, elimina le risorse che hai creato per il tutorial.
Console
Vai alla pagina BigQuery.
Elimina il set di dati
bqml_tutorial. Se elimini il set di dati, viene eliminato anche il modello remoto.Nel riquadro Explorer, espandi il progetto e fai clic su Set di dati.
Nell'elenco Set di dati, fai clic sul set di dati.
Nel riquadro dei dettagli, fai clic su Elimina.
Nella finestra di dialogo Elimina set di dati, fai clic su Elimina.
Elimina la connessione.
Nel riquadro Explorer, espandi il progetto e fai clic su Connessioni.
Nell'elenco Set di dati, fai clic sulla connessione.
Nel riquadro dei dettagli, fai clic su Elimina.
Nella finestra di dialogo Elimina collegamento, inserisci
deleteper confermare l'eliminazione.Fai clic su Elimina.
gcloud
Elimina il set di dati
bqml_tutoriale il modello remoto.bq rm --dataset --recursive bqml_tutorialElimina la connessione.
bq rm --connection PROJECT_ID.REGION.CONNECTION_IDSostituisci quanto segue:
- PROJECT_ID: il tuo Google Cloud ID progetto
- REGION: la regione della connessione
- CONNECTION_ID: l'ID connessione