Strukturierte Daten mit der Funktion AI.GENERATE_TABLE generieren

In diesem Dokument erfahren Sie, wie Sie mit einem Gemini-Modell strukturierte Daten generieren und die Antwort des Modells dann mit einem SQL-Schema formatieren.

Dazu führen Sie die folgenden Aufgaben aus:

• BigQuery ML-Remote-Modell über eines der allgemein verfügbaren oder in der Vorschau verfügbaren Gemini-Modelle erstellen
• Verwenden Sie das Modell mit der AI.GENERATE_TABLE-Funktion, um strukturierte Daten auf Grundlage von Daten aus Standardtabellen zu generieren.

Erforderliche Rollen

Zum Erstellen eines Remote-Modells und Verwenden der Funktion AI.GENERATE_TABLE benötigen Sie die folgenden IAM-Rollen (Identity and Access Management):

• BigQuery-Datasets, -Tabellen und -Modelle erstellen und verwenden: BigQuery-Dateneditor (roles/bigquery.dataEditor) für Ihr Projekt.

• BigQuery-Verbindungen erstellen, delegieren und verwenden: BigQuery-Verbindungsadministrator (roles/bigquery.connectionsAdmin) für Ihr Projekt.

  Wenn Sie keine Standardverbindung konfiguriert haben, können Sie eine erstellen und festlegen, wenn Sie die CREATE MODEL-Anweisung ausführen. Dazu benötigen Sie die Rolle „BigQuery Admin“ (roles/bigquery.admin) für Ihr Projekt. Weitere Informationen finden Sie unter Standardverbindung konfigurieren.

• Gewähren Sie dem Dienstkonto der Verbindung die Berechtigung „Projekt-IAM-Administrator“ (roles/resourcemanager.projectIamAdmin) für das Projekt, das den Vertex AI-Endpunkt enthält. Dies ist das aktuelle Projekt für Remote-Modelle, die Sie erstellen, indem Sie den Modellnamen als Endpunkt angeben. Dies ist das Projekt, das in der URL für Remote-Modelle angegeben ist, die Sie durch Angabe einer URL als Endpunkt erstellen.

• BigQuery-Jobs erstellen: Rolle „BigQuery Job User“ (roles/bigquery.jobUser) für Ihr Projekt.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Ausführen der Aufgaben in diesem Dokument erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Hinweise

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

Dataset erstellen

Erstellen Sie ein BigQuery-Dataset, das Ihre Ressourcen enthält:

Verbindung herstellen

Sie können diesen Schritt überspringen, wenn Sie entweder eine Standardverbindung konfiguriert haben oder die Rolle „BigQuery-Administrator“ haben.

Erstellen Sie eine Cloud-Ressourcenverbindung für das Remote-Modell und rufen Sie das Dienstkonto der Verbindung ab. Erstellen Sie die Verbindung am selben Speicherort wie das Dataset, das Sie im vorherigen Schritt erstellt haben.

Wählen Sie eine der folgenden Optionen aus:

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

Dem Dienstkonto Zugriff gewähren

Weisen Sie dem Dienstkonto der Verbindung die Rolle „Vertex AI-Nutzer“ zu.

Wenn Sie den Endpunkt beim Erstellen des Remote-Modells als URL angeben möchten, z. B. endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-2.5-flash', gewähren Sie diese Rolle in demselben Projekt, das Sie in der URL angeben.

Wenn Sie beim Erstellen des Remote-Modells den Endpunkt mit dem Modellnamen angeben möchten, z. B. endpoint = 'gemini-2.5-flash', gewähren Sie diese Rolle in demselben Projekt, in dem Sie das Remote-Modell erstellen möchten.

Die Zuweisung der Rolle in einem anderen Projekt führt zu dem Fehler bqcx-1234567890-wxyz@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

So weisen Sie die Rolle zu:

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

BigQuery ML-Remote-Modell erstellen

1. Rufen Sie in der Google Cloud Console die Seite BigQuery auf.

   BigQuery aufrufen

