Autonome Einbettungsgenerierung

In diesem Dokument wird beschrieben, wie Sie die autonome Einbettungsgenerierung für Ihre Daten verwenden, damit BigQuery eine Spalte mit Einbettungen in einer Tabelle basierend auf einer Quellspalte verwalten kann. Die Quellspalte muss den Datentyp STRING oder ObjectRef haben. Wenn Sie Daten in der Quellspalte hinzufügen oder ändern, generiert oder aktualisiert BigQuery die Einbettungsspalte für diese Daten automatisch mithilfe eines Einbettungsmodells der Agent Platform. Das ist hilfreich, wenn Sie möchten, dass BigQuery Ihre Einbettungen verwaltet, wenn Ihre Quelldaten regelmäßig aktualisiert werden.

Einbettungen sind nützlich für moderne generative KI-Anwendungen wie Retrieval-Augmented Generation (RAG). Sie können jedoch komplex zu erstellen, zu verwalten und abzufragen sein. Mit der autonomen Einbettungsgenerierung können Sie das Erstellen, Verwalten und Abfragen von Einbettungen für Ähnlichkeitssuchen und andere generative KI-Anwendungen vereinfachen.

Sie können beispielsweise Abfragen wie die folgenden verwenden, um eine Tabelle mit aktivierter autonomer Einbettungsgenerierung zu erstellen, Daten einzufügen und dann eine semantische Suche durchzuführen:

CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE ));

# Values in the description_embedding column are automatically generated.
INSERT INTO mydataset.products (name, description) VALUES
  ('Super slingers', 'An exciting board game for the whole family'), ...;

SELECT * FROM AI.SEARCH(TABLE mydataset.products, 'description', 'A really fun toy');

Hinweis

Wenn Sie die autonome Einbettungsgenerierung für eine Tabelle aktivieren möchten, benötigen Sie die erforderlichen Berechtigungen und die Verbindung. Außerdem müssen Sie die Vertex AI API für Ihr Projekt aktivieren.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aktivieren der autonomen Einbettungsgenerierung benötigen:

  • So verwenden Sie eine Verbindungsressource: BigQuery-Verbindungsnutzer (roles/bigquery.connectionUser) für die Verbindung
  • Zum Erstellen oder Ändern einer Tabelle: BigQuery-Dateneditor (roles/bigquery.dataEditor) für die Tabelle
  • Weisen Sie dem Dienstkonto der Verbindung die folgende Rolle zu, damit es auf Modelle zugreifen kann, die auf Agent Platform-Endpunkten gehostet werden: Agent Platform User (roles/aiplatform.user) für das Projekt, das die Verbindung enthält

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Verbindung erstellen und einem Dienstkonto Berechtigungen gewähren

Wenn Sie die autonome Einbettungserstellung für eine Tabelle aktivieren möchten, müssen Sie eine Cloud-Ressourcenverbindung erstellen. Weisen Sie dann dem Dienstkonto, das beim Erstellen der Verbindung erstellt wurde, die Rolle Agent Platform User (roles/aiplatform.user) zu.

Automatisch generierte Einbettungsspalte erstellen

Sie können entweder eine automatisch generierte Einbettungsspalte in einer neuen Tabelle erstellen oder eine zu einer vorhandenen Tabelle hinzufügen.

Wenn Sie die Funktion AI.EMBED für eine automatisch generierte Einbettungsspalte definieren und das Argument task_type nicht angeben, Ihr Modell aber task_type unterstützt, setzt BigQuery task_type standardmäßig auf RETRIEVAL_DOCUMENT. Wenn Sie die Tabelle mit der AI.SEARCH-Funktion oder der VECTOR_SEARCH-Funktion abfragen, generiert BigQuery die Abfrageeinbettung spontan mit dem folgenden task_type-Verhalten:

  • Wenn die Einbettungsspalte der Tabelle RETRIEVAL_DOCUMENT verwendet, entweder standardmäßig oder explizit angegeben, verwendet BigQuery RETRIEVAL_QUERY, um die Suchanfrage einzubetten.
  • Andernfalls verwendet BigQuery dieselbe task_type, die für die Einbettungsspalte der Tabelle konfiguriert ist.

Tabelle mit einer automatisch generierten Einbettungsspalte erstellen

