Generare in blocco gli embedding di vettori per i dati di testo utilizzando la DML partizionata

Questo documento spiega come generare ed eseguire il backfill dei vector embedding in blocco per i dati testuali (STRING o JSON) archiviati in Spanner utilizzando SQL e i modelli di text embedding di Gemini Enterprise Agent Platform.

Prerequisiti

Nel tuo database Spanner deve essere presente una tabella contenente dati testuali (STRING o JSON). Per saperne di più sull'importazione dei dati, consulta la panoramica dell'importazione e dell'esportazione di Spanner.

Caso d'uso di esempio

Supponiamo di avere una tabella in Spanner con il seguente schema. Questa tabella contiene milioni di record.

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)
);

Il tuo obiettivo è generare vector embedding per la colonna description in questa tabella per trovare articoli simili da consigliare ai clienti per migliorare la loro esperienza di acquisto utilizzando la ricerca vettoriale.

Registra un modello di embedding

GoogleSQL

Registra un modello di text embedding con l'endpoint del modello Agent Platform nel tuo database Spanner:

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
)

Sostituisci quanto segue:

  • MODEL_NAME: il nome del modello di text embedding Agent Platform
  • PROJECT: il progetto che ospita l'endpoint Agent Platform
  • LOCATION: la località dell'endpoint Agent Platform

PostgreSQL

Nel dialetto PostgreSQL, non è necessario registrare il modello. Passi il nome dell'endpoint direttamente alla chiamata di funzione spanner.ML_PREDICT_ROW.

Per le best practice, tieni presente quanto segue:

  • Per mantenere l'isolamento delle quote, utilizza un endpoint in un progetto diverso da quello di produzione per generare e riempire gli embedding. Prenota l'endpoint di produzione per gestire il traffico di produzione.
  • Assicurati che l'endpoint del modello supporti il valore di default_batch_size. Puoi eseguire l'override di default_batch_size con il suggerimento per la query @{remote_udf_max_rows_per_rpc=NEW_NUMBER}. Per informazioni sul limite di default_batch_size per ogni regione, consulta Genera text embedding per uno snippet di testo.
  • Definisci l'endpoint con una versione specifica del modello (ad es. @003) anziché @latest. Questo perché i vettori di embedding generati per lo stesso testo potrebbero variare a seconda della versione del modello che utilizzi, motivo per cui è consigliabile evitare di utilizzare versioni diverse del modello per generare embedding nello stesso set di dati. Inoltre, l'aggiornamento della versione del modello nell'istruzione di definizione del modello non aggiorna gli embedding già generati con questo modello. Un modo per gestire la versione del modello per gli embedding è creare una colonna aggiuntiva nella tabella in cui viene archiviata la versione del modello.
  • I modelli di text embedding ottimizzati personalizzati non sono supportati con le funzioni GoogleSQL ML.PREDICT e PostgreSQL spanner.ML_PREDICT_ROW.

Testa l'integrazione end-to-end del modello di embedding

Puoi eseguire una query per verificare che il modello di embedding sia configurato correttamente e che gli embedding vengano recuperati. Ad esempio, esegui questa query:

GoogleSQL 

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

Sostituisci quanto segue:

  • MODEL_NAME: il nome del modello di text embedding Agent Platform

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;

Sostituisci quanto segue:

  • PROJECT: il progetto che ospita l'endpoint Agent Platform
  • LOCATION: la località dell'endpoint Agent Platform
  • MODEL_NAME: il nome del modello di text embedding Agent Platform

Aggiorna la tabella di origine per includere colonne aggiuntive in cui archiviare gli embedding

Successivamente, aggiorna lo schema della tabella di origine per aggiungere una colonna di embedding. La specifica della lunghezza del vettore è facoltativa per l'archiviazione degli embedding, consigliata per le prestazioni di ricerca KNN e obbligatoria per gli indici vettoriali. Ometti la lunghezza del vettore se la colonna memorizza vettori di dimensioni variabili:

GoogleSQL 

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

Sostituisci quanto segue:

  • TABLE_NAME: il nome della tabella di origine
  • EMBEDDING_COLUMN_NAME: il nome della colonna in cui vuoi aggiungere gli embedding generati
  • VECTOR_LENGTH: la dimensione di output del modello di embedding, ad esempio 768 o 3072

PostgreSQL 

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

Sostituisci quanto segue:

  • TABLE_NAME: il nome della tabella di origine
  • EMBEDDING_COLUMN_NAME: il nome della colonna in cui vuoi aggiungere gli embedding generati
  • VECTOR_LENGTH: la dimensione di output del modello di embedding, ad esempio 768 o 3072

Ad esempio, utilizzando l'esempio di tabella products, esegui:

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;

Puoi aggiungere un'altra colonna per gestire la versione del modello di embedding.

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT64;

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT8;

Aumenta la quota per Agent Platform

Potresti dover aumentare la quota dell'API Agent Platform per la regione che utilizza il modello di text embedding. Per richiedere un aumento, consulta Aumenti della quota di Agent Platform.

