Texteinbettungen mit der Funktion ML.GENERATE_EMBEDDING generieren

In dieser Anleitung wird gezeigt, wie Sie ein BigQuery ML-Remote-Modell erstellen, das auf das Modell 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. 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, 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.

    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.

      Seite "Dataset erstellen"

Verbindung herstellen

Erstellen Sie eine Cloud-Ressourcenverbindung und rufen Sie das Dienstkonto der Verbindung ab. Erstellen Sie die Verbindung in demselben Standort wie dem des von Ihnen im vorherigen Schritt erstellten Datasets.

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 dabei 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": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

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

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/text-embedding-004', 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 = 'text-embedding-004', 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-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

So weisen Sie die Rolle zu:

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 `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.
    • 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 Modell für die Einbettung.

Texteinbettungen mit 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 text-embedding- oder text-multilingual-embedding-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.

Texteinbettung

Generieren Sie Texteinbettungen mit einem Remote-Modell über ein Einbettungsmodell:

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,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Projekt-ID.
  • DATASET_ID ist die ID des Datasets, das das Modell enthält.
  • MODEL_NAME: der Name des Remote-Modells über ein Einbettungsmodell.
  • 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.
  • OUTPUT_DIMENSIONALITY: ein INT64-Wert, der die Anzahl der Dimensionen angibt, die beim Generieren von Einbettungen verwendet werden sollen. Wenn Sie beispielsweise 256 AS output_dimensionality angeben, enthält die Ausgabespalte ml_generate_embedding_result 256 Embeddings für jeden Eingabewert.

    Sie können dieses Argument nur verwenden, wenn für das Remote-Modell, das Sie im model-Argument angeben, eines der folgenden Modelle als Endpunkt verwendet wird:

    • Ab text-embedding-004
    • Ab text-multilingual-embedding-002

multimodale Einbettung

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

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，
  OUTPUT_DIMENSIONALITY AS output_dimensionality)
);

Ersetzen Sie Folgendes:

  • PROJECT_ID: 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.
  • OUTPUT_DIMENSIONALITY: ein INT64-Wert, der die Anzahl der Dimensionen angibt, die beim Generieren von Einbettungen verwendet werden sollen. Gültige Werte sind 128, 256, 512 und 1408. Der Standardwert ist 1408. Wenn Sie beispielsweise 256 AS output_dimensionality angeben, enthält die Ausgabespalte ml_generate_embedding_result für jeden Eingabewert 256 Einbettungen.

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 ein Einbettungsmodell bereitgestellt werden.

In der Regel sollten Sie ein text-embedding- oder text-multilingual-embedding-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.

Texteinbettung

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

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,
    OUTPUT_DIMENSIONALITY AS output_dimensionality)
  );

Ersetzen Sie Folgendes:

  • PROJECT_ID: Ihre Projekt-ID.
  • DATASET_ID ist die ID des Datasets, das das Modell enthält.
  • MODEL_NAME: der Name des Remote-Modells über ein Einbettungsmodell.
  • 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.
  • OUTPUT_DIMENSIONALITY: ein INT64-Wert, der die Anzahl der Dimensionen angibt, die beim Generieren von Einbettungen verwendet werden sollen. Wenn Sie beispielsweise 256 AS output_dimensionality angeben, enthält die Ausgabespalte ml_generate_embedding_result 256 Embeddings für jeden Eingabewert.

    Sie können dieses Argument nur verwenden, wenn für das Remote-Modell, das Sie im model-Argument angeben, eines der folgenden Modelle als Endpunkt verwendet wird:

    • Ab text-embedding-004
    • Ab text-multilingual-embedding-002

multimodale Einbettung

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

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: 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.
  • OUTPUT_DIMENSIONALITY: ein INT64-Wert, der die Anzahl der Dimensionen angibt, die beim Generieren von Einbettungen verwendet werden sollen. Gültige Werte sind 128, 256, 512 und 1408. Der Standardwert ist 1408. Wenn Sie beispielsweise 256 AS output_dimensionality angeben, enthält die Ausgabespalte ml_generate_embedding_result für jeden Eingabewert 256 Einbettungen.

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, 'CLASSIFICATION' AS task_type)
  );

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 just okay...              | 0.062789813467745592       |
| This movie was fantastic                 |  0.18579561313064263       |
| This movie was terrible.                 |  0.35707466240930985       |
| This was the best movie I've ever seen!! |  0.41844932504542975       |
+------------------------------------------+----------------------------+