Sie können die autonome Einbettungsgenerierung verwenden, um Einbettungen mit der Funktion AI.EMBED in einer CREATE TABLE-Anweisung zu generieren.

SQL

Verwenden Sie eine CREATE TABLE-Anweisung, um eine Tabelle mit einer automatisch generierten Einbettungsspalte zu erstellen. So erstellen Sie die Tabelle:

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

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    CREATE TABLE DATASET_ID.TABLE (
  [COLUMN, ...]
  SOURCE_COL { STRING | ObjectRef },
  EMBEDDING_COL_NAME STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(
        SOURCE_COL,
        {
          connection_id => CONNECTION_ID,
          endpoint => ENDPOINT |
          model => MODEL
        })
    )
    STORED OPTIONS (asynchronous = TRUE)
);

    Ersetzen Sie Folgendes:

    • DATASET_ID: der Name des Datasets, in dem Sie die Tabelle erstellen möchten.
    • TABLE: der Name der Tabelle, für die die autonome Einbettungsgenerierung erstellt werden soll.
    • COLUMN, ...: alle Spalten, die Ihre Tabelle neben der Spalte enthalten soll, die Sie automatisch einbetten möchten.
    • SOURCE_COL: der Name der STRING- oder ObjectRef-Spalte, die Sie automatisch einbetten möchten.
    • EMBEDDING_COL_NAME: Der Name der automatisch generierten Einbettungsspalte.
    • CONNECTION_ID: ein STRING-Wert, der den Namen einer zu verwendenden Verbindung enthält, z. B. my_project.us.example_connection. Sie müssen dem Dienstkonto der Verbindung in dem Projekt, in dem Sie die Tabelle erstellen, die Rolle Agent Platform User zuweisen.
    • ENDPOINT: ein STRING-Wert, der einen unterstützten Endpunkt für das Texteinbettungsmodell der Agent Platform angibt, der für das Texteinbettungsmodell verwendet werden soll. Der von Ihnen angegebene Endpunktwert muss die Modellversion enthalten, z. B. text-embedding-005. Wenn Sie den Modellnamen anstelle einer URL angeben, identifiziert BigQuery ML das Modell automatisch und verwendet den vollständigen Endpunkt des Modells.
    • MODEL (Vorabversion): ein STRING-Wert, der ein integriertes Texteinbettungsmodell angibt. Der einzige unterstützte Wert ist das embeddinggemma-300m-Modell. Wenn Sie diesen Parameter angeben, können Sie die Parameter endpoint oder connection_id nicht angeben. Wenn Sie den Parameter MODEL angeben, bleiben Ihre Daten in BigQuery und Ihre Slots werden zum Erstellen der Einbettungen verwendet. Es werden keine Daten an die Agent Platform gesendet und es fallen keine Gebühren in der Agent Platform an.

  3. Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

Wenn Sie eine Tabelle mit einer automatisch generierten Einbettungsspalte mit dem bq-Befehlszeilentool erstellen möchten, verwenden Sie den Befehl bq mk mit einer JSON-Schemadatei, die das Tabellenschema definiert:

  1. Erstellen Sie eine JSON-Schemadatei. Das folgende Beispiel zeigt ein Schema, das eine Einbettungsspalte basierend auf einer Quellspalte erstellt. In diesem Beispiel wird ein Agent Platform-Endpunkt für die Einbettungsgenerierung verwendet.

    [
  {
    "name": "SOURCE_COL",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "result",
        "type": "FLOAT"
      },
      {
        "name": "status",
        "type": "STRING"
      }
    ],
    "generatedColumn": {
      "generationExpressionInfo": {
        "asynchronous": true,
        "generationExpression": "AI.EMBED(SOURCE_COL, connection_id => 'CONNECTION_ID', endpoint => 'ENDPOINT')",
        "stored": true
      },
      "generatedMode": "GENERATED_ALWAYS"
    },
    "name": "EMBEDDING_COL_NAME",
    "type": "RECORD"
  }
]

    Wenn Sie ein integriertes Modell anstelle eines Agent Platform-Endpunkts verwenden, verwenden Sie für generationExpression eine Syntax wie die folgende: "AI.EMBED(SOURCE_COL, model => 'MODEL')"

    Informationen zu den zu verwendenden Werten finden Sie in den Beschreibungen für SOURCE_COL, EMBEDDING_COL_NAME, CONNECTION_ID, ENDPOINT und MODEL auf dem Tab SQL.

  2. Speichern Sie das Schema in einer Datei, z. B. schema.json.

  3. Erstellen Sie die Tabelle mit dem Befehl bq mk --table:

    bq mk --table DATASET_ID.TABLE schema.json

