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 degli incorporamenti vettoriali collettivamente per i dati testuali (STRING o JSON) archiviati in Spanner utilizzando SQL e i modelli di incorporamento di testo di Vertex AI.

Prerequisiti

Devi avere una tabella nel database Spanner che contenga 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 incorporamenti vettoriali per la colonna description di 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 incorporamento di testo con l'endpoint del modello Vertex AI 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 Vertex AI
  • PROJECT: il progetto che ospita l'endpoint Vertex AI
  • LOCATION: la posizione dell'endpoint Vertex AI

PostgreSQL

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

Per le best practice, considera quanto segue:

  • Per mantenere l'isolamento delle quote, utilizza un endpoint in un progetto diverso per generare e riempire gli incorporamenti rispetto all'endpoint di produzione. Riserva 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, vedi Ottenere incorporamenti di testo per un frammento 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 differire a seconda della versione del modello utilizzata. Per questo motivo, è 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 incorporamenti già generati con questo modello. Un modo per gestire la versione del modello per gli incorporamenti è creare una colonna aggiuntiva nella tabella che memorizza la versione del modello.
  • I modelli di incorporamento di testo personalizzati non sono supportati con le funzioni GoogleSQL ML.PREDICT e PostgreSQL spanner.ML_PREDICT_ROW.

Testare l'integrazione end-to-end del modello di incorporamento

Puoi eseguire una query per verificare che il modello di incorporamento sia configurato correttamente e che gli incorporamenti vengano recuperati. Ad esempio, esegui la seguente 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 Vertex AI

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 Vertex AI
  • LOCATION: la posizione dell'endpoint Vertex AI
  • MODEL_NAME: il nome del modello di text embedding Vertex AI

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

Successivamente, aggiorna lo schema della tabella di origine in modo da includere una colonna aggiuntiva del tipo di dati ARRAY<FLOAT32> per archiviare gli incorporamenti generati:

GoogleSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME ARRAY<FLOAT32>;

Sostituisci quanto segue:

  • TABLE_NAME: il nome della tabella di origine
  • EMBEDDING_COLUMN_NAME: il nome della colonna in cui vuoi aggiungere gli incorporamenti generati

PostgreSQL 

ALTER TABLE TABLE_NAME
ADD COLUMN EMBEDDING_COLUMN_NAME real[];

Sostituisci quanto segue:

  • TABLE_NAME: il nome della tabella di origine
  • EMBEDDING_COLUMN_NAME: il nome della colonna in cui vuoi aggiungere gli incorporamenti generati

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

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed ARRAY<FLOAT32>;

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed real[];

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

GoogleSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT64;

PostgreSQL 

ALTER TABLE Products
ADD COLUMN desc_embed_model_version INT8;

Aumentare la quota per Vertex AI

Potresti dover aumentare la quota dell'API Vertex AI per la regione che utilizza il modello di text embedding. Per richiedere un aumento, vedi Aumenti di quota di Vertex AI .

Per ulteriori informazioni, consulta Quote e limiti di Vertex AI.

Incorporamenti backfill

Infine, esegui la seguente istruzione UPDATE utilizzando DML partizionate per generare incorporamenti per la colonna di dati testuali e archiviarli nel database. Puoi memorizzare la versione del modello insieme agli incorporamenti. Ti consigliamo di eseguire questa query durante un periodo di traffico ridotto nel tuo 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 incorporamenti generati
  • DATA_COLUMN_NAME: il nome della colonna con i dati testuali
  • MODEL_NAME: il nome del modello di embedding Vertex AI
  • MAX_ROWS: il numero massimo di righe per RPC
  • EMBEDDING_VERSION_COLUMN: la colonna che gestisce la versione del modello di incorporamento utilizzato per il backfill degli incorporamenti
  • MODEL_VERSION: la versione del modello di incorporamento di testo
  • 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 incorporamenti 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 incorporamenti generati
  • DATA_COLUMN_NAME: il nome della colonna con i dati testuali
  • PROJECT: il progetto che ospita l'endpoint Vertex AI
  • LOCATION: la posizione dell'endpoint Vertex AI
  • MODEL_NAME: il nome del modello di embedding Vertex AI
  • MODEL_VERSION: la versione del modello di embedding Vertex AI
  • MAX_ROWS: il numero massimo di righe per RPC
  • EMBEDDING_VERSION_COLUMN: la colonna che gestisce la versione del modello di incorporamento di testo utilizzato per il backfill degli incorporamenti
  • FILTER_CONDITION: una condizione di filtro partizionabile che vuoi applicare

Un 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, considera quanto segue:

  • Il timeout gRPC predefinito per l'API Spanner è di un'ora. A seconda della quantità di incorporamenti che stai eseguendo il backfill, potresti dover aumentare questo timeout per assicurarti che il DML partizionato UPDATE abbia tempo sufficiente per essere completato. Per ulteriori informazioni, vedi Configurare timeout e tentativi personalizzati.

Rendimento e altre considerazioni

Per ottimizzare il rendimento durante il riempimento dei dati di incorporamento, 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 riscontrare errori di quota durante l'esecuzione di DML partizionato. Se le richieste API Vertex AI vengono limitate a causa dei limiti di quota dell'API Vertex AI, Spanner riprova questi errori in modalità transazione DML partizionata per un massimo di 20 volte. Se osservi un tasso elevato di errori di quota in Vertex AI, aumenta la quota per Vertex AI. Puoi anche ottimizzare il parallelismo utilizzando l'hint 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 Vertex AI ha limiti al numero massimo di token per ogni input di testo. Le diverse versioni del modello hanno limiti di token differenti. Ogni richiesta Vertex AI 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 si verifica un errore INVALID_ARGUMENT con il messaggio "La richiesta è troppo grande", prova a ridurre le dimensioni del batch per evitare l'errore. A questo scopo, puoi configurare default_batch_size o utilizzare il suggerimento per la query @{remote_udf_max_outstanding_rpcs} durante la registrazione del modello.

Numero di richieste API inviate a Vertex AI

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

Monitorare l'avanzamento del backfill

Puoi monitorare il numero di richieste, la latenza e i byte di rete inviati a Vertex AI da Spanner utilizzando la dashboard degli approfondimenti di sistema.

Passaggi successivi