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

In diesem Dokument wird beschrieben, wie Sie Vektoreinbettungen für Textdaten (STRING oder JSON), die in Spanner gespeichert sind, im Bulk generieren und füllen. Dazu verwenden Sie SQL und die Texteinbettungsmodelle der Gemini Enterprise Agent Platform.

Vorbereitung

Sie benötigen eine Tabelle in Ihrer Spanner-Datenbank, die Textdaten (STRING oder JSON) enthält. Weitere Informationen zum Importieren von Daten finden Sie in der Übersicht zum Importieren und Exportieren von Spanner.

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 ist es, Vektoreinbettungen für die Spalte description in dieser Tabelle zu generieren, um ähnliche Artikel zu finden, die Sie Kunden empfehlen können, um ihr Einkaufserlebnis mithilfe der Vektorsuche zu verbessern.

Einbettungsmodell registrieren

GoogleSQL

Registrieren Sie ein Texteinbettungsmodell mit dem Agent Platform-Modellendpunkt 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/$MODEL_NAME',
  default_batch_size = 5
)

Ersetzen Sie Folgendes:

  • MODEL_NAME: der Name des Agent Platform-Modells zur Texteinbettung
  • PROJECT: das Projekt, in dem der Agent Platform-Endpunkt gehostet wird
  • LOCATION: der Standort des Agent Platform-Endpunkts

PostgreSQL

Im PostgreSQL-Dialekt ist es nicht erforderlich, das Modell zu registrieren. Sie übergeben den Endpunktnamen direkt an den Funktionsaufruf spanner.ML_PREDICT_ROW.

Beachten Sie die folgenden Best Practices:

  • Um die Kontingente isoliert zu halten, verwenden Sie einen Endpunkt in einem anderen Projekt, um Einbettungen zu generieren und Backfills durchzuführen, als den Produktionsendpunkt. Reservieren Sie den Produktionsendpunkt für die Bereitstellung von 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 default_batch_size-Limit für die einzelnen Regionen 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 die für denselben Text generierten Einbettungsvektoren je nach verwendeter Modellversion unterschiedlich sein können. Daher sollten Sie vermeiden, verschiedene Modellversionen zum Generieren von Einbettungen im selben Dataset zu verwenden. Außerdem werden durch das Aktualisieren der Modellversion in der Modelldefinitionsanweisung nicht die Einbettungen aktualisiert, die bereits mit diesem Modell generiert wurden. 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, abgestimmte Texteinbettungsmodelle werden mit den GoogleSQL-Funktionen ML.PREDICT und den PostgreSQL-Funktionen 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 wurde 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 Agent Platform-Modells zur Texteinbettung

PostgreSQL 

SELECT spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    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 Agent Platform-Endpunkt gehostet wird
  • LOCATION: der Standort des Agent Platform-Endpunkts
  • MODEL_NAME: der Name des Agent Platform-Modells zur Texteinbettung

Quelltabelle aktualisieren, um zusätzliche Spalten zum Speichern der Einbettungen einzufügen

Aktualisieren Sie als Nächstes das Schema der Quelltabelle, um eine Einbettungsspalte hinzuzufügen. Die Angabe der Vektorlänge ist für das Speichern von Einbettungen optional, wird aber für die KNN-Suchleistung empfohlen und ist für Vektorindexe erforderlich. Lassen Sie die Vektorlänge weg, wenn in der Spalte Vektoren mit unterschiedlichen Dimensionen gespeichert werden:

GoogleSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH);

Ersetzen Sie Folgendes:

  • TABLE_NAME: der Name der Quelltabelle
  • EMBEDDING_COLUMN_NAME: der Name der Spalte, in der Sie generierte Einbettungen hinzufügen möchten
  • VECTOR_LENGTH: die Ausgabedimension des Einbettungsmodells, z. B. 768 oder 3072

PostgreSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME real[] VECTOR LENGTH VECTOR_LENGTH;

Ersetzen Sie Folgendes:

  • TABLE_NAME: der Name der Quelltabelle
  • EMBEDDING_COLUMN_NAME: der Name der Spalte, in der Sie generierte Einbettungen hinzufügen möchten
  • VECTOR_LENGTH: die Ausgabedimension des Einbettungsmodells, z. B. 768 oder 3072