Ersetzen Sie Folgendes:

  • DATASET_ID: Der Name des Datasets, in dem Sie die Tabelle erstellen möchten.
  • TABLE: Der Name der Tabelle, für die die autonome Einbettungsgenerierung erstellt werden soll.
  • COLUMN, ...: Alle Spalten, die Ihre Tabelle neben der Spalte enthalten soll, die Sie automatisch einbetten möchten.
  • STRING_COL: Der Name der STRING-Spalte, die Sie automatisch einbetten möchten.
  • EMBEDDING_COL_NAME: Der Name der automatisch generierten Einbettungsspalte.
  • CONNECTION_ID: Ein STRING-Wert, der den Namen einer zu verwendenden Verbindung enthält, z. B. my_project.us.example_connection. Sie müssen dem Dienstkonto der Verbindung in dem Projekt, in dem Sie die Tabelle erstellen, die Rolle Agent Platform User zuweisen.
  • ENDPOINT: Ein STRING-Wert, der einen unterstützten Texteinbettungsmodell-Endpunkt der Agent-Plattform angibt, der für das Texteinbettungsmodell verwendet werden soll. Der von Ihnen angegebene Endpunktwert muss die Modellversion enthalten, z. B. text-embedding-005. Wenn Sie den Modellnamen anstelle einer URL angeben, identifiziert BigQuery ML das Modell automatisch und verwendet den vollständigen Endpunkt des Modells.

  • MODEL (Vorabversion): ein STRING-Wert, der ein integriertes Texteinbettungsmodell angibt. Der einzige unterstützte Wert ist das embeddinggemma-300m-Modell. Wenn Sie diesen Parameter angeben, können Sie die Parameter endpoint oder connection_id nicht angeben.

    Wenn Sie den Parameter MODEL angeben, bleiben Ihre Daten in BigQuery und Ihre Slots werden zum Erstellen der Einbettungen verwendet. Es werden keine Daten an die Agent Platform gesendet und es fallen keine Gebühren in der Agent Platform an.

Einer vorhandenen Tabelle eine automatisch generierte Einbettungsspalte hinzufügen

Sie können einer vorhandenen Tabelle auch eine automatisch generierte Einbettungsspalte hinzufügen, indem Sie eine ALTER TABLE ADD COLUMN-Anweisung verwenden.

SQL

Verwenden Sie eine ALTER TABLE ADD COLUMN-Anweisung, um einer vorhandenen Tabelle eine automatisch generierte Einbettungsspalte hinzuzufügen. So fügen Sie die Spalte hinzu:

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

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    ALTER TABLE DATASET_ID.TABLE
  ADD COLUMN EMBEDDING_COL_NAME
    STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(
        SOURCE_COL,
        {
          connection_id => CONNECTION_ID,
          endpoint => ENDPOINT |
          model => MODEL
        })
    )
    STORED OPTIONS (asynchronous = TRUE)
;

    Ersetzen Sie Folgendes:

    • DATASET_ID: der Name des Datasets, das die Tabelle enthält.
    • TABLE: Der Name der Tabelle, der Sie die automatisch generierte Einbettungsspalte hinzufügen möchten.
    • EMBEDDING_COL_NAME: Der Name der automatisch generierten Einbettungsspalte.
    • SOURCE_COL: der Name der STRING- oder ObjectRef-Spalte, die Sie automatisch einbetten möchten.
    • CONNECTION_ID: ein STRING-Wert, der den Namen einer zu verwendenden Verbindung enthält, z. B. my_project.us.example_connection.
    • ENDPOINT: Ein STRING-Wert, der einen unterstützten Endpunkt für ein Texteinbettungsmodell der Agent Platform angibt, der für das Texteinbettungsmodell verwendet werden soll.
    • MODEL (Vorabversion): ein STRING-Wert, der ein integriertes Texteinbettungsmodell angibt. Der einzige unterstützte Wert ist das embeddinggemma-300m-Modell. Wenn Sie diesen Parameter angeben, können Sie die Parameter endpoint oder connection_id nicht angeben. Wenn Sie den Parameter MODEL angeben, bleiben Ihre Daten in BigQuery und Ihre Slots werden zum Erstellen der Einbettungen verwendet. Es werden keine Daten an die Agent Platform gesendet und es fallen keine Gebühren in der Agent Platform an.

  3. Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

