Automatische Generierung von Einbettungen

Vorschau

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Hinweis: Wenn Sie Feedback geben oder Support für diese Funktion anfordern möchten, wenden Sie sich bitte an [e-mail]

In diesem Dokument wird beschrieben, wie Sie die automatische Generierung von Einbettungen für Ihre Daten verwenden. Mit dieser Funktion kann BigQuery eine Spalte mit Einbettungen in einer Tabelle basierend auf einer Quellspalte verwalten. Wenn Sie Daten in der Quellspalte hinzufügen oder ändern, generiert oder aktualisiert BigQuery automatisch die Spalte mit Einbettungen für diese Daten. Dazu wird ein Vertex AI-Einbettungsmodell verwendet. Das ist hilfreich, wenn Sie Ihre Einbettungen von BigQuery verwalten lassen möchten, 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 automatischen Generierung von Einbettungen können Sie das Erstellen, Verwalten und Abfragen von Einbettungen für die Verwendung in Ähnlichkeitssuchen und anderen generativen KI-Anwendungen vereinfachen.

Sie können beispielsweise Abfragen wie die folgenden verwenden, um eine Tabelle zu erstellen, in der die automatische Generierung von Einbettungen aktiviert ist, 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 automatische Generierung von Einbettungen für eine Tabelle aktivieren möchten, benötigen Sie die erforderlichen Berechtigungen und eine 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 automatischen Generierung von Einbettungen benötigen:

• Zum Verwenden einer Verbindungsressource: BigQuery Connections User (roles/bigquery.connectionUser) für die Verbindung
• Zum Erstellen oder Ändern einer Tabelle: BigQuery Data Editor (roles/bigquery.dataEditor) für die Tabelle
• Weisen Sie dem Dienstkonto der Verbindung die folgende Rolle zu, damit es auf Modelle zugreifen kann, die in Vertex AI-Endpunkten gehostet werden: Vertex AI User (roles/aiplatform.user) für das Projekt mit der Verbindung

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 Berechtigung für ein Dienstkonto gewähren

Wenn Sie die automatische Generierung von Einbettungen 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 „Vertex AI-Nutzer“ (roles/aiplatform.user) zu.

Automatisch generierte Spalte mit Einbettungen erstellen

Sie können entweder eine automatisch generierte Spalte mit Einbettungen in einer neuen Tabelle erstellen oder einer vorhandenen Tabelle hinzufügen.

Tabelle mit einer automatisch generierten Spalte mit Einbettungen erstellen

Sie können die automatische Generierung von Einbettungen verwenden, um Einbettungen mit der AI.EMBED Funktion in einer CREATE TABLE Anweisung zu generieren.