Backfill degli embedding

Infine, esegui la seguente istruzione UPDATE utilizzando il DML partizionato per generare gli embedding per la colonna di dati testuali e archiviarli nel database. Puoi archiviare la versione del modello insieme agli embedding. Ti consigliamo di eseguire questa query durante un periodo di traffico ridotto nel database.

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;

Sostituisci quanto segue:

  • TABLE_NAME: il nome della tabella con i dati testuali
  • EMBEDDING_COLUMN_NAME: il nome della colonna in cui vuoi aggiungere gli embedding generati
  • DATA_COLUMN_NAME: il nome della colonna con i dati testuali
  • MODEL_NAME: il nome del modello di embedding di Agent Platform
  • MAX_ROWS: il numero massimo di righe per RPC
  • EMBEDDING_VERSION_COLUMN: la colonna che gestisce la versione del modello di embedding utilizzato per eseguire il backfill degli embedding
  • MODEL_VERSION: la versione del modello di text embedding
  • FILTER_CONDITION: una condizione di filtro partizionabile che vuoi applicare

L'utilizzo di SAFE.ML.PREDICT restituisce NULL per le richieste non riuscite. Puoi anche utilizzare SAFE.ML.PREDICT in combinazione con un filtro WHERE embedding_column IS NULL per eseguire nuovamente la query senza calcolare gli embedding per i campi già calcolati.

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;

Sostituisci quanto segue:

  • TABLE_NAME: il nome della tabella con i dati testuali
  • EMBEDDING_COLUMN_NAME: il nome della colonna in cui vuoi aggiungere gli embedding generati
  • DATA_COLUMN_NAME: il nome della colonna con i dati di testo
  • PROJECT: il progetto che ospita l'endpoint Agent Platform
  • LOCATION: la località dell'endpoint Agent Platform
  • MODEL_NAME: il nome del modello di embedding di Agent Platform
  • MODEL_VERSION: la versione del modello di embedding di Agent Platform
  • MAX_ROWS: il numero massimo di righe per RPC
  • EMBEDDING_VERSION_COLUMN: la colonna che gestisce la versione del modello di text embedding utilizzato per il backfill degli embedding
  • FILTER_CONDITION: una condizione di filtro partizionabile che vuoi applicare

Esempio di query di backfill per la tabella 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;

Per le best practice, tieni presente quanto segue:

  • Il timeout gRPC predefinito per l'API Spanner è un'ora. A seconda della quantità di embedding di cui stai eseguendo il backfill, potrebbe essere necessario aumentare questo timeout per garantire che il DML partizionato UPDATE abbia tempo sufficiente per essere completato. Per saperne di più, consulta Configura timeout e tentativi personalizzati.

Prestazioni e altre considerazioni

Per ottimizzare le prestazioni durante il backfill dei dati di embedding, tieni presente quanto segue.

Numero di nodi

DML partizionato esegue l'istruzione DML specificata su partizioni diverse in parallelo. Per le istanze con un numero elevato di nodi, potresti osservare errori di quota durante l'esecuzione di DML partizionato. Se le richieste dell'API Agent Platform vengono limitate a causa dei limiti di quota dell'API Agent Platform, Spanner riprova questi errori in modalità di transazione DML partizionata per un massimo di 20 volte. Se osservi un tasso elevato di errori di quota in Agent Platform, aumenta la quota per Agent Platform. Puoi anche ottimizzare il parallelismo utilizzando il suggerimento a livello di istruzione @{pdml_max_parallelism=DESIRED_NUMBER} quando utilizzi GoogleSQL. L'esempio seguente imposta il parallelismo su "5":

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;

Dimensioni del testo nella colonna di dati

Il modello di embedding di Agent Platform ha limiti sul numero massimo di token per ogni input di testo. Le diverse versioni del modello hanno limiti di token diversi. Ogni richiesta di Agent Platform può avere più campi di testo di input, ma esiste un limite al numero massimo di token presenti in una singola richiesta. Per i database GoogleSQL, se riscontri un errore INVALID_ARGUMENT con il messaggio "La richiesta è troppo grande", prova a ridurre le dimensioni del batch per evitare l'errore. Per farlo, puoi configurare default_batch_size o utilizzare il suggerimento di query @{remote_udf_max_outstanding_rpcs} durante la registrazione del modello.

Numero di richieste API inviate ad Agent Platform

Puoi utilizzare il suggerimento di query @{remote_udf_max_outstanding_rpcs} per aumentare o diminuire il numero di richieste inviate ad Agent Platform da Spanner. Tieni presente che l'aumento di questo limite può aumentare l'utilizzo della CPU e della memoria utilizzata dell'istanza Spanner. Per i database GoogleSQL, l'utilizzo di questo suggerimento di query sostituisce il valore default_batch_size configurato per il modello.

Monitora l'avanzamento del backfill

Puoi monitorare il numero di richieste, la latenza e i byte di rete inviati alla piattaforma agente da Spanner utilizzando la dashboard Insight di sistema.

Passaggi successivi