Wenn Sie einer vorhandenen Tabelle mit dem bq-Befehlszeilentool eine automatisch generierte Einbettungsspalte hinzufügen möchten, verwenden Sie den Befehl bq update mit einer JSON-Schemadatei, die das aktualisierte Tabellenschema definiert:

  1. Rufen Sie das aktuelle Schema der Tabelle ab und speichern Sie es in einer Datei, z. B. schema.json: 
    bq show --schema --format=prettyjson DATASET_ID.TABLE > schema.json

  2. Bearbeiten Sie schema.json, um die Definition für die neue automatisch generierte Einbettungsspalte hinzuzufügen. Das folgende Beispiel zeigt die Definition für eine Einbettungsspalte, die auf einer Quellspalte basiert. In diesem Beispiel wird ein Agent Platform-Endpunkt für die Einbettungsgenerierung verwendet.

    [
  {
    "name": "SOURCE_COL",
    "type": "STRING"
  },
  {
    "fields": [
      {
        "mode": "REPEATED",
        "name": "result",
        "type": "FLOAT"
      },
      {
        "name": "status",
        "type": "STRING"
      }
    ],
    "generatedColumn": {
      "generationExpressionInfo": {
        "asynchronous": true,
        "generationExpression": "AI.EMBED(SOURCE_COL, connection_id => 'CONNECTION_ID', endpoint => 'ENDPOINT')",
        "stored": true
      },
      "generatedMode": "GENERATED_ALWAYS"
    },
    "name": "EMBEDDING_COL_NAME",
    "type": "RECORD"
  }
]

    Wenn Sie ein integriertes Modell anstelle eines Agent Platform-Endpunkts verwenden, verwenden Sie für generationExpression eine Syntax wie die folgende: "AI.EMBED(SOURCE_COL, model => 'MODEL')"

    Informationen zu den zu verwendenden Werten finden Sie in den Beschreibungen für SOURCE_COL, EMBEDDING_COL_NAME, CONNECTION_ID, ENDPOINT und MODEL auf dem Tab SQL.

  3. Aktualisieren Sie die Tabelle mit dem Befehl bq update --table:

    bq update --table DATASET_ID.TABLE schema.json

    Ersetzen Sie Folgendes:

    • DATASET_ID: der Name des Datasets, das die Tabelle enthält.
    • TABLE: Der Name der Tabelle, der Sie die automatisch generierte Einbettungsspalte hinzufügen möchten.

Der Hintergrundjob zur Einbettungsgenerierung wird kurz nach dem Erstellen oder Ändern der Tabelle oder nach dem Aktualisieren von Daten in der Quellspalte gestartet.

Mit einer Abfrage wie der folgenden können Sie den Fortschritt der Einbettungserstellung verfolgen:

SELECT
  COUNT(*) AS total_num_rows,
  COUNTIF(description_embedding IS NOT NULL
          AND description_embedding.status = '') AS total_num_generated_embeddings
FROM
  PROJECT_ID.DATASET_ID.TABLE;

Nachdem Sie die Tabelle mit Einbettungen erstellt haben, können Sie einen Vektorindex für die Spalte STRUCT erstellen, die die automatisch generierte Einbettung enthält.

Beispiel

Angenommen, Sie sind ein großer Einzelhändler, der viele verschiedene Produkte verkauft. Sie haben eine Tabelle mit Produktnamen und -beschreibungen und möchten Ihren Kunden helfen, die gesuchten Produkte zu finden. Die folgenden Abfragen zeigen, wie Sie die autonome Einbettungsgenerierung einrichten, um die semantische Suche in Ihren Produktbeschreibungen zu unterstützen.

Erstellen Sie zuerst ein Dataset:

CREATE SCHEMA mydataset;

