Texteinbettungen mit der Funktion ML.GENERATE_EMBEDDING generieren

In dieser Anleitung wird gezeigt, wie Sie ein BigQuery ML-Remote-Modell erstellen, das auf das Foundation Model der Vertex AI verweist. Anschließend verwenden Sie dieses Modell mit der ML.GENERATE_EMBEDDING-Funktion, um Texteinbettungen über Daten aus einer BigQuery-Standardtabelle zu erstellen.

Erforderliche Rollen

• Zum Erstellen einer Verbindung benötigen Sie die Mitgliedschaft in der folgenden IAM-Rolle (Identity and Access Management):

  • roles/bigquery.connectionAdmin

• Zum Erteilen von Berechtigungen für das Dienstkonto der Verbindung benötigen Sie die folgende Berechtigung:

  • resourcemanager.projects.setIamPolicy

• Zum Erstellen des Modells mit BigQuery ML benötigen Sie die folgenden IAM-Berechtigungen:

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• Zum Ausführen von Inferenzen benötigen Sie die folgenden Berechtigungen:

  • bigquery.tables.getData für die Tabelle
  • bigquery.models.getData für das Modell
  • bigquery.jobs.create

Hinweise

1. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

   Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

   Zur Projektauswahl

2. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

3. BigQuery, BigQuery Connection, and Vertex AI APIs aktivieren.

   Aktivieren Sie die APIs

Dataset erstellen

Erstellen Sie ein BigQuery-Dataset, um Ihr ML-Modell zu speichern:

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

   Zur Seite „BigQuery“

2. Klicken Sie im Bereich Explorer auf den Namen Ihres Projekts.

3. Klicken Sie auf Aktionen ansehen > Dataset erstellen.

   

4. Führen Sie auf der Seite Dataset erstellen die folgenden Schritte aus:

   • Geben Sie unter Dataset-ID bqml_tutorial ein.

   • Wählen Sie als Standorttyp die Option Mehrere Regionen und dann USA (mehrere Regionen in den USA) aus.

     Die öffentlichen Datasets sind am multiregionalen Standort US gespeichert. Der Einfachheit halber sollten Sie Ihr Dataset am selben Standort speichern.

   • Übernehmen Sie die verbleibenden Standardeinstellungen unverändert und klicken Sie auf Dataset erstellen.

     

Verbindung herstellen

Erstellen Sie eine Cloud-Ressourcenverbindung und rufen Sie das Dienstkonto der Verbindung ab. Erstellen Sie die Verbindung am selben Standort wie das im vorherigen Schritt erstellte Dataset.

Wählen Sie eine der folgenden Optionen aus:

Console

1. Rufen Sie die Seite BigQuery auf.

   BigQuery aufrufen

2. Klicken Sie auf Hinzufügen und dann auf Verbindungen zu externen Datenquellen, um eine Verbindung zu erstellen.

3. Wählen Sie in der Liste Verbindungstyp die Option Vertex AI-Remote-Modelle, Remote-Funktionen und BigLake (Cloud Resource) aus.

4. Geben Sie im Feld Verbindungs-ID einen Namen für die Verbindung ein.

5. Klicken Sie auf Verbindung erstellen.

6. Klicken Sie auf Zur Verbindung.

7. Kopieren Sie im Bereich Verbindungsinformationen die Dienstkonto-ID zur Verwendung in einem späteren Schritt.

bq

1. Erstellen Sie in einer Befehlszeilenumgebung eine Verbindung:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID
   

   Der Parameter --project_id überschreibt das Standardprojekt.

   Ersetzen Sie Folgendes:

   • REGION: Ihre Verbindungsregion
   • PROJECT_ID: Ihre Google Cloud-Projekt-ID
   • CONNECTION_ID: eine ID für Ihre Verbindung

   Wenn Sie eine Verbindungsressource herstellen, erstellt BigQuery ein eindeutiges Systemdienstkonto und ordnet es der Verbindung zu.

   Fehlerbehebung:Wird der folgende Verbindungsfehler angezeigt, aktualisieren Sie das Google Cloud SDK:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Rufen Sie die Dienstkonto-ID ab und kopieren Sie sie zur Verwendung in einem späteren Schritt:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID
   

   Die Ausgabe sieht in etwa so aus:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

Hängen Sie folgenden Abschnitt an Ihre main.tf-Datei an.

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}        

Ersetzen Sie Folgendes:

• CONNECTION_ID: eine ID für Ihre Verbindung
• PROJECT_ID: Ihre Google Cloud-Projekt-ID
• REGION: Ihre Verbindungsregion

Dem Dienstkonto Zugriff gewähren

Gewähren Sie Ihrem Dienstkonto die Berechtigung, die Verbindung zu verwenden. Wenn Sie keine Berechtigung erteilen, tritt ein Fehler auf. Wählen Sie eine der folgenden Optionen aus:

Console

1. Zur Seite IAM & Verwaltung.

   IAM & Verwaltung aufrufen

2. Klicken Sie auf Zugriff erlauben.

   Das Dialogfeld Principals hinzufügen wird geöffnet.

3. Geben Sie im Feld Neue Hauptkonten die Dienstkonto-ID ein, die Sie zuvor kopiert haben.

4. Wählen Sie im Feld Rolle auswählen die Option Vertex AI und dann Vertex AI-Nutzer aus.

5. Klicken Sie auf Speichern.

gcloud

Führen Sie den Befehl gcloud projects add-iam-policy-binding aus:

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

Ersetzen Sie Folgendes:

• PROJECT_NUMBER: Ihre Projektnummer
• MEMBER: Die Dienstkonto-ID, die Sie zuvor kopiert haben

Modell erstellen

