Mit partitionierter DML Vektoreinbettungen für Textdaten im Bulk generieren

In diesem Dokument wird erläutert, wie Sie für Textdaten (STRING oder JSON), die in Spanner mit SQL und dem Vertex AI-Modell textembedding-gecko gespeichert werden, im Bulk Vektoreinbettungen generieren und Backfill-Vorgänge ausführen.

Vorbereitung

Die Spanner-Datenbank muss eine Tabelle mit Textdaten enthalten (STRING oder JSON). Weitere Informationen zum Importieren von Daten finden Sie in der Übersicht zum Spanner-Import und -Export.

Anwendungsbeispiel

Angenommen, Sie haben in Spanner eine Tabelle 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 ist es, Vektoreinbettungen für die Spalte description in dieser Tabelle zu generieren, um mit der Vektorsuche ähnliche Artikel zu finden und Kunden zur Verbesserung des Einkaufserlebnisses zu empfehlen.

Einbettungsmodell registrieren

GoogleSQL

Registrieren Sie ein Einbettungsmodell mit dem Vertex AI-Endpunkt textembedding-gecko 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, das den Vertex AI-Endpunkt hostet
  • LOCATION: der Standort des Vertex AI-Endpunkts
  • MODEL_VERSION: die Version des Einbettungsmodells textembedding-gecko

PostgreSQL

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

Berücksichtigen Sie dabei folgende Best Practices:

  • Verwenden Sie zum Generieren und Backfill von Einbettungen einen Endpunkt in einem anderen Projekt als der Produktionsendpunkt, um die Kontingente isoliert zu halten. Reservieren Sie den Produktionsendpunkt für den Produktionstraffic.
  • Achten Sie darauf, dass der Modellendpunkt den Wert von default_batch_size unterstützt. Sie können default_batch_size mit dem Abfragehinweis @{remote_udf_max_rows_per_rpc=NEW_NUMBER} überschreiben. Informationen zum Limit default_batch_size 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 ein und denselben Textelement generierten Einbettungsvektoren je nach Version des verwendeten Modells unterscheiden können. Deshalb sollten Sie es vermeiden, Einbettungen in einem Datensatz mit unterschiedlichen Modellversionen zu generieren. Außerdem werden durch das Aktualisieren der Modellversion in der Modelldefinitionsanweisung die bereits mit diesem Modell generierten Einbettungen nicht aktualisiert. Eine Möglichkeit, die Modellversion für Einbettungen zu verwalten, besteht darin, eine zusätzliche Spalte in der Tabelle zu erstellen, in der die Modellversion gespeichert wird.
  • Benutzerdefinierte angepasste textembedding-gecko-Modelle werden von der GoogleSQL-Funktion ML.PREDICT und der PostgreSQL-Funktion spanner.ML_PREDICT_ROW nicht unterstützt.

End-to-End-Integration des Einbettungsmodells testen

Sie können eine Abfrage ausführen, um zu testen, ob das Einbettungsmodell erfolgreich 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: der 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, das den Vertex AI-Endpunkt hostet
  • LOCATION: der Standort des Vertex AI-Endpunkts
  • MODEL_VERSION: die Version des Einbettungsmodells textembedding-gecko

Quelltabelle mit zusätzlichen Spalten zum Speichern der Einbettungen aktualisieren

Als Nächstes aktualisieren Sie das Schema der Quelltabelle, um eine zusätzliche Spalte des Datentyps 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: der Name der Quelltabelle
  • EMBEDDING_COLUMN_NAME: der Name der Spalte, in die Sie generierte Einbettungen einfügen möchten

PostgreSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME real[];

Ersetzen Sie Folgendes:

  • TABLE_NAME: der Name der Quelltabelle
  • EMBEDDING_COLUMN_NAME: der Name der Spalte, in die Sie generierte Einbettungen einfügen möchten

Führen Sie beispielsweise mit dem Tabellenbeispiel products folgenden Befehl 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 unter Kontingenterhöhungen für Vertex AI.

Weitere Informationen finden Sie unter Kontingente und Limits für Vertex AI.

Backfill-Einbettungen