Erstellen Sie als Nächstes eine Tabelle mit aktivierter autonomer Einbettungsgenerierung, um Ihre Produktinformationen zu speichern. Die automatisch generierte Spalte heißt description_embedding und basiert auf der Spalte description.

# Create a table of products and descriptions with a generated embedding column.
CREATE TABLE mydataset.products (
  name STRING,
  description STRING,
  description_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(description, connection_id => 'us.example_connection',
        endpoint => 'text-embedding-005')
      # Alternatively, you can use the syntax for a built-in model.
      # AI.EMBED(description, model => 'embeddinggemma-300m')
    ) STORED OPTIONS( asynchronous = TRUE )
);

Mit der folgenden Abfrage werden einige Produktnamen und Beschreibungen in die Tabelle eingefügt. Sie geben keinen Wert für description_embedding an, da dieser automatisch generiert wird.

# Insert product descriptions into the table.
# The description_embedding column is automatically updated.
INSERT INTO mydataset.products (name, description) VALUES
  ("Lounger chair", "A comfortable chair for relaxing in."),
  ("Super slingers", "An exciting board game for the whole family."),
  ("Encyclopedia set", "A collection of informational books.");

Optional können Sie einen Vektorindex für die Tabelle erstellen, um die Suche zu beschleunigen. Für einen Vektorindex sind mehr als drei Zeilen erforderlich. Daher wird in der folgenden Abfrage davon ausgegangen, dass Sie zusätzliche Daten eingefügt haben. Jedes Mal, wenn Sie Daten einfügen, wird die Spalte description_embedding automatisch aktualisiert.

CREATE VECTOR INDEX my_index
ON mydataset.products(description_embedding)
OPTIONS(index_type = 'IVF');

Schließlich können Sie die Funktion AI.SEARCH verwenden, um eine semantische Suche nach einem lustigen Spielzeug in Ihren Produkten durchzuführen:

# Search for products that are fun to play with.
SELECT base.name, base.description, distance
FROM AI.SEARCH(TABLE mydataset.products, 'description', "A really fun toy");

/*------------------+----------------------------------------------+----------------------+
 | name             | description                                  | distance             |
 +------------------+----------------------------------------------+----------------------+
 | Super slingers   | An exciting board game for the whole family. | 0.80954913893618929  |
 | Lounger chair    | A comfortable chair for relaxing in.         | 0.938933930620146    |
 | Encyclopedia set | A collection of informational books.         | 1.1119297739353384   |
 +------------------+----------------------------------------------+----------------------*/

Einbettungen aus ObjectRef Spalten generiert

Sie können generierte Einbettungsspalten für eine ObjectRef-Spalte in einer Tabelle hinzufügen.

Im folgenden Beispiel wird gezeigt, wie Sie eine Tabelle mit einer ObjectRef-Spalte erstellen und dann eine generierte Einbettungsspalte für diese Spalte hinzufügen:

# Create a table with ObjectRef columns.
CREATE TABLE mydataset.images AS
SELECT
  REGEXP_EXTRACT(ref.uri, r'.*/(.*).jpg$') AS name,
  ref
FROM mydataset.object_table;

# Add a generated embedding column for the ObjectRef column.
ALTER TABLE mydataset.images
ADD COLUMN image_embedding STRUCT<result ARRAY<FLOAT64>, status STRING>
GENERATED ALWAYS AS (
  AI.EMBED(
    ref,
    connection_id => "us.my_connection",
    endpoint => "multimodalembedding@001")
)
STORED OPTIONS (asynchronous = true);

Informationen zu automatisch generierten Einbettungsspalten abrufen

Wenn Sie prüfen möchten, ob eine Spalte eine automatisch generierte Einbettungsspalte ist, fragen Sie die Ansicht INFORMATION_SCHEMA.COLUMNS ab.

Die folgende Abfrage zeigt Informationen zu allen automatisch generierten Einbettungsspalten:

SELECT *
FROM PROJECT_ID.DATASET_ID.INFORMATION_SCHEMA.COLUMNS
WHERE is_generated = 'ALWAYS';

Im Feld generation_expression wird der Aufruf der Funktion AI.EMBED angezeigt, mit der die Einbettungen für die Spalte generiert werden. Dazu gehört auch das Standardargument task_type => 'RETRIEVAL_DOCUMENT', wenn Sie für ein Modell, das dies unterstützt, keine task_type angegeben haben.

