Mithilfe von partitionierter DML Bulk-Vektoreinbettungen für Textdaten generieren

In diesem Dokument wird beschrieben, wie Sie Vektor-Embeddings im Bulk-Verfahren für Textdaten (STRING oder JSON) generieren und mithilfe von SQL und dem Vertex AI-textembedding-gecko-Modell in Spanner zurückfüllen.

Vorbereitung

In Ihrer Spanner-Datenbank muss eine Tabelle mit Textdaten (STRING oder JSON) vorhanden sein. Weitere Informationen zum Importieren von Daten finden Sie unter Spanner-Import- und ‑Export – Übersicht.

Anwendungsbeispiel

Angenommen, Sie haben eine Tabelle in Spanner mit dem folgenden Schema. Diese Tabelle enthält Millionen von Datensätzen.

GoogleSQL 

CREATE TABLE Products (
  product_id INT64 NOT NULL,
  name STRING(MAX),
  description STRING(MAX)
) PRIMARY KEY(product_id);

PostgreSQL 

CREATE TABLE Products (
  product_id INT8 NOT NULL,
  name TEXT,
  description TEXT,
  PRIMARY KEY(product_id)
);

Ihr Ziel besteht darin, Vektoreinbettungen für die Spalte description in dieser Tabelle zu generieren, um ähnliche Artikel zu finden, die Sie Kunden empfehlen können, um die Nutzerfreundlichkeit mithilfe der Vektorsuche zu verbessern.

Einbettungsmodell registrieren

GoogleSQL

Registrieren Sie ein Einbettungsmodell mit dem Vertex AI-textembedding-gecko-Endpunkt in Ihrer Spanner-Datenbank:

CREATE MODEL MODEL_NAME
INPUT(
  content STRING(MAX)
)
OUTPUT(
  embeddings STRUCT<values ARRAY<FLOAT32>>
)
REMOTE OPTIONS(
    endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/textembedding-gecko$MODEL_VERSION',
  default_batch_size = 5
)

Ersetzen Sie Folgendes:

  • MODEL_NAME: der Name des Einbettungsmodells
  • PROJECT: das Projekt, in dem der Vertex AI-Endpunkt gehostet wird
  • LOCATION: den Standort des Vertex AI-Endpunkts
  • MODEL_VERSION: die Version des textembedding-gecko-Embedding-Modells

PostgreSQL

Im PostgreSQL-Dialekt muss das Modell nicht registriert werden. Sie übergeben den Endpunktnamen direkt an den spanner.ML_PREDICT_ROW-Funktionsaufruf.

Beachten Sie die folgenden Best Practices:

  • Verwenden Sie zum Isolieren von Kontingenten einen anderen Endpunkt in einem anderen Projekt, um Einbettungen zu generieren und zu ergänzen als den Produktionsendpunkt. Reserviere den Produktionsendpunkt, um Produktionstraffic zu verarbeiten.
  • Der Modellendpunkt muss den Wert von default_batch_size unterstützen. Sie können default_batch_size mit dem Abfragehinweis @{remote_udf_max_rows_per_rpc=NEW_NUMBER} überschreiben. Informationen zum default_batch_size-Limit für jede Region finden Sie unter Texteinbettungen für ein Text-Snippet abrufen.
  • Definieren Sie den Endpunkt mit einer bestimmten Modellversion (z.B. @003) anstelle von @latest. Das liegt daran, dass sich die für denselben Text generierten Einbettungsvektoren je nach verwendeter Modellversion unterscheiden können. Daher sollten Sie vermeiden, unterschiedliche Modellversionen zum Generieren von Einbettungen im selben Dataset zu verwenden. Außerdem werden durch das Aktualisieren der Modellversion in der Modelldefinitionsanweisung nicht die bereits mit diesem Modell generierten Einbettungen aktualisiert. Eine Möglichkeit, die Modellversion für Einbettungen zu verwalten, besteht darin, in der Tabelle eine zusätzliche Spalte zu erstellen, in der die Modellversion gespeichert wird.
  • Benutzerdefiniert abgestimmte textembedding-gecko-Modelle werden von den GoogleSQL-Funktionen ML.PREDICT und PostgreSQL spanner.ML_PREDICT_ROW nicht unterstützt.

End-to-End-Integration des Einbettungsmodells testen

Sie können eine Abfrage ausführen, um zu prüfen, ob das Einbettungsmodell richtig konfiguriert ist und Einbettungen abgerufen werden. Führen Sie beispielsweise die folgende Abfrage aus:

GoogleSQL 

SELECT embeddings.values
FROM SAFE.ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT description AS content FROM products LIMIT 10)
);

Ersetzen Sie Folgendes:

  • MODEL_NAME: Name des Einbettungsmodells

PostgreSQL 

SELECT spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/textembedding-gecko$MODEL_VERSION',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description))))
FROM Products
LIMIT 10;

