El procesamiento por lotes inteligente para las funciones de IA te permite optimizar el rendimiento cuando ejecutas consultas que usan funciones de IA en AlloyDB para PostgreSQL. Proporciona el mismo rendimiento o uno mejor que las funciones basadas en arrays, sin que tengas que volver a escribir consultas en estructuras de arrays complejas. Para obtener más información sobre las funciones de IA, consulta la descripción general de las funciones de IA.
En PostgreSQL estándar, evaluar una función de IA fila por fila genera latencia de red en cada fila individual. Con el procesamiento por lotes inteligente en AlloyDB, las operaciones de IA aptas se procesan por lotes y se descargan automáticamente para su evaluación asíncrona, lo que te permite escribir consultas en SQL estándar y fáciles de leer. Los filtros relacionales estándar se evalúan antes que las funciones de IA, lo que garantiza un rendimiento y un uso del modelo óptimos.
Funciones IA compatibles
El procesamiento por lotes inteligente de AlloyDB admite las siguientes funciones de IA,
que están disponibles en los esquemas ai y google_ml:
| Función | Descripción | Versión de la extensión |
|---|---|---|
ai.if(prompt text, ...)/google_ml.if(...) |
Evalúa una instrucción booleana de lenguaje natural y devuelve true o false. Se admite en proyecciones SELECT, filtros WHERE y cláusulas JOIN. |
Todos |
ai.rank(prompt text, ...)/google_ml.rank(...) |
Calcula una puntuación de relevancia numérica (float) que indica qué tan cerca está una entrada de los criterios dados. Se admite en los filtros WHERE y las cláusulas ORDER BY, SELECT y JOIN. |
Todos |
ai.generate(prompt text, ...)/google_ml.generate(...) |
Genera respuestas en lenguaje natural o texto estructurado con modelos de base. Se admite en proyecciones SELECT, filtros WHERE y cláusulas JOIN. |
Todos |
ai.analyze_sentiment(input text, ...)/google_ml.analyze_sentiment(...) |
Analiza la opinión del texto de entrada y devuelve 'positive', 'negative' o 'neutral'. Se admite en proyecciones SELECT, filtros WHERE y cláusulas JOIN. |
1.6.3 |
ai.summarize(input text, ...)/google_ml.summarize(...) |
Resume el texto de entrada. Se admite en proyecciones SELECT, filtros WHERE y cláusulas JOIN. |
1.6.4 |
ai.extract(input text, output_schema text, ...) / google_ml.extract(...) (en versión preliminar; requiere configurar google_ml_integration.enable_preview_ai_functions=on) |
Extrae entidades estructuradas o atributos de par clave-valor del texto. Se admite en proyecciones SELECT, filtros WHERE y cláusulas JOIN. |
1.6.1 |
ai.classify(input text, categories text[][], ...) / google_ml.classify(...) (en versión preliminar; requiere configurar google_ml_integration.enable_preview_ai_functions=on) |
Clasifica el texto en etiquetas de categorías especificadas. Se admite en proyecciones SELECT, filtros WHERE y cláusulas JOIN. |
1.6.1 |
Para obtener más información sobre la sintaxis y los parámetros de las funciones de IA, consulta la referencia de administración de extremos de modelos.
Cláusulas admitidas
La aceleración de funciones de IA funciona en las principales cláusulas de SQL, ya sea de forma individual o en combinación:
- Cláusulas
WHERE: Filtra filas con evaluaciones de IA booleanas (ai.if) después de evaluar predicados relacionales selectivos que no son de IA. - Cláusulas
ORDER BY: Calcula las puntuaciones de relevancia de la IA (ai.rank) en lotes antes de realizar operaciones de ordenamiento o limitación. - Proyecciones de
SELECT: agrupa en lotes las funciones IA escalares (ai.if,ai.rank,ai.generate,ai.analyze_sentiment,ai.summarize,ai.extractyai.classify) en las filas de resultados. - Condiciones
JOIN ... ON: evalúa las condiciones de IA de varias tablas en operacionesINNER JOINcon lotes inteligentes. - Sentencias DML: Acelera las funciones IA en los predicados
WHERE, las listas de destino y las expresionesSETen las operacionesUPDATE,DELETEyINSERT ... SELECT, comoINSERT INTO ... SELECT ai.generate(...)yUPDATE ... SET col = ai.generate(...).
Expresiones de argumentos admitidas
Los argumentos de la instrucción admiten expresiones de SQL estándar, incluidas las siguientes:
- Referencias de columnas, como
r.review - Literales de cadena concatenados con referencias de columna, como
'Is this a positive review? Review: ' || r.review - Concatenación de varias columnas, como
r.name || ' ' || r.review - Expresiones y funciones escalares de SQL, como
las instrucciones
COALESCE(r.review, ''),LOWER(r.comments),SUBSTRING(description FROM 1 FOR 500)yCASE
Antes de comenzar
Para usar el procesamiento por lotes inteligente para las funciones de IA en AlloyDB, asegúrate de que se cumplan los siguientes requisitos:
- Versión de PostgreSQL: Usa la versión 17 o posterior de PostgreSQL.
- Integra con Gemini Enterprise Agent Platform: completa los pasos que se indican en Integra con Gemini Enterprise Agent Platform.
- Disponibilidad regional: El procesamiento por lotes inteligente está disponible en las regiones que admiten
el modelo predeterminado (
gemini-3.5-flash-lite) o el modelo configurado congoogle_ml_integration.default_llm_model. Para obtener más información, consulta Regiones admitidas.
Habilita el procesamiento por lotes inteligente para las funciones IA
En PostgreSQL 18 o versiones posteriores, el procesamiento por lotes inteligente para las funciones IA está habilitado de forma predeterminada. En PostgreSQL 17, está inhabilitado de forma predeterminada y debe habilitarse
de forma explícita. Puedes configurar su comportamiento de forma global con marcas de base de datos a
nivel de la instancia o por sesión con comandos SET de SQL.
Parámetros de configuración
| Nombre del parámetro | Tipo | Predeterminado | Alcance | Descripción |
|---|---|---|---|---|
google_ml_integration.enable_ai_function_acceleration |
Booleano | PostgreSQL 18: on PostgreSQL 17: off |
Sesión, usuario o instancia | Controla si el planificador y el ejecutor de consultas descargan las operaciones de IA aptas para el procesamiento por lotes inteligente. Cuando se establece en off, las consultas se ejecutan con la ejecución estándar de PostgreSQL fila por fila. |
Configuración adicional:
- Funciones de versión preliminar: Para habilitar el procesamiento por lotes inteligente para las funciones IA en
versión preliminar,
como
ai.extractyai.classify, establecegoogle_ml_integration.enable_preview_ai_functionsenon. - Selección de modelo: Para especificar un modelo diferente en lugar del predeterminado
gemini-3.5-flash-lite, establecegoogle_ml_integration.default_llm_modelen el ID del modelo de destino o pasa el parámetromodel_iden la función IA.
Configura a nivel de la instancia
Para configurar las marcas de base de datos a nivel de la instancia en todo tu
clúster de AlloyDB, usa el 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_IDReemplaza lo siguiente:
INSTANCE_ID: Es el ID de la instancia que deseas actualizar.REGION_ID: Es el ID de la región en la que se encuentra el clúster. Para obtener más información, consulta Regiones admitidas.CLUSTER_ID: Es el ID del clúster.PROJECT_ID: el ID del proyecto
Para obtener más información, consulta Configura marcas de bases de datos.
Configura a nivel de sesión
Para ajustar o activar o desactivar los parámetros de procesamiento por lotes inteligente de tu sesión, usa el 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 el procesamiento por lotes inteligente para las funciones IA
Para verificar que el procesamiento por lotes inteligente para las funciones de IA esté habilitado, puedes usar la
declaración EXPLAIN para analizar tu consulta.
Cuando se habilita el procesamiento por lotes inteligente, el plan de ejecución incluye un nodo Custom Scan (AIFunctionApply) o Parallel Custom Scan (AIFunctionApply). La presencia de este nodo indica que las llamadas a funciones de IA aptas se
extraen de la fila por fila estándar y se ejecutan en lotes asíncronos de alta capacidad de procesamiento. Si este nodo no está presente, la consulta se ejecuta con
la evaluación fila por fila estándar de PostgreSQL.
Verifica el filtrado de IA en las cláusulas WHERE
Cuando usas una función booleana de IA (como ai.if) en una cláusula WHERE
junto con predicados de SQL relacionales estándar, AlloyDB evalúa
primero los filtros relacionales selectivos con análisis de índices o de tablas. Luego,
AlloyDB acelera solo las filas candidatas para la evaluación de IA.
Por ejemplo:
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';
Cuando usas la sentencia EXPLAIN para analizar tu consulta, el plan de consulta muestra
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)
El filtro relacional (city = 'Los Angeles') se evalúa primero en el índice,
y solo las filas que coinciden se agrupan y se envían al modelo para la evaluación de ai.if.
Verifica la proyección de IA con la ejecución de consultas en paralelo
Las funciones de puntuación y generación de IA en la lista de destino SELECT se aceleran
automáticamente. Cuando las consultas analizan tablas grandes, la aceleración inteligente se integra
en la consulta paralela de PostgreSQL,
lo que distribuye la evaluación por lotes entre los trabajadores en segundo plano paralelos:
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);
Resultado de ejemplo del plan de consulta:
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)
Comportamiento de resguardo
El procesamiento por lotes inteligente proporciona una semántica de resguardo segura. Si una consulta contiene una construcción o un patrón que no se puede acelerar de forma segura, la consulta no falla. En su lugar, AlloyDB ejecuta la consulta de forma segura con la ejecución estándar de PostgreSQL fila por fila.
Diagnostica resguardos con DEBUG2
Para verificar por qué una consulta usó la ejecución estándar en lugar del procesamiento por lotes inteligente, establece
client_min_messages en DEBUG2 y ejecuta EXPLAIN:
SET client_min_messages TO DEBUG2;
EXPLAIN SELECT ...;
RESET client_min_messages;
Inspecciona el resultado para ver los mensajes de diagnóstico con el prefijo AI function acceleration is not applied.
Patrones de consulta no admitidos
Los siguientes patrones de consulta no se pueden acelerar y recurren de forma automática a la ejecución estándar fila por fila:
- Funciones IA anidadas: Las funciones IA no pueden tomar otra llamada a función IA
como argumento (por ejemplo,
ai.if(ai.if(...))). - Cláusulas
ONde unión externa: Funciones IA ubicadas en condicionesLEFT,RIGHToFULL OUTER JOIN. Una solución alternativa es colocar el filtro de IA en la cláusulaWHEREo en una subconsulta. - Agregaciones que unen funciones IA: agregaciones directas sobre funciones IA
(por ejemplo,
AVG(ai.rank(...))). Una solución alternativa es calcular primero la función IA en una CTE o subconsulta y, luego, agregarla. - Argumentos de funciones volátiles: expresiones de argumentos que contienen funciones volátiles (por ejemplo,
random()oclock_timestamp()). - Argumentos no constantes: Todos los argumentos que siguen a la entrada de texto inicial (como
output_schema,categoriesymodel_id) deben ser literales constantes, no referencias de columnas ni expresiones. - Subconsultas correlacionadas o parámetros externos: Expresiones de IA que hacen referencia a variables de un bloque de consulta externo.
- Relaciones no base: análisis de tablas externas (
postgres_fdw) o CTE materializadas (WITH ... AS MATERIALIZED). - Más de cinco funciones de IA distintas: un solo análisis de tabla admite hasta cinco llamadas a funciones de IA distintas.
Ajusta el rendimiento
Puedes ajustar los parámetros de instancia y sesión de AlloyDB para maximizar la capacidad de procesamiento y minimizar la latencia de las cargas de trabajo de IA.
Tamaño del grupo de lotes
El parámetro google_ml_integration.ai_function_acceleration_group_size establece
la cantidad máxima de filas agrupadas en una sola llamada RPC remota a
Vertex AI:
- Valor predeterminado:
4000(rango: de1a20000) - Alcance: nivel de sesión, usuario o base de datos
SET google_ml_integration.ai_function_acceleration_group_size = 10000;
Lineamientos para el dimensionamiento de las cargas de trabajo:
- Consultas interactivas (para el procesamiento de transacciones en línea (OLTP)
o baja latencia): establece
group_sizeentre50y100. Los tamaños de lote más pequeños devuelven el primer lote de resultados con mayor rapidez para las consultas con cláusulasLIMIT. - Canalizaciones de procesamiento masivo o analíticas (para cargas de trabajo de procesamiento analítico en línea (OLAP) o de extracción, transformación y carga (ETL)): establece
group_sizeentre5000y20000. Los lotes más grandes maximizan la capacidad de procesamiento del modelo y minimizan el tiempo general de ejecución de las consultas en conjuntos de datos grandes.
Administra la simultaneidad y los trabajadores
La ejecución de consultas en paralelo distribuye la evaluación por lotes entre los trabajadores en segundo plano en un nodo de Gather. Para optimizar la capacidad de procesamiento paralela, ten en cuenta lo siguiente:
- Para los análisis analíticos pesados, asegúrate de que
max_parallel_workers_per_gatherymax_parallel_workersestén configurados de forma adecuada para maximizar la capacidad de procesamiento paralela. - En el caso de las cargas de trabajo o los entornos interactivos con límites de frecuencia estrictos de Vertex AI, reducir la cantidad de trabajadores evita que las consultas simultáneas compitan por la cuota del modelo.
Cómo administrar la memoria
El procesamiento por lotes inteligente limita automáticamente el uso de memoria con el parámetro de configuración work_mem
de PostgreSQL, lo que envía lotes de forma dinámica cuando se alcanzan los umbrales de memoria para
evitar el consumo excesivo de recursos. Asegúrate de que work_mem tenga el tamaño adecuado si procesas instrucciones de texto o lotes muy grandes.
Optimización de costos
Solo se envían al modelo las filas que pasan todos los predicados relacionales que no son de IA. Siempre que la semántica de la consulta lo permita, aplicar filtros de SQL relacionales selectivos, como rangos de fechas, códigos de estado o filtros categóricos, reduce la cantidad de filas candidatas que se envían al modelo. Esto reduce los costos de invocación del modelo y la latencia de ejecución.
Solucionar problemas
En las siguientes secciones, se describen los problemas comunes y los pasos de solución cuando se ejecutan consultas de IA aceleradas.
La consulta no usa la aceleración
Si tu consulta no usa la agrupación por lotes inteligente, pero esperas que lo haga, considera lo siguiente:
- Verifica el parámetro de configuración de la extensión: comprueba que
SHOW google_ml_integration.enable_ai_function_acceleration;devuelvaon. - Inspecciona los patrones no admitidos: Verifica que tu consulta no contenga ningún patrón de consulta no admitido.
Ejecuta el diagnóstico de
DEBUG2: ejecutaSET client_min_messages TO DEBUG2;seguido deEXPLAIN SELECT ...;para ver el motivo específico por el que se omitió la aceleración de la función IA. Asegúrate de ejecutarRESET client_min_messages;inmediatamente después de ejecutarEXPLAINpara evitar que tu sesión se inunde con mensajes de depuración durante las operaciones de consulta normales. Por ejemplo:SET client_min_messages TO DEBUG2; EXPLAIN SELECT ...; RESET client_min_messages;Sentencias preparadas: PostgreSQL almacena en caché los planes de consulta para las sentencias preparadas. Si activaste o desactivaste las marcas de aceleración, ejecuta
DEALLOCATE ALL;para volver a compilar los planes almacenados en caché.
Controla el agotamiento de la cuota
Si experimentas errores de HTTP 429 o de límite de frecuencia, es probable que se deba a que
el procesamiento por lotes inteligente procesa demasiadas filas de forma simultánea y aumenta el consumo
de la API. Para evitar el agotamiento de la cuota, ten en cuenta lo siguiente:
- Cuotas de tokens (TPM): Asegúrate de que tu proyecto de Google Cloud tenga una cuota adecuada de tokens por minuto (TPM) para tu modelo de destino en la región de destino. Para aumentar tu cuota de TPM, consulta Solicita un ajuste de cuota de TPM.
- Límites de frecuencia de la API de Agent Platform: Asegúrate de que tu proyecto de Google Cloud tenga suficiente cuota de la API de Agent Platform. Para solicitar un aumento de la cuota de tu modelo de Agent Platform, consulta Solicita un aumento de la cuota de la API.
Consultas paralelas: Si los trabajadores paralelos agotan las cuotas de Agent Platform, reduce el paralelismo de la sesión:
SET max_parallel_workers_per_gather = 0;Consultas no paralelas: Para las consultas no paralelas que experimentan límites de frecuencia, reduce el tamaño del grupo de lotes:
SET google_ml_integration.ai_function_acceleration_group_size = 500;
¿Qué sigue?
- Realiza consultas en SQL inteligentes con funciones de IA.
- Acelera las consultas de IA con funciones optimizadas.
- Configura la integración de Vertex AI.