CREATE TABLE DATASET_ID.TABLE (
  [COLUMN, ...]
  STRING_COL STRING,
  EMBEDDING_COL_NAME STRUCT<result ARRAY<FLOAT64>, status STRING>
    GENERATED ALWAYS AS (
      AI.EMBED(
        STRING_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 automatische Generierung von Einbettungen 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 Spalte mit Einbettungen.
• 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 „Vertex AI-Nutzer“ zuweisen.
• ENDPOINT: Ein STRING-Wert, der einen unterstützten Vertex AI Texteinbettungsmodell Endpunkt angibt, der für das Texteinbettungsmodell verwendet werden soll. Der 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 (Vorschau): 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 verwendet, um die Einbettungen zu erstellen. Es werden keine Daten an Vertex AI gesendet und es fallen keine Kosten in Vertex AI an.

Vorhandener Tabelle eine automatisch generierte Spalte mit Einbettungen hinzufügen

Sie können einer vorhandenen Tabelle auch eine automatisch generierte Spalte mit Einbettungen hinzufügen. Verwenden Sie dazu die ALTER TABLE ADD COLUMN Anweisung.

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

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

Wenn Sie den Fortschritt der Generierung von Einbettungen verfolgen möchten, können Sie eine Abfrage wie die folgende verwenden:

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 haben, können Sie einen Vektorindex erstellen für die STRUCT Spalte, 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 automatische Generierung von Einbettungen einrichten, um die semantische Suche in Ihren Produktbeschreibungen zu unterstützen.

Erstellen Sie zuerst ein Dataset:

CREATE SCHEMA mydataset;

Erstellen Sie dann eine Tabelle, in der die automatische Generierung von Einbettungen aktiviert ist, um Ihre Produktinformationen zu speichern. Die automatisch generierte Spalte heißt description_embedding und basiert auf der description Spalte.

# 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 er 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. Bei der folgenden Abfrage wird 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 mit der AI.SEARCH Funktion eine semantische Suche nach einem lustigen Spielzeug für Ihre Produkte durchfü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   |
 +------------------+----------------------------------------------+----------------------*/

Informationen zu automatisch generierten Spalten mit Einbettungen abrufen

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

Die folgende Abfrage zeigt Informationen zu allen automatisch generierten Spalten mit Einbettungen:

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

Im Feld generation_expression sehen Sie den Aufruf der Funktion AI.EMBED, mit der die Einbettungen in der Spalte generiert werden.

Eigene Reservierung verwenden

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

Fehlerbehebung

Die generierte Spalte mit Einbettungen enthält zwei Felder: result und status. Wenn ein Fehler auftritt, wenn 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 result Einbettung ebenfalls NULL und der Status ist NULL value is not supported for embedding generation.

Ein schwerwiegenderer Fehler kann die Generierung von Einbettungen zum Stillstand bringen. In diesem Fall können Sie die INFORMATION_SCHEMA.JOBS Ansicht nach dem Hintergrundjob abfragen und die Informationen im error_result Feld ansehen. Die Job-ID eines Hintergrundjobs zur Generierung von 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 verfolgen

Bei der automatischen Generierung von Einbettungen werden Anfragen an Vertex AI gesendet, wodurch Kosten entstehen können. So verfolgen Sie die Vertex AI-Kosten, die durch Hintergrundjobs zur Generierung von Einbettungen entstehen:

1. Rufen Sie Ihre Abrechnungsberichte in Cloud Billing auf.

2. Verwenden Sie Filter, um die Ergebnisse einzugrenzen.

   Wählen Sie für Dienste die Option 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. Alle Hintergrundjobs zur Generierung von Einbettungen haben das Präfix gc_.

Es kann bis zu 24 Stunden dauern, bis einige Kosten in Cloud Billing angezeigt werden.

Beschränkungen

• Jede Tabelle unterstützt maximal eine automatisch generierte Spalte mit Einbettungen.
• Gleichzeitige DML-Vorgänge können zu Verzögerungen und vorübergehenden Fehlern bei der Generierung von Einbettungen führen. Für eine bessere Leistung und zur Reduzierung der Kosten empfehlen wir, Daten in Batches einzufügen und häufige DML-Aktualisierungen zu vermeiden.
• Wenn Sie die BigQuery Storage Write API zum Aufnehmen von Daten verwenden, kann es zu Verzögerungen kommen, bevor die Generierung von Einbettungen beginnt.
• Es gibt keinen Hinweis darauf, dass eine Spalte automatisch generiert wird, wenn Sie das Schema einer Tabelle mit der Google Cloud Console, dem bq show Befehl, oder dem ddl Feld der INFORMATION_SCHEMA.TABLES Ansicht aufrufen.
• Wenn Sie eine Kopie, einen Klon oder einen Snapshot einer Tabelle mit einer generierten Spalte mit Einbettungen 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 automatische Generierung von Einbettungen aktiviert war, aus einem Snapshot wiederherstellen, wird die Konfiguration zur Generierung von Einbettungen nicht wiederhergestellt.
• Sie können generierte Spalten mit Einbettungen nur mit SQL erstellen. Sie können die Befehle bq mk oder bq update nicht verwenden, um generierte Spalten mit Einbettungen zu erstellen.
• Die Quellspalte der generierten Spalte muss eine STRING-Spalte sein.

• Nachdem Sie die generierte Spalte mit Einbettungen erstellt haben, gelten die folgenden Einschränkungen:

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

• Sie können keine Standardwerte für automatisch generierte Spalten mit Einbettungen angeben.

• Sie können mit diesen Methoden nicht direkt in generierte Spalten mit Einbettungen schreiben:

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

• Tabellen mit generierten Spalten mit Einbettungen unterstützen keine Sicherheitsrichtlinien auf Spaltenebene wie Richtlinien-Tags.

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

• Sie können keinen partitionierten Vektorindex für eine Tabelle erstellen, für die die automatische Generierung von Einbettungen aktiviert ist.

• Wenn Sie einen Vektorindex für die automatisch generierte Spalte mit Einbettungen erstellen, beginnt das Indextraining, nachdem für mindestens 80% der Zeilen Einbettungen generiert wurden. Mit der folgenden Abfrage können Sie prüfen, wie viel Prozent der Einbettungen in Ihrer Tabelle 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

• Weitere Informationen zum Erstellen und Verwalten von Vektorindexen.
• Siehe die Einführung in die Vektorsuche.