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 Tabellebigquery.models.getData
für das Modellbigquery.jobs.create
Hinweise
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.
Dataset erstellen
Erstellen Sie ein BigQuery-Dataset, um Ihr ML-Modell zu speichern:
Rufen Sie in der Google Cloud Console die Seite „BigQuery“ auf.
Klicken Sie im Bereich Explorer auf den Namen Ihres Projekts.
Klicken Sie auf
Aktionen ansehen > Dataset erstellen.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 in demselben Standort wie dem des von Ihnen im vorherigen Schritt erstellten Datasets.
Wählen Sie eine der folgenden Optionen aus:
Console
Rufen Sie die Seite BigQuery auf.
Klicken Sie auf
Hinzufügen und dann auf Verbindungen zu externen Datenquellen, um eine Verbindung zu erstellen.Wählen Sie in der Liste Verbindungstyp die Option Vertex AI-Remote-Modelle, Remote-Funktionen und BigLake (Cloud Resource) aus.
Geben Sie im Feld Verbindungs-ID einen Namen für die Verbindung ein.
Klicken Sie auf Verbindung erstellen.
Klicken Sie auf Zur Verbindung.
Kopieren Sie im Bereich Verbindungsinformationen die Dienstkonto-ID zur Verwendung in einem späteren Schritt.
bq
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 VerbindungsregionPROJECT_ID
: Ihre Google Cloud-Projekt-IDCONNECTION_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...
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
Verwenden Sie die Ressource google_bigquery_connection
:
Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.
Im folgenden Beispiel wird eine Cloud-Ressourcenverbindung mit dem Namen my_cloud_resource_connection
in der Region US
erstellt:
Führen Sie die Schritte in den folgenden Abschnitten aus, um Ihre Terraform-Konfiguration auf ein Google Cloud-Projekt anzuwenden.
Cloud Shell vorbereiten
- Rufen Sie Cloud Shell auf.
-
Legen Sie das Google Cloud-Standardprojekt fest, auf das Sie Ihre Terraform-Konfigurationen anwenden möchten.
Sie müssen diesen Befehl nur einmal pro Projekt und in jedem beliebigen Verzeichnis ausführen.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
Umgebungsvariablen werden überschrieben, wenn Sie in der Terraform-Konfigurationsdatei explizite Werte festlegen.
Verzeichnis vorbereiten
Jede Terraform-Konfigurationsdatei muss ein eigenes Verzeichnis haben (auch als Stammmodul bezeichnet).
-
Erstellen Sie in Cloud Shell ein Verzeichnis und eine neue Datei in diesem Verzeichnis. Der Dateiname muss die Erweiterung
.tf
haben, z. B.main.tf
. In dieser Anleitung wird die Datei alsmain.tf
bezeichnet.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Wenn Sie einer Anleitung folgen, können Sie den Beispielcode in jedem Abschnitt oder Schritt kopieren.
Kopieren Sie den Beispielcode in das neu erstellte
main.tf
.Kopieren Sie optional den Code aus GitHub. Dies wird empfohlen, wenn das Terraform-Snippet Teil einer End-to-End-Lösung ist.
- Prüfen und ändern Sie die Beispielparameter, die auf Ihre Umgebung angewendet werden sollen.
- Speichern Sie die Änderungen.
-
Initialisieren Sie Terraform. Dies ist nur einmal für jedes Verzeichnis erforderlich.
terraform init
Fügen Sie optional die Option
-upgrade
ein, um die neueste Google-Anbieterversion zu verwenden:terraform init -upgrade
Änderungen anwenden
-
Prüfen Sie die Konfiguration und prüfen Sie, ob die Ressourcen, die Terraform erstellen oder aktualisieren wird, Ihren Erwartungen entsprechen:
terraform plan
Korrigieren Sie die Konfiguration nach Bedarf.
-
Wenden Sie die Terraform-Konfiguration an. Führen Sie dazu den folgenden Befehl aus und geben Sie
yes
an der Eingabeaufforderung ein:terraform apply
Warten Sie, bis Terraform die Meldung „Apply complete“ anzeigt.
- Öffnen Sie Ihr Google Cloud-Projekt, um die Ergebnisse aufzurufen. Rufen Sie in der Google Cloud Console Ihre Ressourcen in der Benutzeroberfläche auf, um sicherzustellen, dass Terraform sie erstellt oder aktualisiert hat.
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
Zur Seite IAM & Verwaltung.
Klicken Sie auf
Zugriff erlauben.Das Dialogfeld Principals hinzufügen wird geöffnet.
Geben Sie im Feld Neue Hauptkonten die Dienstkonto-ID ein, die Sie zuvor kopiert haben.
Wählen Sie im Feld Rolle auswählen die Option Vertex AI und dann Vertex AI-Nutzer aus.
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 ProjektnummerMEMBER
: Die Dienstkonto-ID, die Sie zuvor kopiert haben
Modell erstellen
Öffnen Sie in der Google Cloud Console die Seite BigQuery.
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 sollMODEL_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
: der Name des zu verwendenden Modells für das Einbetten. Das muss eintext-embedding
-,text-multilingual-embedding
- odermultimodalembedding
-Modell sein. Weitere Informationen zu unterstützten Modellversionen und Aliassen finden Sie unterENDPOINT
.
Texteinbettungen mit Daten aus einer Tabelle generieren
Erstellen Sie Texteinbettungen mit der Funktion ML.GENERATE_EMBEDDING
. Verwenden Sie dazu 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 namenscontent
enthalten. Sie können auch einen Alias nutzen, um eine Spalte mit anderen Namen zu verwenden.FLATTEN_JSON
ist einBOOL
-Wert, der angibt, ob die Einbettung in eine separate Spalte geparst werden soll. Der Standardwert istTRUE
.TASK_TYPE
: EinSTRING
-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.Wenn Sie diesen Aufgabentyp verwenden, sollten Sie den Dokumenttitel in die Abfrageanweisung aufnehmen, um die Qualität des Einbettens 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 entwedertitle
heißt oder den Aliastitle
verwendet. Beispiel:SELECT * FROM ML.GENERATE_EMBEDDING( MODEL
mydataset.embedding_model
, (SELECT abstract as content, header as title, publication_number FROMmydataset.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
: einINT64
-Wert, der die Anzahl der Dimensionen angibt, die beim Generieren von Einbettungen verwendet werden sollen. Wenn Sie beispielsweise256 AS output_dimensionality
angeben, enthält die Ausgabespalteml_generate_embedding_result
für jeden Eingabewert 256 Einbettungen.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
- Ab
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 einmultimodalembedding@001
-Modell.TABLE_NAME
ist der Name der Tabelle, die den einzubettenden Text enthält. Diese Tabelle muss eine Spalte namenscontent
enthalten. Sie können auch einen Alias nutzen, um eine Spalte mit anderen Namen zu verwenden.FLATTEN_JSON
ist einBOOL
-Wert, der angibt, ob die Einbettung in eine separate Spalte geparst werden soll. Der Standardwert istTRUE
.OUTPUT_DIMENSIONALITY
: einINT64
-Wert, der die Anzahl der Dimensionen angibt, die beim Generieren von Einbettungen verwendet werden sollen. Gültige Werte sind128
,256
,512
und1408
. Der Standardwert ist1408
. Wenn Sie beispielsweise256 AS output_dimensionality
angeben, enthält die Ausgabespalteml_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 einSTRING
-Spalte mit dem Namencontent
enthält.FLATTEN_JSON
ist einBOOL
-Wert, der angibt, ob die Einbettung in eine separate Spalte geparst werden soll. Der Standardwert istTRUE
.TASK_TYPE
: EinSTRING
-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.Wenn Sie diesen Aufgabentyp verwenden, sollten Sie den Dokumenttitel in die Abfrageanweisung aufnehmen, um die Qualität des Einbettens 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 entwedertitle
heißt oder den Aliastitle
verwendet. Beispiel:SELECT * FROM ML.GENERATE_EMBEDDING( MODEL
mydataset.embedding_model
, (SELECT abstract as content, header as title, publication_number FROMmydataset.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
: einINT64
-Wert, der die Anzahl der Dimensionen angibt, die beim Generieren von Einbettungen verwendet werden sollen. Wenn Sie beispielsweise256 AS output_dimensionality
angeben, enthält die Ausgabespalteml_generate_embedding_result
für jeden Eingabewert 256 Einbettungen.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
- Ab
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 einmultimodalembedding@001
-Modell.CONTENT_QUERY
ist eine Abfrage, deren Ergebnis einSTRING
-Spalte mit dem Namencontent
enthält.FLATTEN_JSON
ist einBOOL
-Wert, der angibt, ob die Einbettung in eine separate Spalte geparst werden soll. Der Standardwert istTRUE
.OUTPUT_DIMENSIONALITY
: einINT64
-Wert, der die Anzahl der Dimensionen angibt, die beim Generieren von Einbettungen verwendet werden sollen. Gültige Werte sind128
,256
,512
und1408
. Der Standardwert ist1408
. Wenn Sie beispielsweise256 AS output_dimensionality
angeben, enthält die Ausgabespalteml_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 | +------------------------------------------+----------------------------+