Ersetzen Sie Folgendes:

  • PROJECT: das Projekt, in dem der Vertex AI-Endpunkt gehostet wird
  • LOCATION: den Standort des Vertex AI-Endpunkts
  • MODEL_VERSION: die Version des textembedding-gecko-Embedding-Modells

Aktualisieren Sie die Quelltabelle, um zusätzliche Spalten zum Speichern der Einbettungen hinzuzufügen.

Aktualisieren Sie als Nächstes das Schema der Quelltabelle, um eine zusätzliche Spalte vom Datentyp ARRAY<FLOAT32> zum Speichern der generierten Einbettungen hinzuzufügen:

GoogleSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME ARRAY<FLOAT32>;

Ersetzen Sie Folgendes:

  • TABLE_NAME: Name der Quelltabelle
  • EMBEDDING_COLUMN_NAME: Der Name der Spalte, in der Sie generierte Einbettungen hinzufügen möchten.

PostgreSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME real[];

Ersetzen Sie Folgendes:

  • TABLE_NAME: Name der Quelltabelle
  • EMBEDDING_COLUMN_NAME: Der Name der Spalte, in der Sie generierte Einbettungen hinzufügen möchten.

Führen Sie beispielsweise für die Tabelle products Folgendes aus:

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed ARRAY<FLOAT32>;

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed real[];

Sie können eine weitere Spalte hinzufügen, um die Version des Einbettungsmodells zu verwalten.

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT64;

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT8;

Kontingent für Vertex AI erhöhen

Möglicherweise müssen Sie das Vertex AI API-Kontingent für textembedding-gecko in der Region erhöhen, in der das Modell verwendet wird. Informationen zum Anfordern einer Erhöhung finden Sie Vertex AI Kontingenterhöhungen.

Weitere Informationen finden Sie unter Vertex AI-Kontingente und ‑Limits.

Backfill-Einbettungen

Führen Sie abschließend die folgende UPDATE-Anweisung mit partitionierter DML aus, um Einbettungen für die Spalte mit Textdaten zu generieren und in Ihrer Datenbank zu speichern. Sie können die Modellversion zusammen mit den Einbettungen speichern. Wir empfehlen, diese Abfrage während eines Zeitraums mit geringem Traffic in Ihrer Datenbank auszuführen.

GoogleSQL 

UPDATE TABLE_NAME
SET 
  TABLE_NAME.EMBEDDING_COLUMN_NAME = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL MODEL_NAME,
      (SELECT TABLE_NAME.DATA_COLUMN_NAME AS content)
    ) @{remote_udf_max_rows_per_rpc=MAX_ROWS}
  ),
  TABLE_NAME.EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

Ersetzen Sie Folgendes:

  • TABLE_NAME: der Name der Tabelle mit den Textdaten
  • EMBEDDING_COLUMN_NAME: der Name der Spalte, in der Sie generierte Einbettungen hinzufügen möchten
  • DATA_COLUMN_NAME: der Name der Spalte mit den Textdaten
  • MODEL_NAME: Name des Einbettungsmodells
  • MAX_ROWS: die maximale Anzahl von Zeilen pro RPC
  • EMBEDDING_VERSION_COLUMN: die Spalte, in der die Version des textembedding-gecko-Embedding-Modells verwaltet wird, das zum Backfillen Ihrer Einbettungen verwendet wird
  • MODEL_VERSION: die Version des textembedding-gecko-Embedding-Modells
  • FILTER_CONDITION: eine partitionsfähige Filterbedingung, die Sie anwenden möchten

Wenn Sie SAFE.ML.PREDICT verwenden, wird für fehlgeschlagene Anfragen NULL zurückgegeben. Sie können SAFE.ML.PREDICT auch in Kombination mit einem WHERE embedding_column IS NULL-Filter verwenden, um die Abfrage noch einmal auszuführen, ohne die Einbettungen für die bereits berechneten Felder zu berechnen.

PostgreSQL 

UPDATE TABLE_NAME
SET 
  EMBEDDING_COLUMN_NAME = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/textembedding-gecko$MODEL_VERSION', 
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', DATA_COLUMN_NAME)))
  ) /*@ remote_udf_max_rows_per_rpc=MAX_ROWS */ ->'predictions'->0->'embeddings'->'values'),
  EMBEDDING_VERSION_COLUMN = MODEL_VERSION
WHERE FILTER_CONDITION;

Ersetzen Sie Folgendes:

  • TABLE_NAME: der Name der Tabelle mit den Textdaten
  • EMBEDDING_COLUMN_NAME: der Name der Spalte, in der Sie generierte Einbettungen hinzufügen möchten
  • DATA_COLUMN_NAME: der Name der Spalte mit den Textdaten
  • PROJECT: das Projekt, in dem der Vertex AI-Endpunkt gehostet wird
  • LOCATION: den Standort des Vertex AI-Endpunkts
  • MODEL_VERSION: die Version des textembedding-gecko-Embedding-Modells
  • MAX_ROWS: die maximale Anzahl von Zeilen pro RPC
  • EMBEDDING_VERSION_COLUMN: die Spalte, in der die Version des textembedding-gecko-Embedding-Modells verwaltet wird, das zum Backfill Ihrer Einbettungen verwendet wird
  • FILTER_CONDITION: eine partitionsfähige Filterbedingung, die Sie anwenden möchten

