Generare dati strutturati utilizzando la funzione AI.GENERATE_TABLE

Questo documento mostra come generare dati strutturati utilizzando un modello Gemini e poi formattare la risposta del modello utilizzando uno schema SQL.

Per farlo, completa le seguenti attività:

• Creazione di un modello remoto BigQuery ML su uno qualsiasi dei modelli Gemini disponibili a livello generale o in anteprima.
• Utilizzando il modello con la funzione AI.GENERATE_TABLE per generare dati strutturati in base ai dati delle tabelle standard.

Ruoli obbligatori

Per creare un modello remoto e utilizzare la funzione AI.GENERATE_TABLE, devi disporre dei seguenti ruoli IAM (Identity and Access Management):

• Crea e utilizza set di dati, tabelle e modelli BigQuery: Editor dati BigQuery (roles/bigquery.dataEditor) nel tuo progetto.

• Crea, delega e utilizza le connessioni BigQuery: Amministratore connessioni BigQuery (roles/bigquery.connectionsAdmin) nel tuo progetto.

  Se non hai configurato una connessione predefinita, puoi crearne e impostarne una durante l'esecuzione dell'istruzione CREATE MODEL. Per farlo, devi disporre del ruolo Amministratore BigQuery (roles/bigquery.admin) nel tuo progetto. Per ulteriori informazioni, vedi Configurare la connessione predefinita.

• Concedi le autorizzazioni al account di servizio della connessione: Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) nel progetto che contiene l'endpoint Vertex AI. Questo è il progetto attuale per i modelli remoti che crei specificando il nome del modello come endpoint. Questo è il progetto identificato nell'URL per i modelli remoti che crei specificando un URL come endpoint.

• Crea job BigQuery: Utente job BigQuery (roles/bigquery.jobUser) nel tuo progetto.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire le attività descritte in questo documento. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

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 che contenga le tue risorse:

Crea una connessione

Puoi saltare questo passaggio se hai configurato una connessione predefinita o se disponi del ruolo Amministratore BigQuery.

Crea una connessione a una risorsa Cloud da utilizzare per il modello remoto e recupera il account di servizio della connessione. Crea la connessione nella stessa posizione del set di dati che hai creato nel passaggio precedente.

Seleziona una delle seguenti opzioni:

# 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 {}
}

Concedi l'accesso al account di servizio

Concedi al 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/gemini-2.5-flash', 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 = 'gemini-2.5-flash', concedi questo ruolo nello stesso progetto in cui prevedi di creare il modello remoto.

La concessione del ruolo in un progetto diverso genera l'errore bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Per concedere il ruolo, segui questi passaggi:

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

Crea un modello remoto BigQuery ML

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 {DEFAULT | `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 deve contenere il modello. Questo set di dati deve trovarsi nella stessa posizione della connessione che stai utilizzando
   • 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 , questo è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio projects/myproject/locations/connection_location/connections/myconnection

   • ENDPOINT: il nome del modello Gemini da utilizzare. Per ulteriori informazioni, vedi ENDPOINT.

Generare dati strutturati

Genera dati strutturati utilizzando la funzione AI.GENERATE_TABLE con un modello remoto e utilizzando i dati del prompt da una colonna della tabella:

SELECT *
FROM AI.GENERATE_TABLE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  [TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` / (PROMPT_QUERY)],
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p, STOP_SEQUENCES AS stop_sequences,
  SAFETY_SETTINGS AS safety_settings,
  OUTPUT_SCHEMA AS output_schema)
);

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.
• TABLE_NAME: il nome della tabella che contiene il prompt. Questa tabella deve avere una colonna denominata prompt oppure puoi utilizzare un alias per utilizzare una colonna con un nome diverso.
• PROMPT_QUERY: la query GoogleSQL che genera i dati del prompt. Il valore del prompt può essere estratto da una colonna oppure puoi specificarlo come valore struct con un numero arbitrario di sottocampi stringa e nome colonna. Ad esempio, SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt.
• TOKENS: un valore INT64 che imposta il numero massimo di token che possono essere generati nella risposta. Questo valore deve essere compreso nell'intervallo [1,8192]. Specifica un valore più basso per risposte più brevi e un valore più alto per risposte più lunghe. Il valore predefinito è 128.
• TEMPERATURE: un valore FLOAT64 nell'intervallo [0.0,2.0] che controlla il grado di casualità nella selezione dei token. Il valore predefinito è 1.0.

  I valori più bassi per temperature sono ideali per prompt che richiedono risposte più deterministici e meno aperti o creativi, mentre i valori più alti per temperature possono portare a risultati più diversificati o creativi. Un valore di 0 per temperature è deterministico, il che significa che viene sempre selezionata la risposta con la probabilità più alta.

