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.extracteai.classify) tra le righe dei risultati. - Condizioni
JOIN ... ON: valuta le condizioni AI tra tabelle nelle operazioniINNER JOINutilizzando il batching intelligente. - Istruzioni DML: accelera le funzioni AI nei predicati
WHERE, negli elenchi di destinazione e nelle espressioniSETnelle operazioniUPDATE,DELETEeINSERT ... SELECT, comeINSERT INTO ... SELECT ai.generate(...)eUPDATE ... 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)eCASE
Prima di iniziare
Per utilizzare il batching smart per le funzioni AI in AlloyDB, assicurati che siano soddisfatti i seguenti prerequisiti:
- Versione PostgreSQL: utilizza PostgreSQL versione 17 o successive.
- Integra con Gemini Enterprise Agent Platform: completa i passaggi descritti in Integra con Gemini Enterprise Agent Platform.
- 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 utilizzandogoogle_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.extracteai.classify, impostagoogle_ml_integration.enable_preview_ai_functionssuon. - Selezione del modello: per specificare un modello diverso da quello predefinito
gemini-3.5-flash-lite, impostagoogle_ml_integration.default_llm_modelsull'ID del modello di destinazione o passa il parametromodel_idnella 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_IDSostituisci 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 condizioniLEFT,RIGHToFULL OUTER JOIN. Una soluzione alternativa è inserire il filtro AI nella clausolaWHEREo 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()oclock_timestamp()). - Argomenti non costanti: tutti gli argomenti che seguono l'input di testo iniziale (come
output_schema,categoriesemodel_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: da1a20000) - 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_sizetra50e100. Dimensioni dei batch più piccole restituiscono il primo batch di risultati più rapidamente per le query con clausoleLIMIT. - Pipeline di elaborazione o analisi collettiva (per workload di elaborazione analitica online (OLAP) o di estrazione, trasformazione e caricamento (ETL)): imposta
group_sizetra5000e20000. 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_gatheremax_parallel_workerssiano 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;restituiscaon. - Ispeziona i pattern non supportati: verifica che la query non contenga pattern di query non supportati.
Esegui la diagnostica di
DEBUG2: eseguiSET client_min_messages TO DEBUG2;seguito daEXPLAIN SELECT ...;per visualizzare il motivo specifico per cui l'accelerazione della funzione AI è stata saltata. Assicurati di eseguireRESET client_min_messages;subito dopo aver eseguitoEXPLAINper 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
- Esegui query SQL intelligenti utilizzando le funzioni AI.
- Accelera le query AI utilizzando funzioni ottimizzate.
- Configura l'integrazione di Vertex AI.