Eigene Reservierung verwenden

Standardmäßig verwendet BigQuery On-Demand-Slots, um die Verarbeitung zu übernehmen, die für die Verwaltung der generierten Einbettungsspalte erforderlich ist. Um eine vorhersehbare und konsistente Leistung zu gewährleisten, können Sie optional eine Reservierung erstellen und job_type auf BACKGROUND setzen. Wenn eine Hintergrundreservierung vorhanden ist, verwendet BigQuery diese stattdessen, um die generierte Einbettungsspalte zu verwalten.

Kontingente

Wenn Sie einen Agent Platform-Endpunkt für die Einbettungsgenerierung verwenden, indem Sie den Parameter endpoint in der Funktion AI.EMBED angeben, sendet BigQuery Anfragen an die Agent Platform, um Einbettungen zu generieren. Diese Anfragen unterliegen den Kontingenten für die Agent Platform. Das Kontingent für Anfragen pro Minute für Ihr Einbettungsmodell wirkt sich direkt auf den Durchsatz von Jobs zur Einbettungsgenerierung im Hintergrund aus. Wenn die Einbettungserstellung langsam ist, fordern Sie ein höheres Kontingentlimit für die Agent Platform an. Folgen Sie dazu der Anleitung unter Höheres Kontingent anfordern. Wenn Sie den Parameter model in der Funktion AI.EMBED angeben, werden Einbettungen in BigQuery generiert und es werden keine Anfragen an die Agent Platform gesendet. Daher gelten die Kontingente der Agent Platform nicht.

Fehlerbehebung

Die generierte Einbettungsspalte enthält zwei Felder: result und status. Wenn ein Fehler auftritt, während BigQuery versucht, eine Einbettung für eine bestimmte Zeile in Ihrer Tabelle zu generieren, ist das Feld result NULL und das Feld status beschreibt den Fehler. Wenn die Quellspalte beispielsweise NULL ist, ist die Einbettung result ebenfalls NULL und der Status ist NULL value is not supported for embedding generation.

Ein schwerwiegenderer Fehler kann die Einbettungserstellung blockieren. In diesem Fall können Sie die Spalte async_generation_status in der Ansicht INFORMATION_SCHEMA.COLUMNS abfragen, um den blockierenden Fehler zu identifizieren.

Blockierungsfehler können folgende Ursachen haben:

  • Fehler „Berechtigung verweigert“
  • Fehler „Nicht gefunden“
  • Fehler bei nicht unterstützten Einbettungsmodell-Endpunkten
  • Fehler „Vertex AI API nicht aktiviert“

Sobald der nächste Job zur Einbettungsgenerierung erfolgreich abgeschlossen wurde, wird die Spalte async_generation_status gelöscht.

Die folgende Abfrage zeigt, wie Sie nach Blockierungsfehlern suchen:

SELECT
  column_name,
  async_generation_status
FROM
  mydataset.INFORMATION_SCHEMA.COLUMNS
WHERE
  table_name = 'images';

Wenn die Spalte image_embedding einen blockierenden Fehler enthält, sieht das Ergebnis in etwa so aus:

[
  {
    "column_name": "image_embedding",
    "async_generation_status": {
      "blocking_error": {
        "message": "<service_account> does not have the permission to access resources used by AI.EMBED. Please follow https://docs.cloud.google.com/bigquery/docs/permissions-for-ai-functions to set up permissions.",
        ...
      }
    }
  }
]

Sie können auch die Ansicht INFORMATION_SCHEMA.JOBS für den Hintergrundjob abfragen und sich die Informationen im Feld error_result ansehen. Die Job-ID eines Hintergrundjobs für Einbettungen hat das Präfix gc_. Mit der folgenden Abfrage werden beispielsweise alle Hintergrundjobs extrahiert, deren Fehlerergebnis nicht NULL ist:

SELECT * FROM `region-REGION.INFORMATION_SCHEMA.JOBS` j
WHERE EXISTS (
  SELECT 1
  FROM unnest(j.referenced_tables) t
  WHERE
    j.project_id = 'PROJECT_ID'
    AND t.dataset_id = 'DATASET_ID'
    AND t.table_id = 'TABLE'
)
AND starts_with(job_id, 'gc')
AND error_result IS NOT NULL
ORDER BY j.creation_time DESC;