1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

   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 `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (ENDPOINT = 'ENDPOINT');
   

   Ersetzen Sie Folgendes:

   • PROJECT_ID: Ihre Projekt-ID.
   • DATASET_ID: die ID des Datasets, das das Modell enthalten soll
   • 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: Das zu verwendende LLM der Einbettung. Beispiel: ENDPOINT='multimodalembedding'

     Für einige Modelltypen können Sie eine bestimmte Version des Modells angeben, indem Sie @version an den Modellnamen anhängen. Beispiel: textembedding-gecko@001 Informationen zu unterstützten Modellversionen für die verschiedenen Modelltypen finden Sie unter ENDPOINT.

Hinweis: Sie können ein Remote-Modell über ein Vertex AI-textembedding-gecko-Modell erstellen. Dazu geben Sie den REMOTE_SERVICE_TYPE-Wert als „CLOUD_AI_TEXT_EMBEDDING_MODEL_V1“ an. Die bevorzugte Methode zum Erstellen eines Remote-Modells gegenüber einem LLM besteht jedoch darin, das LLM stattdessen als Endpunkt anzugeben, wie hier gezeigt.

Texteinbettungen mithilfe von Daten aus einer Tabelle generieren

Erzeugen Sie Texteinbettungen mit der Funktion ML.GENERATE_EMBEDDING mithilfe von Textdaten aus einer Tabellenspalte.

In der Regel sollten Sie ein textembedding-gecko- oder textembedding-gecko-multilingual-Modell für Anwendungsfälle mit nur Text und ein multimodalembedding-Modell für modale Suchanwendungsfälle verwenden, wobei Einbettungen für Text und visuelle Inhalte im selben semantischen Bereich generiert werden.

textembedding-gecko*

Generieren Sie Texteinbettungen mit einem Remote-Modell über das textembedding-gecko- oder textembedding-gecko-multilingual-LLM:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type)
);

Ersetzen Sie Folgendes:

• PROJECT_ID ist Ihre Projekt-ID.
• DATASET_ID ist die ID des Datasets, das das Modell enthält.
• MODEL_NAME: der Name des Remote-Modells über ein textembedding-gecko- oder textembedding-gecko-multilingual-Modell.
• TABLE_NAME ist der Name der Tabelle, die den einzubettenden Text enthält. Diese Tabelle muss eine Spalte namens content enthalten. Sie können auch einen Alias nutzen, um eine Spalte mit anderen Namen zu verwenden.
• FLATTEN_JSON ist ein BOOL-Wert, der angibt, ob die Einbettung in eine separate Spalte geparst werden soll. Der Standardwert ist TRUE.
• TASK_TYPE: Ein STRING-Literal, das die beabsichtigte nachgelagerte Anwendung angibt, um dem Modell zu helfen, Einbettungen mit höherer Qualität zu erstellen. TASK_TYPE kann folgende Werte haben:
  • RETRIEVAL_QUERY: Gibt an, dass der angegebene Text eine Abfrage in einer Such- oder Abrufeinstellung ist.
  • RETRIEVAL_DOCUMENT: Gibt an, dass der angegebene Text ein Dokument in einer Such- oder Abrufeinstellung ist.

    Bei Verwendung dieses Aufgabentyps ist es hilfreich, den Dokumenttitel in die Abfrageanweisung aufzunehmen, um die Einbettungsqualität zu verbessern. Sie können die Option title verwenden, um den Namen der Spalte anzugeben, die den Dokumenttitel enthält. Andernfalls muss sich der Dokumenttitel in einer Spalte befinden, die entweder title heißt oder den Alias title verwendet. Beispiel:

          SELECT *
          FROM
            ML.GENERATE_EMBEDDING(
              MODEL mydataset.embedding_model,
              (SELECT abstract as content, header as title, publication_number
              FROM mydataset.publications),
              STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
          );
          

  • SEMANTIC_SIMILARITY: Gibt an, dass der angegebene Text für die Bestimmung der semantischen Textähnlichkeit (Semantic Textual Similarity, STS) verwendet wird.
  • CLASSIFICATION: Gibt an, dass die Einbettungen zur Klassifizierung verwendet werden.
  • CLUSTERING: Gibt an, dass die Einbettungen für das Clustering verwendet werden.

multimodalembedding

Generieren Sie Texteinbettungen mit einem Remote-Modell über das multimodalembedding-LLM:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE PROJECT_ID.DATASET_ID.TABLE_NAME,
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

Ersetzen Sie Folgendes:

• PROJECT_ID ist Ihre Projekt-ID.
• DATASET_ID ist die ID des Datasets, das das Modell enthält.
• MODEL_NAME: der Name des Remote-Modells über ein multimodalembedding@001-Modell.
• TABLE_NAME ist der Name der Tabelle, die den einzubettenden Text enthält. Diese Tabelle muss eine Spalte namens content enthalten. Sie können auch einen Alias nutzen, um eine Spalte mit anderen Namen zu verwenden.
• FLATTEN_JSON ist ein BOOL-Wert, der angibt, ob die Einbettung in eine separate Spalte geparst werden soll. Der Standardwert ist TRUE.

Texteinbettungen mithilfe von Daten aus einer Abfrage generieren

Erstellen Sie Texteinbettungen mit der Funktion ML.GENERATE_EMBEDDING. Verwenden Sie dazu Textdaten, die von einer Abfrage und einem Remote-Modell über das LLM textembedding-gecko oder textembedding-gecko-multilingual bereitgestellt werden:

In der Regel sollten Sie ein textembedding-gecko- oder textembedding-gecko-multilingual-Modell für Anwendungsfälle mit nur Text und ein multimodalembedding-Modell für modale Suchanwendungsfälle verwenden, wobei Einbettungen für Text und visuelle Inhalte im selben semantischen Bereich generiert werden.

textembedding-gecko*

Generieren Sie Texteinbettungen mit einem Remote-Modell über das textembedding-gecko- oder textembedding-gecko-multilingual-LLM:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output,
    TASK_TYPE AS task_type
  );

Ersetzen Sie Folgendes:

• PROJECT_ID ist Ihre Projekt-ID.
• DATASET_ID ist die ID des Datasets, das das Modell enthält.
• MODEL_NAME: der Name des Remote-Modells über ein textembedding-gecko- oder textembedding-gecko-multilingual-Modell.
• CONTENT_QUERY ist eine Abfrage, deren Ergebnis ein STRING-Spalte mit dem Namen content enthält.
• FLATTEN_JSON ist ein BOOL-Wert, der angibt, ob die Einbettung in eine separate Spalte geparst werden soll. Der Standardwert ist TRUE.
• TASK_TYPE: Ein STRING-Literal, das die beabsichtigte nachgelagerte Anwendung angibt, um dem Modell zu helfen, Einbettungen mit höherer Qualität zu erstellen. TASK_TYPE kann folgende Werte haben:
  • RETRIEVAL_QUERY: Gibt an, dass der angegebene Text eine Abfrage in einer Such- oder Abrufeinstellung ist.
  • RETRIEVAL_DOCUMENT: Gibt an, dass der angegebene Text ein Dokument in einer Such- oder Abrufeinstellung ist.

    Bei Verwendung dieses Aufgabentyps ist es hilfreich, den Dokumenttitel in die Abfrageanweisung aufzunehmen, um die Einbettungsqualität zu verbessern. Sie können die Option title verwenden, um den Namen der Spalte anzugeben, die den Dokumenttitel enthält. Andernfalls muss sich der Dokumenttitel in einer Spalte befinden, die entweder title heißt oder den Alias title verwendet. Beispiel:

              SELECT *
              FROM
                ML.GENERATE_EMBEDDING(
                  MODEL mydataset.embedding_model,
                  (SELECT abstract as content, header as title, publication_number
                  FROM mydataset.publications),
                  STRUCT(TRUE AS flatten_json_output, 'RETRIEVAL_DOCUMENT' as task_type)
              );
              

  • SEMANTIC_SIMILARITY: Gibt an, dass der angegebene Text für die Bestimmung der semantischen Textähnlichkeit (Semantic Textual Similarity, STS) verwendet wird.
  • CLASSIFICATION: Gibt an, dass die Einbettungen zur Klassifizierung verwendet werden.
  • CLUSTERING: Gibt an, dass die Einbettungen für das Clustering verwendet werden.

multimodalembedding

Generieren Sie Texteinbettungen mit einem Remote-Modell über das multimodalembedding-LLM:

SELECT *
FROM ML.GENERATE_EMBEDDING(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (CONTENT_QUERY),
  STRUCT(FLATTEN_JSON AS flatten_json_output)
);

Ersetzen Sie Folgendes:

• PROJECT_ID ist Ihre Projekt-ID.
• DATASET_ID ist die ID des Datasets, das das Modell enthält.
• MODEL_NAME: der Name des Remote-Modells über ein multimodalembedding@001-Modell.
• CONTENT_QUERY ist eine Abfrage, deren Ergebnis ein STRING-Spalte mit dem Namen content enthält.
• FLATTEN_JSON ist ein BOOL-Wert, der angibt, ob die Einbettung in eine separate Spalte geparst werden soll. Der Standardwert ist TRUE.

Beispiele

Die folgenden Beispiele zeigen, wie die Funktion ML.GENERATE_EMBEDDING für eine Tabelle und eine Abfrage aufgerufen wird.

Text in eine Tabelle einbetten

Das folgende Beispiel zeigt eine Anfrage zum Einbetten der Spalte content der Tabelle text_data:

SELECT *
FROM
  ML.GENERATE_EMBEDDING(
    MODEL `mydataset.embedding_model`,
    TABLE mydataset.text_data,
    STRUCT(TRUE AS flatten_json_output)
  );

Semantische Ähnlichkeit mit Einbettungen sortieren

Im folgenden Beispiel wird eine Sammlung von Filmrezensionen eingebettet. Die Rezension werden dann mithilfe der ML.DISTANCE-Funktion nach der Kosinus-Distanz zur Rezension "Dieser Film war durchschnittlich" sortiert. Eine kleinere Distanz weist auf eine größere semantische Ähnlichkeit hin.

WITH movie_review_embeddings AS (
  SELECT *
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (
        SELECT "Movie 1" AS title, "This movie was fantastic" AS content
        UNION ALL
        SELECT "Movie 2" AS title, "This was the best movie I've ever seen!!" AS content
        UNION ALL
        SELECT "Movie 3" AS title, "This movie was just okay..." AS content
        UNION ALL
        SELECT "Movie 4" AS title, "This movie was terrible." AS content
      ),
      STRUCT(TRUE AS flatten_json_output)
    )
),
average_review_embedding AS (
  SELECT ml_generate_embedding_result
  FROM
    ML.GENERATE_EMBEDDING(
      MODEL `bqml_tutorial.embedding_model`,
      (SELECT "This movie was average" AS content),
      STRUCT(TRUE AS flatten_json_output)
    )
)
SELECT
  content,
  ML.DISTANCE(
    (SELECT ml_generate_embedding_result FROM average_review_embedding),
    ml_generate_embedding_result,
    'COSINE'
  ) AS distance_to_average_review
FROM
  movie_review_embeddings
ORDER BY distance_to_average_review;

Das Ergebnis lautet:

+------------------------------------------+----------------------------+
| content                                  | distance_to_average_review |
+------------------------------------------+----------------------------+
| This movie was fantastic                 | 0.10028859431058901        |
| This movie was terrible.                 |   0.142427236973374        |
| This was the best movie I've ever seen!! | 0.46742391210381995        |
| This movie was just okay...              | 0.47399255715360622        |
+------------------------------------------+----------------------------+