• TOP_P: un valore FLOAT64 nell'intervallo [0.0,1.0] contribuisce a determinare la probabilità dei token selezionati. Specifica un valore più basso per risposte meno casuali e un valore più alto per risposte più casuali. Il valore predefinito è 0.95.
• STOP_SEQUENCES: un valore ARRAY<STRING> che rimuove le stringhe specificate se sono incluse nelle risposte del modello. Le stringhe vengono confrontate esattamente, comprese le maiuscole. Il valore predefinito è un array vuoto.
• SAFETY_SETTINGS: un valore ARRAY<STRUCT<STRING AS category, STRING AS threshold>> che configura le soglie di sicurezza dei contenuti per filtrare le risposte. Il primo elemento dello struct specifica una categoria di contenuti dannosi, mentre il secondo elemento dello struct specifica una soglia di blocco corrispondente. Il modello filtra i contenuti che violano queste impostazioni. Puoi specificare ogni categoria una sola volta. Ad esempio, non puoi specificare sia STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) che STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold). Se non è presente un'impostazione di sicurezza per una determinata categoria, viene utilizzata l'impostazione di sicurezza BLOCK_MEDIUM_AND_ABOVE.

  Le categorie supportate sono le seguenti:

  • HARM_CATEGORY_HATE_SPEECH
  • HARM_CATEGORY_DANGEROUS_CONTENT
  • HARM_CATEGORY_HARASSMENT
  • HARM_CATEGORY_SEXUALLY_EXPLICIT

  Le soglie supportate sono le seguenti:

  • BLOCK_NONE (con accesso limitato)
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE (valore predefinito)
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  Per ulteriori informazioni, consulta Categorie di danni e Come configurare i filtri per i contenuti.

• OUTPUT_SCHEMA: un valore STRING che specifica il formato della risposta del modello. Il valore output_schema deve essere una definizione dello schema SQL, simile a quella utilizzata nell'istruzione CREATE TABLE. Sono supportati i seguenti tipi di dati:
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  Per i modelli Gemini 1.5, specifica un tipo di dati FLOAT64 solo se hai la certezza che il valore restituito non sarà un numero intero. A volte questi modelli possono restituire valori INT64 anziché FLOAT64 per i numeri interi, ad esempio 2 anziché 2.0, e ciò può causare un errore di analisi nella query.

  Quando utilizzi l'argomento output_schema per generare dati strutturati in base ai prompt di una tabella, è importante comprendere i dati dei prompt per specificare uno schema appropriato.

  Ad esempio, supponiamo di analizzare i contenuti delle recensioni di film da una tabella che contiene i seguenti campi:

  • movie_id
  • review
  • prompt

  Poi puoi creare il testo del prompt eseguendo una query simile alla seguente:

  UPDATE mydataset.movie_review
  SET prompt = CONCAT('Extract the key words and key sentiment from the text below: ', review)
  WHERE review IS NOT NULL;

  Potresti specificare un valore output_schema simile a "keywords ARRAY<STRING>, sentiment STRING" AS output_schema.

Esempi

L'esempio seguente mostra una richiesta che prende i dati del prompt da una tabella e fornisce uno schema SQL per formattare la risposta del modello:

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY<STRING>, sentiment STRING" AS output_schema));

L'esempio seguente mostra una richiesta che prende i dati del prompt da una query e fornisce uno schema SQL per formattare la risposta del modello:

SELECT *
FROM
  AI.GENERATE_TABLE(
    MODEL `mydataset.gemini_model`,
    (
      SELECT
        'John Smith is a 20-year old single man living at 1234 NW 45th St, Kirkland WA, 98033. He has two phone numbers 123-123-1234, and 234-234-2345. He is 200.5 pounds.'
          AS prompt
    ),
    STRUCT("address STRUCT<street_address STRING, city STRING, state STRING, zip_code STRING>, age INT64, is_married BOOL, name STRING, phone_number ARRAY<STRING>, weight_in_pounds FLOAT64"
        AS output_schema, 8192 AS max_output_tokens));