Kosten im Blick behalten

Die Kosten für die autonome Einbettungsgenerierung fallen in die folgenden Kategorien.

BigQuery-Kosten für Hintergrund-DML

Generierte Einbettungen werden mithilfe von DML-Hintergrundjobs in Ihre Tabelle geschrieben. Standardmäßig verwendet BigQuery On-Demand-Slots, um diese Jobs zu verarbeiten. Das Projekt der Tabelle wird gemäß dem On-Demand-Abrechnungsmodell für DML abgerechnet.

Alternativ können Sie eine Reservierung erstellen und job_type auf BACKGROUND setzen, um eine vorhersehbare und konsistente Leistung zu erzielen. Wenn eine Hintergrundreservierung vorhanden ist, verwendet BigQuery sie, um die Hintergrund-DML-Jobs auszuführen. Und die Hintergrundreservierung wird für die Slot-Zeitnutzung der Hintergrund-DML-Jobs in Rechnung gestellt.

Wenn Sie die Werte total_slot_ms und total_bytes_billed für Hintergrund-DML-Jobs in einer Tabelle verfolgen möchten, fragen Sie die Ansicht INFORMATION_SCHEMA.JOBS nach Jobs mit dem job_id-Präfix gc_ ab:

SELECT
  job_id,
  creation_time,
  reservation_id,
  total_slot_ms,
  total_bytes_processed,
  total_bytes_billed
FROM
  `region-REGION.INFORMATION_SCHEMA.JOBS` j
WHERE
  EXISTS (
    SELECT 1
    FROM UNNEST(j.referenced_tables) t
    WHERE
      j.project_id = 'PROJECT_ID'
      AND t.dataset_id = 'DATASET_ID'
      AND t.table_id = 'TABLE'
  )
  AND STARTS_WITH(job_id, 'gc_')
ORDER BY
  j.creation_time DESC;

Ersetzen Sie Folgendes:

  • REGION: die Dataset-Region, die Ihre Tabelle enthält, z. B. us.
  • PROJECT_ID: Die ID des Projekts, das Ihre Tabelle enthält.
  • DATASET_ID: der Name des Datasets, das die Tabelle enthält.
  • TABLE: der Name der Tabelle, für die die autonome Einbettungsgenerierung aktiviert ist.

Wenn Sie das integrierte Modell embeddinggemma-300m mit dem Parameter model in der Funktion AI.EMBED angeben, generiert BigQuery die Einbettungen auch direkt in diesen Hintergrund-DML-Jobs mithilfe von BigQuery-Slots. Es werden keine Anfragen an die Agent Platform gesendet und es fallen keine Agent Platform-Gebühren an. Weitere Informationen finden Sie unter Modell auswählen.

Kosten für die Gemini Enterprise Agent Platform

Wenn Sie ein Gemini Enterprise Agent Platform-Modell mit dem Parameter endpoint in der Funktion AI.EMBED angeben, sendet die autonome Einbettungsgenerierung Anfragen an die Gemini Enterprise Agent Platform, was Kosten verursachen kann. So verfolgen Sie die Kosten der Agent-Plattform, die durch Hintergrund-Einbettungsjobs entstehen:

  1. Abrechnungsberichte in Cloud Billing ansehen

  2. Verwenden Sie Filter, um die Ergebnisse einzugrenzen.

    Wählen Sie für Dienste Vertex AI aus.

  3. Wenn Sie die Kosten für einen bestimmten Job sehen möchten, filtern Sie nach Label.

    Legen Sie den Schlüssel auf bigquery_ml_job und den Wert auf die Job-ID des Einbettungsjobs fest. Hintergrundjobs für Einbettungen haben alle das Präfix gc_.

Es kann bis zu 24 Stunden dauern, bis einige Gebühren in Cloud Billing angezeigt werden.

