Migliorare le prestazioni delle query con le funzioni AI

Il batching smart per le funzioni AI ti consente di ottimizzare le prestazioni quando esegui query che utilizzano funzioni AI in AlloyDB per PostgreSQL. Offre prestazioni uguali o migliori rispetto alle funzioni basate su array, senza richiedere la riscrittura delle query in strutture di array complesse. Per saperne di più sulle funzioni AI, consulta Panoramica delle funzioni AI.

In PostgreSQL standard, la valutazione di una funzione AI riga per riga comporta una latenza di rete su ogni singola riga. Con il batching intelligente in AlloyDB, le operazioni di AI idonee vengono raggruppate automaticamente in batch e scaricate per la valutazione asincrona, consentendoti di scrivere query SQL standard e di facile lettura. I filtri relazionali standard vengono valutati prima delle funzioni AI, garantendo prestazioni e utilizzo del modello ottimali.

Funzioni AI supportate

Il batching smart di AlloyDB supporta le seguenti funzioni AI, disponibili sia nello schema ai che nello schema google_ml:

Funzione Descrizione Versione estensione
ai.if(prompt text, ...)/google_ml.if(...) Valuta un prompt booleano in linguaggio naturale, restituendo true o false. Supportato per proiezioni SELECT, filtri WHERE e clausole JOIN. Tutti
ai.rank(prompt text, ...)/google_ml.rank(...) Calcola un punteggio di pertinenza numerico (float) che indica il grado di corrispondenza di un input con i criteri specificati. Supportato nei filtri WHERE e nelle clausole ORDER BY, SELECT e JOIN. Tutti
ai.generate(prompt text, ...)/google_ml.generate(...) Genera risposte in linguaggio naturale o testo strutturato utilizzando i foundation model. Supportato per proiezioni SELECT, filtri WHERE e clausole JOIN. Tutti
ai.analyze_sentiment(input text, ...)/google_ml.analyze_sentiment(...) Analizza il sentiment del testo di input e restituisce 'positive', 'negative' o 'neutral'. Supportato per proiezioni SELECT, filtri WHERE e clausole JOIN. 1.6.3
ai.summarize(input text, ...)/google_ml.summarize(...) Riassume il testo di input. Supportato per proiezioni SELECT, filtri WHERE e clausole JOIN. 1.6.4
ai.extract(input text, output_schema text, ...)/google_ml.extract(...)

