Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Automatische Einbettungserstellung

In diesem Dokument wird beschrieben, wie Sie die automatische Einbettungserstellung für Ihre Daten verwenden. Damit kann BigQuery eine Spalte mit Einbettungen in einer Tabelle basierend auf einer Quellspalte verwalten. Die Quellspalte muss den Datentyp STRING oder ObjectRef haben. Wenn Sie Daten in der Quellspalte hinzufügen oder ändern, generiert oder aktualisiert BigQuery automatisch die Einbettungsspalte für diese Daten mithilfe eines Agent Platform-Einbettungsmodells. Das ist hilfreich, wenn Sie BigQuery Ihre Einbettungen 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), aber sie können komplex zu erstellen, zu verwalten und abzufragen sein. Mit der automatischen Einbettungserstellung können Sie den Prozess der Erstellung, Verwaltung und Abfrage 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 mit aktivierter automatischer Einbettungserstellung 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 automatische Einbettungserstellung für eine Tabelle aktivieren möchten, benötigen Sie die erforderlichen Berechtigungen und eine Verbindung und müssen 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 Einbettungserstellung benötigen:

Zum Verwenden einer Verbindungsressource: BigQuery-Verbindungsnutzer (roles/bigquery.connectionUser) für die Verbindung
Zum Erstellen oder Ändern einer Tabelle: BigQuery-Datenbearbeiter (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-Nutzer (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 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-Nutzer“ (roles/aiplatform.user) zu.

Automatisch generierte Einbettungsspalte erstellen

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

Tabelle mit einer automatisch generierten Einbettungsspalte erstellen

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

SQL

Verwenden Sie eine CREATE TABLE-Anweisung, um eine Tabelle mit einer automatisch generierten Einbettungsspalte zu erstellen. Führen Sie dazu die folgenden Schritte aus:

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

BigQuery aufrufen
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 automatische Einbettungserstellung 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-Nutzer“ zuweisen.
- ENDPOINT: ein STRING-Wert, der einen unterstützten Agent Platform-Texteinbettungsmodell-Endpunkt angibt. 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 (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 Agent Platform gesendet und es fallen keine Gebühren in Agent Platform an.
Klicken Sie auf Ausführen.

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

bq

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

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 Einbettungserstellung 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 anstelle eines Agent Platform Endpunkts ein integriertes Modell verwenden, verwenden Sie eine ähnliche Syntax wie die folgende für generationExpression: "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.

Speichern Sie das Schema in einer Datei wie schema.json.
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 automatische Einbettungserstellung 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-Nutzer“ zuweisen.
ENDPOINT: ein STRING-Wert, der einen unterstützten Agent Platform Endpunkt für das Texteinbettungsmodell angibt. 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 (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 Agent Platform gesendet und es fallen keine Gebühren in Agent Platform an.

Vorhandener Tabelle eine automatisch generierte Einbettungsspalte hinzufügen

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

SQL

Verwenden Sie eine ALTER TABLE ADD COLUMN-Anweisung, um einer vorhandenen Tabelle eine automatisch generierte Einbettungsspalte hinzuzufügen. Führen Sie dazu die folgenden Schritte aus:

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

BigQuery aufrufen
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 Agent Platform-Texteinbettungsmodell-Endpunkt angibt.
- 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 Agent Platform gesendet und es fallen keine Gebühren in Agent Platform an.
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:

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

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 Einbettungserstellung 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"
  }
]

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.

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 Einbettungserstellung wird kurz nach dem Erstellen oder Ändern der Tabelle oder nach dem Aktualisieren der Daten in der Quellspalte gestartet.

Wenn Sie den Fortschritt der Einbettungserstellung 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 Einbettungserstellung 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 automatischer Einbettungserstellung, 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   |
 +------------------+----------------------------------------------+----------------------*/

Aus `ObjectRef`-Spalten generierte Einbettungen

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

Das folgende Beispiel zeigt, 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 =>