Führen Sie beispielsweise mit der Tabelle products Folgendes aus:

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed ARRAY<FLOAT32>(vector_length=>768);

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed real[] VECTOR LENGTH 768;

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 die Agent Platform erhöhen

Möglicherweise müssen Sie das Agent Platform API-Kontingent für die Region erhöhen, in der das Texteinbettungsmodell verwendet wird. Informationen zum Anfordern einer Erhöhung finden Sie unter Kontingenterhöhungen für die Agent Platform.

Einbettungen per Backfill einfügen

Führen Sie schließlich 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 während eines Zeitfensters 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: der Name des Einbettungsmodells der Agent Platform
  • MAX_ROWS: die maximale Anzahl von Zeilen pro RPC
  • EMBEDDING_VERSION_COLUMN: Die Spalte, in der die Version des Einbettungsmodells verwaltet wird, das zum Backfill Ihrer Einbettungen verwendet wird.
  • MODEL_VERSION: die Version des Texteinbettungsmodells
  • FILTER_CONDITION: eine partitionierbare 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/$MODEL_NAME',
    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 Agent Platform-Endpunkt gehostet wird
  • LOCATION: der Standort des Agent Platform-Endpunkts
  • MODEL_NAME: der Name des Einbettungsmodells der Agent Platform
  • MODEL_VERSION: die Version des Einbettungsmodells der Agent Platform
  • MAX_ROWS: die maximale Anzahl von Zeilen pro RPC
  • EMBEDDING_VERSION_COLUMN: die Spalte, die die Version des Texteinbettungsmodells verwaltet, das zum 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 embedding_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/$MODEL_NAME',
    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:

  • Das standardmäßige gRPC-Zeitlimit für die Spanner API beträgt eine Stunde. Je nach Anzahl der Einbettungen, die Sie füllen, müssen Sie dieses Zeitlimit möglicherweise erhöhen, damit die partitionierte DML-Anweisung UPDATE genügend Zeit hat, um abgeschlossen zu werden. Weitere Informationen finden Sie unter Benutzerdefinierte Zeitlimits und Wiederholungsversuche konfigurieren.

Leistung und andere Überlegungen

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

Anzahl der Knoten

Partitionierte DML führt die angegebene DML-Anweisung parallel auf verschiedenen Partitionen aus. Bei Instanzen mit einer großen Anzahl von Knoten können während der Ausführung von partitionierter DML Kontingentfehler auftreten. Wenn die Agent Platform API-Anfragen aufgrund von Agent Platform API-Kontingentlimits gedrosselt werden, wiederholt Spanner diese Fehler im partitionierten DML-Transaktionsmodus maximal 20 Mal. Wenn Sie eine hohe Rate an Kontingentfehlern in der Agent Platform feststellen, erhöhen Sie das Kontingent für die Agent Platform. Sie können die Parallelität auch mit dem Hinweis @{pdml_max_parallelism=DESIRED_NUMBER} auf Anweisungsebene optimieren, wenn Sie GoogleSQL verwenden. 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 embedding_model, (
        SELECT products.value AS CONTENT
        )
  )
      @{remote_udf_max_rows_per_rpc=200}
),
products.desc_embed_model_version = MODEL_VERSION
WHERE products.desc_embed IS NULL;

Größe des Texts in der Datenspalte

Für das Einbettungsmodell der Agent Platform gilt eine maximale Anzahl von Tokens pro Texteingabe. Verschiedene Modellversionen haben unterschiedliche Tokenlimits. Jede Agent Platform-Anfrage kann mehrere Eingabetextfelder enthalten. Es gibt jedoch ein Limit für die maximale Anzahl von Tokens, die in einer einzelnen Anfrage enthalten sein können. 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 den Abfragehinweis @{remote_udf_max_outstanding_rpcs} verwenden, wenn Sie das Modell registrieren.

Anzahl der an die Agent Platform gesendeten API-Anfragen

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

Backfill-Fortschritt überwachen

Sie können die Anzahl der Anfragen, die Latenz und die Netzwerkbytes, die von Cloud Spanner an die Agent Platform gesendet werden, über das System Insights-Dashboard überwachen.

Nächste Schritte