(in Anteprima; richiede l'impostazione google_ml_integration.enable_preview_ai_functions=on)
Estrae entità strutturate o attributi coppia chiave-valore dal testo. Supportato per proiezioni SELECT, filtri WHERE e clausole JOIN. 1.6.1
ai.classify(input text, categories text[][], ...)/google_ml.classify(...)

(in Anteprima; richiede l'impostazione google_ml_integration.enable_preview_ai_functions=on)
Classifica il testo in etichette di categorie specificate. Supportato per proiezioni SELECT, filtri WHERE e clausole JOIN. 1.6.1

Per ulteriori informazioni sulla sintassi e sui parametri delle funzioni AI, consulta il riferimento per la gestione degli endpoint del modello.

Clausole supportate

L'accelerazione delle funzioni AI funziona con le principali clausole SQL, singolarmente o in combinazione:

  • Clausole WHERE: filtrano le righe utilizzando valutazioni booleane dell'AI (ai.if) dopo aver valutato i predicati relazionali selettivi non AI.
  • Clausole ORDER BY: calcola i punteggi di pertinenza AI (ai.rank) in batch prima di eseguire operazioni di ordinamento o limitazione.
  • Proiezioni SELECT: raggruppa in batch le funzioni AI scalari (ai.if, ai.rank, ai.generate, ai.analyze_sentiment, ai.summarize, ai.extract e ai.classify) tra le righe dei risultati.
  • Condizioni JOIN ... ON: valuta le condizioni AI tra tabelle nelle operazioni INNER JOIN utilizzando il batching intelligente.
  • Istruzioni DML: accelera le funzioni AI nei predicati WHERE, negli elenchi di destinazione e nelle espressioni SET nelle operazioni UPDATE, DELETE e INSERT ... SELECT, come INSERT INTO ... SELECT ai.generate(...) e UPDATE ... SET col = ai.generate(...).

Espressioni di argomenti supportate

Gli argomenti dei prompt supportano le espressioni SQL standard, tra cui:

  • Riferimenti alle colonne, ad esempio r.review
  • Valori letterali stringa concatenati con riferimenti alle colonne, ad esempio 'Is this a positive review? Review: ' || r.review
  • Concatenazione di più colonne, ad esempio r.name || ' ' || r.review
  • Espressioni e funzioni SQL scalari, come le istruzioni COALESCE(r.review, ''), LOWER(r.comments), SUBSTRING(description FROM 1 FOR 500) e CASE

Prima di iniziare

Per utilizzare il batching smart per le funzioni AI in AlloyDB, assicurati che siano soddisfatti i seguenti prerequisiti:

  1. Versione PostgreSQL: utilizza PostgreSQL versione 17 o successive.
  2. Integra con Gemini Enterprise Agent Platform: completa i passaggi descritti in Integra con Gemini Enterprise Agent Platform.
  3. Disponibilità a livello di regione: il batching smart è disponibile nelle regioni che supportano il modello predefinito (gemini-3.5-flash-lite) o il modello configurato utilizzando google_ml_integration.default_llm_model. Per saperne di più, consulta Regioni supportate.

Attiva l'elaborazione in batch intelligente per le funzioni AI

In PostgreSQL 18 o versioni successive, il batching smart per le funzioni AI è abilitato per impostazione predefinita. In PostgreSQL 17, è disabilitata per impostazione predefinita e deve essere abilitata esplicitamente. Puoi configurare il suo comportamento a livello globale tramite i flag di database a livello di istanza o per sessione utilizzando i comandi SQL SET.

Parametri di configurazione

Nome parametro Tipo Predefinito Ambito Descrizione
google_ml_integration.enable_ai_function_acceleration Booleano PostgreSQL 18: on
PostgreSQL 17: off
Sessione, utente o istanza Controlla se l'utilità di pianificazione e l'esecutore del piano di query eseguono il trasferimento delle operazioni AI idonee per il raggruppamento intelligente. Se impostato su off, le query vengono eseguite utilizzando l'esecuzione riga per riga standard di PostgreSQL.

Impostazioni aggiuntive

  • Funzioni di anteprima: per attivare lo smart batching per le funzioni AI in anteprima come ai.extract e ai.classify, imposta google_ml_integration.enable_preview_ai_functions su on.
  • Selezione del modello: per specificare un modello diverso da quello predefinito gemini-3.5-flash-lite, imposta google_ml_integration.default_llm_model sull'ID del modello di destinazione o passa il parametro model_id nella funzione AI.

Configura a livello di istanza

Per configurare i flag di database a livello di istanza nel tuo cluster AlloyDB, utilizza il comando gcloud alloydb instances update:

gcloud alloydb instances update INSTANCE_ID \
  --database-flags google_ml_integration.enable_ai_function_acceleration=on \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --project=PROJECT_ID

Sostituisci quanto segue:

  • INSTANCE_ID: l'ID dell'istanza che vuoi aggiornare.
  • REGION_ID: l'ID della regione in cui si trova il cluster. Per ulteriori informazioni, consulta Regioni supportate.
  • CLUSTER_ID: l'ID del cluster.
  • PROJECT_ID: l'ID del progetto

Per saperne di più, consulta Configura i flag di database.

Configura a livello di sessione

Per ottimizzare o attivare/disattivare i parametri di smart batching per la sessione, utilizza il comando SET:

-- Disable smart batching for the current session (runs standard row-by-row execution)
SET google_ml_integration.enable_ai_function_acceleration = off;

-- Re-enable smart batching
SET google_ml_integration.enable_ai_function_acceleration = on;

-- Enable preview functions (ai.extract, ai.classify)
SET google_ml_integration.enable_preview_ai_functions = on;

Verifica lo smart batching per le funzioni AI

Per verificare che lo smart batching per le funzioni AI sia abilitato, puoi utilizzare l'istruzione EXPLAIN per analizzare la query.

Quando il batching intelligente è abilitato, il piano di esecuzione include un nodo Custom Scan (AIFunctionApply) o Parallel Custom Scan (AIFunctionApply). La presenza di questo nodo indica che le chiamate di funzione AI idonee vengono estratte dalla riga per riga standard ed eseguite in batch asincroni ad alta velocità effettiva. Se questo nodo non è presente, la query viene eseguita utilizzando la valutazione riga per riga standard di PostgreSQL.

Verifica i filtri AI nelle clausole WHERE

Quando utilizzi una funzione booleana AI (come ai.if) in una clausola WHERE insieme ai predicati SQL relazionali standard, AlloyDB valuta prima i filtri relazionali selettivi utilizzando scansioni di indici o tabelle. Poi, AlloyDB accelera solo le righe candidate per la valutazione dell'AI. Ad esempio:

EXPLAIN (COSTS OFF)
SELECT r.name, r.review
FROM restaurant_reviews r
WHERE ai.if('Is the following a positive review? Review: ' || r.review)
  AND r.city = 'Los Angeles';

Quando utilizzi l'istruzione EXPLAIN per analizzare la query, il piano di query mostra un nodo Custom Scan (AIFunctionApply):

                                       QUERY PLAN
----------------------------------------------------------------------------------------
 Custom Scan (AIFunctionApply)
   Filter: ai.if(('Is the following a positive review? Review: '::text || review), NULL::character varying)
   ->  Index Scan using idx_restaurant_reviews_city on restaurant_reviews r
         Index Cond: ((city)::text = 'Los Angeles'::text)

Il filtro relazionale (city = 'Los Angeles') viene valutato per primo nell'indice e solo le righe corrispondenti vengono raggruppate e inviate al modello per la valutazione di ai.if.

Verifica la proiezione AI con l'esecuzione parallela delle query

Le funzioni di generazione e punteggio AI nell'elenco di destinazione SELECT accelerano automaticamente. Quando le query analizzano tabelle di grandi dimensioni, l'accelerazione intelligente si integra con la query parallela di PostgreSQL, distribuendo la valutazione batch tra worker in background paralleli:

EXPLAIN (COSTS OFF)
SELECT ai.generate('Summarize the customer sentiment for: ' || r.review) AS review_summary
FROM restaurant_reviews r
WHERE ai.if('Does this review mention food safety concerns? ' || r.review);

Output del piano di query di esempio:

                            QUERY PLAN
------------------------------------------------------------------------------------------------------
 Gather
   Workers Planned: 4
   ->  Custom Scan (AIFunctionApply)
         ->  Parallel Custom Scan (AIFunctionApply)
               Filter: ai.if(('Does this review mention food safety concerns? '::text || r.review), NULL::character varying)
               ->  Parallel Seq Scan on restaurant_reviews r
(6 rows)

Comportamento di fallback

Il raggruppamento in batch intelligente fornisce una semantica di fallback sicura. Se una query contiene un costrutto o un pattern che non può essere accelerato in modo sicuro, la query non genera un errore. AlloyDB esegue invece la query in modo sicuro utilizzando l'esecuzione riga per riga standard di PostgreSQL.

Diagnostica i fallback con DEBUG2

Per verificare il motivo per cui una query ha utilizzato l'esecuzione standard anziché il batching smart, imposta client_min_messages su DEBUG2 ed esegui EXPLAIN:

SET client_min_messages TO DEBUG2;
EXPLAIN SELECT ...;
RESET client_min_messages;

Controlla l'output per individuare i messaggi di diagnostica con prefisso: AI function acceleration is not applied.

Pattern di query non supportati

I seguenti pattern di query non possono essere accelerati e tornano automaticamente all'esecuzione riga per riga standard:

  • Funzioni AI nidificate: le funzioni AI non possono accettare un'altra chiamata di funzione AI come argomento (ad esempio, ai.if(ai.if(...))).
  • Clausole di outer join ON: funzioni AI inserite nelle condizioni LEFT, RIGHT o FULL OUTER JOIN. Una soluzione alternativa è inserire il filtro AI nella clausola WHERE o in una sottoquery.
  • Aggregazioni che aggregano funzioni AI: aggregazioni dirette su funzioni AI (ad esempio, AVG(ai.rank(...))). Una soluzione alternativa è calcolare prima la funzione AI in una CTE o in una sottoquery, quindi aggregare.
  • Argomenti di funzioni volatili: espressioni di argomenti che contengono funzioni volatili (ad esempio random() o clock_timestamp()).
  • Argomenti non costanti: tutti gli argomenti che seguono l'input di testo iniziale (come output_schema, categories e model_id) devono essere valori letterali costanti, non riferimenti a colonne o espressioni.
  • Subquery correlate o parametri esterni: espressioni AI che fanno riferimento a variabili di un blocco di query esterno.
  • Relazioni non di base: scansioni su tabelle esterne (postgres_fdw) o CTE materializzate (WITH ... AS MATERIALIZED).
  • Più di cinque funzioni AI distinte: una singola scansione della tabella supporta fino a cinque chiamate di funzioni AI distinte.

Ottimizza le prestazioni

Puoi ottimizzare i parametri dell'istanza e della sessione di AlloyDB per massimizzare il throughput e ridurre al minimo la latenza per i workload AI.

Dimensione del gruppo di batch

Il parametro google_ml_integration.ai_function_acceleration_group_size imposta il numero massimo di righe raggruppate in un'unica chiamata RPC remota a Vertex AI:

  • Valore predefinito: 4000 (intervallo: da 1 a 20000)
  • Ambito: a livello di sessione, utente o database
SET google_ml_integration.ai_function_acceleration_group_size = 10000;

Linee guida per il dimensionamento dei workload:

  • Query interattive (per l'elaborazione delle transazioni online (OLTP) o bassa latenza): imposta group_size tra 50 e 100. Dimensioni dei batch più piccole restituiscono il primo batch di risultati più rapidamente per le query con clausole LIMIT.
  • Pipeline di elaborazione o analisi collettiva (per workload di elaborazione analitica online (OLAP) o di estrazione, trasformazione e caricamento (ETL)): imposta group_size tra 5000 e 20000. Batch più grandi massimizzano il throughput del modello e riducono al minimo il tempo di esecuzione complessivo delle query su set di dati di grandi dimensioni.

Gestisci la concorrenza e i worker

L'esecuzione di query in parallelo distribuisce la valutazione in batch tra i worker in background in un nodo Gather. Per ottimizzare il throughput parallelo, considera quanto segue:

  • Per scansioni analitiche pesanti, assicurati che max_parallel_workers_per_gather e max_parallel_workers siano impostati in modo appropriato per massimizzare la velocità effettiva parallela.
  • Per i workload interattivi o gli ambienti con limiti di frequenza di Vertex AI rigorosi, la riduzione del numero di worker impedisce alle query simultanee di competere per la quota del modello.

Gestisci memoria

Il batching intelligente limita automaticamente la memoria utilizzata utilizzando l'impostazione work_mem di PostgreSQL, inviando i batch in modo dinamico quando vengono raggiunte le soglie di memoria per evitare un consumo eccessivo di risorse. Assicurati che work_mem sia dimensionato in modo appropriato se elabori prompt testuali o batch molto grandi.

Ottimizza i costi

Al modello vengono inviate solo le righe che superano tutti i predicati relazionali non AI. Ogni volta che la semantica della query lo consente, l'applicazione di filtri SQL relazionali selettivi, come intervalli di date, codici di stato o filtri di categoria, riduce il numero di righe candidate inviate al modello. In questo modo si riducono i costi di chiamata del modello e la latenza di esecuzione.

Risoluzione dei problemi

Le sezioni seguenti descrivono i problemi comuni e i passaggi di correzione durante l'esecuzione di query di AI accelerate.

Query che non utilizza l'accelerazione

Se la query non utilizza il batching smart, ma ti aspetti che lo faccia, considera quanto segue:

  • Controlla il flag dell'estensione: verifica che SHOW google_ml_integration.enable_ai_function_acceleration; restituisca on.
  • Ispeziona i pattern non supportati: verifica che la query non contenga pattern di query non supportati.
  • Esegui la diagnostica di DEBUG2: esegui SET client_min_messages TO DEBUG2; seguito da EXPLAIN SELECT ...; per visualizzare il motivo specifico per cui l'accelerazione della funzione AI è stata saltata. Assicurati di eseguire RESET client_min_messages; subito dopo aver eseguito EXPLAIN per evitare che la sessione venga inondata di messaggi di debug durante le normali operazioni di query. Ad esempio:

    SET client_min_messages TO DEBUG2;
    EXPLAIN SELECT ...;
    RESET client_min_messages;
    

  • Istruzioni preparate: PostgreSQL memorizza nella cache i piani di query per le istruzioni preparate. Se hai attivato o disattivato i flag di accelerazione, esegui DEALLOCATE ALL; per ricompilare i piani memorizzati nella cache.

Gestisci l'esaurimento della quota

Se riscontri errori HTTP 429 o di limitazione di frequenza, è probabile che il raggruppamento smart stia elaborando troppe righe contemporaneamente e aumentando il consumo dell'API. Per evitare l'esaurimento della quota, tieni presente quanto segue:

  • Quote di token (TPM): assicurati che il tuo progetto Google Cloud disponga di una quota di token al minuto (TPM) adeguata per il modello di destinazione nella regione di destinazione. Per aumentare la quota di TPM, consulta Richiedi un aggiustamento della quota di TPM.
  • Limiti di frequenza dell'API Agent Platform: assicurati che il tuo progetto Google Cloud disponga di una quota sufficiente per l'API Agent Platform. Per richiedere un aumento della quota per il tuo modello Agent Platform, consulta Richiedi un aumento della quota API.
  • Query parallele: se i worker paralleli esauriscono le quote di Agent Platform, riduci il parallelismo per la sessione:

    SET max_parallel_workers_per_gather = 0;
    

  • Query non parallele: per le query non parallele soggette a limiti di frequenza, riduci le dimensioni del gruppo di batch:

    SET google_ml_integration.ai_function_acceleration_group_size = 500;
    

Passaggi successivi