Führen Sie abschließend die folgende UPDATE-Anweisung mit partitionierter DML aus, um Einbettungen für die Textdatenspalte zu generieren und die Einbettungen in Ihrer Datenbank zu speichern. Sie können die Modellversion zusammen mit den Einbettungen speichern. Wir empfehlen, diese Abfrage in einem Fenster 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 die Sie generierte Einbettungen einfügen möchten
  • DATA_COLUMN_NAME: der Name der Spalte mit den Textdaten
  • MODEL_NAME: der Name des Einbettungsmodells
  • MAX_ROWS: die maximale Anzahl von Zeilen pro RPC
  • EMBEDDING_VERSION_COLUMN: die Spalte, die die Version des Einbettungsmodells textembedding-gecko verwaltet, das für den Backfill Ihrer Einbettungen verwendet wird
  • MODEL_VERSION: die Version des Einbettungsmodells textembedding-gecko
  • FILTER_CONDITION: eine partitionierbare Filterbedingung, die Sie anwenden möchten

Bei Verwendung von SAFE.ML.PREDICT wird NULL für fehlgeschlagene Anfragen 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 die Sie generierte Einbettungen einfügen möchten
  • DATA_COLUMN_NAME: der Name der Spalte mit den Textdaten
  • PROJECT: das Projekt, das den Vertex AI-Endpunkt hostet
  • LOCATION: der Standort des Vertex AI-Endpunkts
  • MODEL_VERSION: die Version des Einbettungsmodells textembedding-gecko
  • MAX_ROWS: die maximale Anzahl von Zeilen pro RPC
  • EMBEDDING_VERSION_COLUMN: die Spalte, die die Version des Einbettungsmodells textembedding-gecko verwaltet, das für den Backfill Ihrer Einbettungen verwendet wird
  • FILTER_CONDITION: eine partitionierbare 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;

Berücksichtigen Sie dabei folgende Best Practices:

  • Das standardmäßige gRPC-Zeitlimit für die Spanner API beträgt eine Stunde. Je nach Anzahl der Einbettungen, für die ein Backfill ausgeführt wird, müssen Sie dieses Zeitlimit möglicherweise erhöhen, damit die nach UPDATE partitionierte DML genügend Zeit zum Ausführen hat. Weitere Informationen finden Sie unter Benutzerdefinierte Zeitlimits und Wiederholungsversuche konfigurieren.

Leistung und andere Aspekte

Beachten Sie Folgendes, um die Leistung beim Backfill von Einbettungsdaten zu optimieren.

Anzahl von Knoten

Partitionierte DML führt die angegebene DML-Anweisung für verschiedene Partitionen parallel aus. Bei Instanzen mit einer hohen Anzahl von Knoten können während der Ausführung von partitionierter DML Kontingentfehler auftreten. Wenn die Vertex AI API-Anfragen aufgrund von Kontingentlimits der Vertex AI API gedrosselt werden, wiederholt Spanner diese Fehler im partitionierten DML-Transaktionsmodus maximal 20-mal. Wenn in Vertex AI eine hohe Rate von Kontingentfehlern auftritt, erhöhen Sie das Kontingent für Vertex AI. Sie können die Parallelität auch mit dem Hinweis @{pdml_max_parallelism=DESIRED_NUMBER} auf Anweisungsebene abstimmen, wenn Sie Google SQL verwenden. Im folgenden Beispiel wird die Parallelität auf "5" gesetzt:

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;

Größe des Textes in der Datenspalte

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

Anzahl der an Vertex AI gesendeten API-Anfragen

Sie können den Abfragehinweis @{remote_udf_max_outstanding_rpcs} verwenden, um die Anzahl der von Spanner an Vertex AI gesendeten Anfragen zu erhöhen oder zu verringern. Beachten Sie, dass eine Erhöhung dieses Limits die CPU- und Arbeitsspeichernutzung der Spanner-Instanz erhöhen kann. Bei GoogleSQL-Datenbanken überschreibt dieser Abfragehinweis den für Ihr Modell konfigurierten default_batch_size.

Backfill-Fortschritt überwachen

Mit dem Dashboard für Systemstatistiken können Sie die Anzahl der Anfragen, Latenz und Netzwerkbyte, die von Spanner an Vertex AI gesendet wurden, überwachen.

Nächste Schritte