Generare dati strutturati utilizzando la funzione AI.GENERATE_TABLE

Questo documento mostra come generare dati strutturati utilizzando un modello Gemini Pro 1.5, Gemini Flash 1.5 o Gemini Flash 2.0 e poi formattare la risposta del modello utilizzando uno schema SQL.

Per farlo, completa le seguenti attività:

• Creazione di un modello remoto BigQuery ML che rappresenti un modello Gemini 1.5 o 2.0 di Vertex AI ospitato.
• Utilizzo del modello con la funzione AI.GENERATE_TABLE per generare dati strutturati in base ai dati delle tabelle standard.

Autorizzazioni obbligatorie

• 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 una connessione

Crea una connessione risorsa Cloud e recupera l'account di servizio della connessione.

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 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/gemini-1.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-1.5-flash', 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:

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

Creare 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 `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 località della connessione che stai utilizzando
   • MODEL_NAME: il nome del modello
   • REGION: la regione utilizzata dalla 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: il nome del modello Gemini da utilizzare. Sono supportati i seguenti modelli:
     • gemini-2.0-flash-001
     • gemini-1.5-flash-001
     • gemini-1.5-flash-002
     • gemini-1.5-pro-001
     • gemini-1.5-pro-002
     Per ulteriori informazioni, consulta ENDPOINT.

Generare dati strutturati

Genera dati strutturati utilizzando la funzione AI.GENERATE_TABLE con un modello remoto e i dati del prompt di 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 stesso può essere estratto da una colonna o puoi specificarlo come valore di struct con un numero arbitrario di campi secondari di stringhe e nomi di colonne. 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ù deterministiche e meno aperte o creative, 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] consente di 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 associate esattamente, incluse le lettere 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 della struttura specifica una categoria di danno, mentre il secondo elemento 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 (Accesso limitato)
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE (valore predefinito)
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  Per saperne di più, consulta le categorie di danno e Come configurare i filtri dei 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 arrotondato. A volte questi modelli possono restituire valori INT64 anziché FLOAT64 per i numeri arrotondati, ad esempio 2 anziché 2.0, e questo 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 che tu stia analizzando i contenuti delle recensioni di film da una tabella che contiene i seguenti campi:

  • movie_id
  • review
  • prompt

  A questo punto, 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;

  e puoi 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));