Beispiel für eine Backfill-Abfrage für die Tabelle products:

GoogleSQL 

UPDATE products
SET
  products.desc_embed = (
    SELECT embeddings.values
    FROM SAFE.ML.PREDICT(
      MODEL gecko_model,
      (SELECT products.description AS content)
    ) @{remote_udf_max_rows_per_rpc=200}
  ),
  products.desc_embed_model_version = 3
WHERE products.desc_embed IS NULL;

PostgreSQL 

UPDATE products
SET
  desc_embed = spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/textembedding-gecko@003', 
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description)))
  ) /*@ remote_udf_max_rows_per_rpc=200 */ ->'predictions'->0->'embeddings'->'values'),
  desc_embed_model_version = 3
WHERE desc_embed IS NULL;

Beachten Sie die folgenden Best Practices:

  • Die Standard-gRPC-Zeitüberschreitung für die Spanner API beträgt eine Stunde. Je nach Anzahl der Einbettungen, die Sie backfillen, müssen Sie diese Zeitüberschreitung möglicherweise verlängern, damit die partitionierte DML-Anweisung UPDATE genügend Zeit hat, um abgeschlossen zu werden. Weitere Informationen finden Sie unter Benutzerdefinierte Zeitüberschreitungen und Wiederholungsversuche konfigurieren.

Leistung und weitere Aspekte

Beachten Sie die folgenden Hinweise, um die Leistung beim Backfilling von Daten für das Einbetten zu optimieren.

Anzahl von Knoten

Bei der partitionierten DML wird die angegebene DML-Anweisung parallel auf verschiedenen Partitionen ausgeführt. Bei Instanzen mit einer großen Anzahl von Knoten können bei der Ausführung von partitionierter DML möglicherweise Kontingentfehler auftreten. Wenn die Vertex AI API-Anfragen aufgrund von Kontingentlimits der Vertex AI API gedrosselt werden, versucht Spanner, diese Fehler maximal 20 Mal im Partitionierungsmodus für DML-Transaktionen noch einmal auszuführen. Wenn Sie in Vertex AI häufig Kontingentfehler feststellen, erhöhen Sie das Kontingent für Vertex AI. Mit GoogleSQL können Sie die Parallelität auch mit dem Hinweis @{pdml_max_parallelism=DESIRED_NUMBER} auf Anweisungsebene optimieren. Im folgenden Beispiel wird die Parallelität auf „5“ festgelegt:

GoogleSQL 

@{pdml_max_parallelism=5} UPDATE products
SET products.desc_embed =(
  SELECT embeddings.values
  FROM SAFE.ML.PREDICT(MODEL gecko_model, (
        SELECT products.value AS CONTENT
        )
  )
      @{remote_udf_max_rows_per_rpc=200}
),
products.desc_embed_model_version = 003
WHERE products.desc_embed IS NULL;

Textgröße in der Datenspalte

Das Vertex AI-Embedding-Modell hat Limits für die maximale Anzahl von Tokens für jede Texteingabe. Für unterschiedliche Modellversionen gelten unterschiedliche Tokenlimits. Jede Vertex AI-Anfrage kann mehrere Eingabetextfelder haben. Die maximale Anzahl von Tokens in einer einzelnen Anfrage ist jedoch begrenzt. Wenn bei GoogleSQL-Datenbanken der Fehler INVALID_ARGUMENT mit der Meldung „Anfrage ist zu groß“ auftritt, reduzieren Sie die Batchgröße, um den Fehler zu vermeiden. Dazu können Sie default_batch_size konfigurieren oder den Abfragehinweis @{remote_udf_max_outstanding_rpcs} bei der Registrierung des Modells verwenden.

Anzahl der an Vertex AI gesendeten API-Anfragen

Mit dem Abfragehinweis @{remote_udf_max_outstanding_rpcs} können Sie die Anzahl der Anfragen erhöhen oder verringern, die von Spanner an Vertex AI gesendet werden. Beachten Sie, dass sich durch eine Erhöhung dieses Limits die CPU- und Arbeitsspeichernutzung der Spanner-Instanz erhöhen kann. Bei GoogleSQL-Datenbanken wird durch die Verwendung dieses Abfragehinweises die für Ihr Modell konfigurierte default_batch_size überschrieben.

Fortschritt des Backfills im Blick behalten

Im Dashboard für Systeminformationen können Sie die Anzahl der Anfragen, die Latenz und die Netzwerk-Byte überwachen, die von Spanner an Vertex AI gesendet werden.

Nächste Schritte