Acelera el rendimiento de las consultas con funciones basadas en IA

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.extract y ai.classify) en las filas de resultados.
  • Condiciones JOIN ... ON: evalúa las condiciones de IA de varias tablas en operaciones INNER JOIN con lotes inteligentes.
  • Sentencias DML: Acelera las funciones IA en los predicados WHERE, las listas de destino y las expresiones SET en las operaciones UPDATE, DELETE y INSERT ... SELECT, como INSERT INTO ... SELECT ai.generate(...) y UPDATE ... 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) y CASE

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:

  1. Versión de PostgreSQL: Usa la versión 17 o posterior de PostgreSQL.
  2. Integra con Gemini Enterprise Agent Platform: completa los pasos que se indican en Integra con Gemini Enterprise Agent Platform.
  3. 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 con google_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.extract y ai.classify, establece google_ml_integration.enable_preview_ai_functions en on.
  • Selección de modelo: Para especificar un modelo diferente en lugar del predeterminado gemini-3.5-flash-lite, establece google_ml_integration.default_llm_model en el ID del modelo de destino o pasa el parámetro model_id en 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_ID

Reemplaza 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 ON de unión externa: Funciones IA ubicadas en condiciones LEFT, RIGHT o FULL OUTER JOIN. Una solución alternativa es colocar el filtro de IA en la cláusula WHERE o 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() o clock_timestamp()).
  • Argumentos no constantes: Todos los argumentos que siguen a la entrada de texto inicial (como output_schema, categories y model_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: de 1 a 20000)
  • 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_size entre 50 y 100. Los tamaños de lote más pequeños devuelven el primer lote de resultados con mayor rapidez para las consultas con cláusulas LIMIT.
  • 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_size entre 5000 y 20000. 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_gather y max_parallel_workers esté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; devuelva on.
  • 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: ejecuta SET client_min_messages TO DEBUG2; seguido de EXPLAIN SELECT ...; para ver el motivo específico por el que se omitió la aceleración de la función IA. Asegúrate de ejecutar RESET client_min_messages; inmediatamente después de ejecutar EXPLAIN para 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?