2. Erstellen Sie mit dem SQL-Editor ein Remote-Modell:

   CREATE OR REPLACE MODEL
   `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
   OPTIONS (ENDPOINT = 'ENDPOINT');

   Ersetzen Sie Folgendes:

   • PROJECT_ID: Ihre Projekt-ID.
   • DATASET_ID ist die ID des Datasets, das das Modell enthalten soll. Dieses Dataset muss sich am selben Standort wie die von Ihnen verwendete Verbindung befinden.
   • MODEL_NAME ist der Name des Modells.
   • REGION ist die Region, die von der Verbindung verwendet wird.
   • CONNECTION_ID: die ID Ihrer BigQuery-Verbindung.

     Wenn Sie sich Verbindungsdetails in der Google Cloud Console ansehen, ist dies der Wert im letzten Abschnitt der voll qualifizierten Verbindungs-ID, der unter Verbindungs-ID angezeigt wird, z. B. projects/myproject/locations/connection_location/connections/myconnection.

   • ENDPOINT: Der Name des zu verwendenden Gemini-Modells. Weitere Informationen finden Sie unter ENDPOINT.

Strukturierte Daten generieren

Generieren Sie strukturierte Daten mithilfe der Funktion AI.GENERATE_TABLE mit einem Remote-Modell und Prompt-Daten aus einer Tabellenspalte:

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

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Projekt-ID.
• DATASET_ID ist die ID des Datasets, das das Modell enthält.
• MODEL_NAME ist der Name des Modells.
• TABLE_NAME: der Name der Tabelle, die den Prompt enthält. Diese Tabelle muss eine Spalte namens prompt enthalten. Sie können auch einen Alias nutzen, um eine Spalte mit anderen Namen zu verwenden.
• PROMPT_QUERY: Die GoogleSQL-Abfrage, mit der die Prompt-Daten generiert werden. Der Aufforderungswert selbst kann aus einer Spalte abgerufen werden. Alternativ können Sie ihn als Strukturwert mit einer beliebigen Anzahl von Unterfeldern für String und Spaltennamen angeben. Beispiel: SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt
• TOKENS: ein INT64-Wert, der die maximale Anzahl an Tokens festlegt, die in der Antwort generiert werden können. Dieser Wert muss im Bereich [1,8192] liegen. Geben Sie kürzere Werte für kürzere Antworten und höhere Werte für längere Antworten an. Der Standardwert ist 128.
• TEMPERATURE: ein FLOAT64-Wert im Bereich [0.0,2.0], der den Grad der Zufälligkeit in der Tokenauswahl steuert. Der Standardwert ist 1.0.

  Niedrigere Werte für temperature eignen sich für Prompts, die deterministischere und weniger offene oder kreative Reaktionen erfordern, während höhere Werte für temperature zu vielfältigeren oder kreativen Ergebnissen führen können. Ein Wert von 0 für temperature ist deterministisch, d. h. die Antwort mit der höchsten Wahrscheinlichkeit wird immer ausgewählt.

• TOP_P: ein FLOAT64-Wert im Bereich [0.0,1.0], der die Wahrscheinlichkeit der ausgewählten Tokens bestimmt. Geben Sie einen niedrigeren Wert für weniger zufällige Antworten und einen höheren Wert für zufälligere Antworten an. Der Standardwert ist 0.95.
• STOP_SEQUENCES ist ein ARRAY<STRING>-Wert, der die angegebenen Strings entfernt, wenn sie in Antworten des Modells enthalten sind. Strings werden genau abgeglichen, einschließlich Groß-/Kleinschreibung. Der Standardwert ist ein leeres Array.
• SAFETY_SETTINGS: ein ARRAY<STRUCT<STRING AS category, STRING AS threshold>>-Wert, der Sicherheitsgrenzwerte für Inhalte konfiguriert, um Antworten zu filtern. Das erste Element in der Struktur gibt eine Schadenskategorie und das zweite Element in der Struktur einen entsprechenden Grenzwert für „Blockiert“ an. Das Modell filtert Inhalte heraus, die gegen diese Einstellungen verstoßen. Sie können jede Kategorie nur einmal angeben. Sie können beispielsweise nicht sowohl STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) als auch STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold) angeben. Wenn für eine bestimmte Kategorie keine Sicherheitseinstellung vorhanden ist, wird die Sicherheitseinstellung BLOCK_MEDIUM_AND_ABOVE verwendet.

  Die folgenden Kategorien werden unterstützt:

  • HARM_CATEGORY_HATE_SPEECH
  • HARM_CATEGORY_DANGEROUS_CONTENT
  • HARM_CATEGORY_HARASSMENT
  • HARM_CATEGORY_SEXUALLY_EXPLICIT

  Folgende Grenzwerte werden unterstützt:

  • BLOCK_NONE (Eingeschränkt)
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE (Standard)
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  Weitere Informationen finden Sie unter Schadenskategorien und Inhaltsfilter konfigurieren.

• OUTPUT_SCHEMA: ein STRING-Wert, der das Format für die Antwort des Modells angibt. Der Wert output_schema muss eine SQL-Schemadefinition sein, ähnlich der, die in der CREATE TABLE-Anweisung verwendet wird. Folgende Datentypen werden unterstützt:
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  Geben Sie für Gemini 1.5-Modelle nur dann einen FLOAT64-Datentyp an, wenn Sie sicher sind, dass der Rückgabewert keine gerundete Zahl ist. Diese Modelle können manchmal INT64-Werte anstelle von FLOAT64-Werten für gerundete Zahlen zurückgeben, z. B. 2 anstelle von 2.0. Dies kann zu einem Parsing-Fehler in der Abfrage führen.

  Wenn Sie das Argument output_schema verwenden, um strukturierte Daten auf Grundlage von Prompts aus einer Tabelle zu generieren, ist es wichtig, die Prompt-Daten zu verstehen, um ein geeignetes Schema anzugeben.

  Angenommen, Sie analysieren Filmbesprechungen aus einer Tabelle mit den folgenden Feldern:

  • movie_id
  • Rezension
  • prompt

  Anschließend können Sie Prompt-Text erstellen, indem Sie eine Abfrage ähnlich der folgenden ausführen:

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

  Möglicherweise geben Sie einen output_schema-Wert an, der "keywords ARRAY<STRING>, sentiment STRING" AS output_schema ähnelt.

Beispiele

Im folgenden Beispiel sehen Sie eine Anfrage, die Prompt-Daten aus einer Tabelle abruft und ein SQL-Schema zum Formatieren der Antwort des Modells bereitstellt:

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

Im folgenden Beispiel sehen Sie eine Anfrage, die Prompt-Daten aus einer Abfrage verwendet und ein SQL-Schema zum Formatieren der Antwort des Modells bereitstellt:

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