Beschränkungen

  • Jede Tabelle unterstützt höchstens eine automatisch generierte Einbettungsspalte.
  • Gleichzeitige DML-Vorgänge können zu Verzögerungen und vorübergehenden Fehlern bei der Einbettungsgenerierung führen. Für eine bessere Leistung und zur Kostensenkung empfehlen wir, Daten in Batches einzufügen und häufige DML-Updates zu vermeiden.
  • Wenn Sie die Legacy-Streaming API zum Aufnehmen von Daten verwenden, kann es zu Verzögerungen kommen, bevor die Einbettung generiert wird.
  • Wenn Sie die BigQuery Storage Write API (gRPC) verwenden, können Jobs zur Generierung von Einbettungen im Hintergrund fehlschlagen, wenn gleichzeitig ein Streaming-Schreibjob ausgeführt wird. In diesem Fall werden das Kontingent der Agent Platform und die Kosten für Hintergrund-DML verschwendet. Die Verwendung der Storage Write API (gRPC) führt auch zu gleichzeitigen Jobs zur Einbettungsgenerierung für die Tabelle. Dies wird jedoch von BigQuery verarbeitet und es werden keine Agent Platform-Kontingente oder Hintergrund-DML-Kosten verschwendet.
  • Für einen höheren Durchsatz auf Remote-Endpunkten der Agent Platform empfehlen wir, Modelle zur Texteinbettung anstelle von Gemini-Modellen zu verwenden. Weitere Informationen finden Sie unter Kontingente.
  • Es gibt keinen Hinweis darauf, dass eine Spalte automatisch generiert wird, wenn Sie das Schema einer Tabelle mit der Google Cloud -Console oder dem Feld ddl der Ansicht INFORMATION_SCHEMA.TABLES aufrufen.
  • Wenn Sie eine Kopie, einen Klon oder einen Snapshot einer Tabelle mit einer generierten Einbettungsspalte erstellen, werden nur die Daten kopiert. Die Generierungskonfiguration gilt nicht für die neue Tabelle und Aktualisierungen der Quellspalte der neuen Tabelle führen nicht zu neuen Einbettungen.
  • Wenn Sie eine Tabelle, für die die autonome Einbettungsgenerierung aktiviert war, aus einem Snapshot wiederherstellen, wird die Konfiguration für die Einbettungsgenerierung nicht wiederhergestellt.
  • Wenn Sie die BigQuery API verwenden, können Sie das Attribut generatedColumn nur beim Erstellen einer neuen Spalte angeben. Sie können das Attribut generatedColumn in einer vorhandenen Spalte nicht hinzufügen, aktualisieren oder entfernen.

  • Nachdem Sie die generierte Einbettungsspalte erstellt haben, gelten die folgenden Einschränkungen:

    • Sie können die Quellspalte nicht löschen oder umbenennen, aber Sie können die generierte Einbettungsspalte löschen oder umbenennen. Wenn Sie die Einbettungsspalte löschen, können Sie die Quellspalte löschen oder umbenennen.
    • Sie können den Datentyp der Quellspalte oder der generierten Einbettungsspalte nicht ändern.

  • Für automatisch generierte Einbettungsspalten können Sie keine Standardwerte angeben.

  • Sie können mit den folgenden Methoden nicht direkt in generierte Einbettungsspalten schreiben:

    • DML
    • Streaming-Schreibvorgänge
    • bq insert
    • bq load
    • bq copy -a

  • Tabellen mit generierten Einbettungsspalten unterstützen keine Sicherheitsrichtlinien auf Spaltenebene, z. B. Richtlinien-Tags.

  • Wenn Sie eine Suchfunktion wie VECTOR_SEARCH oder AI.SEARCH aufrufen, werden Zeilen mit fehlenden Einbettungen in der Basistabelle während der Suche übersprungen.

  • Sie können keinen partitionierten Vektorindex für eine Tabelle erstellen, für die die autonome Einbettungsgenerierung aktiviert ist.

  • Wenn Sie einen Vektorindex für die automatisch generierte Einbettungsspalte erstellen, beginnt das Indextraining, nachdem für mindestens 80% der Zeilen Einbettungen generiert wurden. So können Sie den Fortschritt der Einbettungserstellung prüfen:

    Fragen Sie den Prozentsatz der Einbettungen in Ihrer Tabelle ab, die generiert wurden:

    SELECT
  COUNTIF(description_embedding IS NOT NULL
  AND description_embedding.status = '') * 100.0 / COUNT(*) AS percent
FROM PROJECT_ID.DATASET_ID.TABLE;

Nächste Schritte