Realiza consultas SQL inteligentes con funciones basadas en IA

Las funciones de AlloyDB AI integran modelos de lenguaje grandes (LLM), como Gemini, directamente con tus datos de AlloyDB para PostgreSQL para que puedas combinar el lenguaje natural con las consultas en SQL. Con funciones integradas para el filtrado semántico (ai.if), la clasificación semántica (ai.rank) y la generación de texto (ai.generate), tu aplicación puede procesar datos con modelos de IA en búsquedas de una sola fila y operaciones de bases de datos a gran escala.

Nota: AlloyDB no cobra por las llamadas a funciones de IA. Sin embargo, cuando llamas a modelos y servicios de Gemini Enterprise Agent Platform, de terceros o autohospedados (como para la búsqueda híbrida) desde tu base de datos, el proveedor del modelo o de la infraestructura te cobra directamente. Para obtener más información sobre los costos de Gemini Enterprise Agent Platform, consulta Precios.

Existen tres categorías de funciones IA que difieren según cómo manejan los datos de entrada y la asignación de memoria: funciones escalares, basadas en arrays y de cursor. Elegir la función IA adecuada depende de la escala de tus datos y de tus requisitos de rendimiento. Usa la siguiente tabla para obtener información sobre estas funciones y sus casos de uso:

Categoría	Descripción	Caso práctico recomendado
Escalar	Está diseñado para el procesamiento básico uno a uno. Toma una sola entrada y devuelve una sola salida.	Úsala cuando quieras una función básica que proporcione un rendimiento aceptable para las consultas que realizan una pequeña cantidad (menos de 50) de llamadas a funciones escalares.
Basada en arrays	Procesa datos como un array de filas en una sola llamada a función. Toma un array como entrada y devuelve un array como salida.	Se usa para conjuntos de datos pequeños a medianos en los que todo el array de filas aptas puede caber dentro de los límites de memoria. Esto proporciona una alta capacidad de procesamiento para las operaciones basadas en conjuntos.
Cursor	Toma un cursor como entrada y devuelve un cursor como salida.	Se usa para procesar grandes cantidades de filas, por ejemplo, 10,000 filas.

Antes de comenzar

• Verifica que la extensión google_ml_integration esté instalada y que uses la versión 1.5.2 o una posterior. Para obtener más beneficios de rendimiento con las funciones basadas en arrays, usa la versión 1.5.4 o una posterior.
• Verifica que la marca google_ml_integration.enable_ai_query_engine esté configurada como on.
• Integrar con Gemini Enterprise Agent Platform.
• Usa un modelo de Gemini que sea compatible con tu región. Gemini 3.5 Flash-Lite es el modelo predeterminado del motor de consultas de IA. Si no especificas un modelo de Gemini en la consulta, el motor de consultas de IA usa el modelo predeterminado.

Integrar con Agent Platform e instalar la extensión

1. Configura el acceso de los usuarios a los modelos de Agent Platform.
2. Verifica que esté instalada la versión más reciente de google_ml_integration.

   1. Para verificar la versión instalada, ejecuta el siguiente comando:

      SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
      extversion 
      ------------
      1.5.2
      (1 row)

   2. Si la extensión no está instalada o si la versión instalada es anterior a la 1.5.2, actualiza la extensión.

      CREATE EXTENSION IF NOT EXISTS google_ml_integration;
      ALTER EXTENSION google_ml_integration UPDATE;

      Si tienes problemas cuando ejecutas los comandos anteriores o si la extensión no se actualiza a la versión 1.5.2 después de ejecutar los comandos anteriores, comunícate con el equipo de asistencia deGoogle Cloud .

3. Para usar la funcionalidad del motor de consultas de AlloyDB AI, establece la marca google_ml_integration.enable_ai_query_engine en on.

   SQL

   1. Habilita el motor de consultas de IA para la sesión actual.
      

      SET google_ml_integration.enable_ai_query_engine = on;

   2. Habilitar funciones para una base de datos específica en todas las sesiones
      

      ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';

   3. Habilitar el motor de consultas de IA para un usuario específico en todas las sesiones y bases de datos
      

      ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';

   Console

   Para modificar el valor de la marca google_ml_integration.enable_ai_query_engine, sigue los pasos que se indican en Configura las marcas de base de datos de una instancia.

   gcloud

   Para usar gcloud CLI, puedes instalar e inicializar Google Cloud CLI, o bien puedes usar Cloud Shell.

   Puedes modificar el valor de la marca google_ml_integration.enable_ai_query_engine. Para obtener más información, consulta Configura las marcas de base de datos de una instancia.

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

Usa un modelo de Gemini que sea compatible con tu región

El modelo predeterminado del motor de consultas de IA es gemini-3.5-flash-lite. Si no especificas un model_id en tus funciones IA, tus consultas usarán este modelo. Para verificar la disponibilidad del modelo, consulta Regiones admitidas. Para obtener detalles sobre los precios, consulta Precios de Agent Platform.

Si tu clúster de AlloyDB para PostgreSQL se encuentra en una región en la que no se admite gemini-3.5-flash-lite, puedes especificar otro modelo de Gemini disponible con el parámetro model_id. Para obtener más información, consulta Ubicaciones de extremos de modelos de Google.

Como alternativa, puedes registrar un extremo del modelo de Gemini y proporcionar ese ID de modelo a los operadores de IA. Para obtener más información, consulta Registra y llama a modelos de IA remotos con la administración de extremos de modelos.

En el siguiente ejemplo, se muestra cómo registrar otro extremo de Gemini. En este ejemplo, este segundo extremo de Gemini es el extremo global para gemini-3.5-flash-lite. Puedes usar este modelo registrado con operadores de IA pasando model_id => 'gemini-3.5-flash-lite-global' como un argumento adicional.

CALL
  google_ml.create_model(
    model_id => 'gemini-3.5-flash-lite-global',
    model_type => 'llm',
    model_provider => 'google',
    model_qualified_name => 'gemini-3.5-flash-lite',
    model_request_url =>  'https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent',
    model_auth_type => 'alloydb_service_agent_iam'
);

Usa los modelos de Gemini 3.0

Algunos modelos de Gemini, como gemini-3.0-pro-preview, solo están disponibles a través del extremo global. Debes registrar esos modelos de la siguiente manera:

CALL
  google_ml.create_model(
    model_id => 'gemini-3-preview-model',
    model_request_url => 'https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3-pro-preview:generateContent',
    model_qualified_name => 'gemini-3-pro-preview',
    model_provider => 'google',
    model_type => 'llm',
    model_auth_type => 'alloydb_service_agent_iam'
);

Reemplaza PROJECT_ID por el ID del proyecto en el que está disponible el modelo de Agent Platform. La cuenta de servicio de AlloyDB debe tener el rol de usuario de Agent Platform en ese proyecto.

Después de registrar el modelo, puedes usarlo en las funciones de IA de la siguiente manera:

SELECT ai.generate(prompt => 'What is AlloyDB?', model_id => 'gemini-3-preview-model');

Usa filtros en tus consultas

AlloyDB AI ofrece funciones de SQL potenciadas por IA que te permiten usar el procesamiento de lenguaje natural y los LLM directamente en tus consultas de base de datos, incluidos los operadores ai.if y ai.rank.

Nota: Si no especificas un tamaño de lote en tus consultas, el tamaño predeterminado es 10.

Realizar filtrados con funciones escalares

Para evaluar si se cumple una condición expresada en lenguaje natural, usa el operador ai.if/google_ml.if. La función devuelve un valor booleano verdadero o falso, y devuelve false si el resultado no se detecta con claridad.

- Function signature
FUNCTION ai.if(prompt TEXT, model_id VARCHAR(100) DEFAULT NULL) RETURNS bool

En el siguiente ejemplo, se muestra el uso del operador ai.if como filtro para encontrar restaurantes con más de 500 opiniones positivas ubicados en ciudades con una población superior a 100,000 habitantes. En el ejemplo, se usa restaurant_reviews y se incluyen datos como opiniones y la ubicación de la ciudad. El operador ai.if te ayuda a comprender la opinión de las opiniones y combinar las ubicaciones de la base de datos con el conocimiento general de Gemini sobre la población en estas ubicaciones.

SELECT r.name, r.location_city
FROM restaurant_reviews r
WHERE
  AI.IF(r.location_city || ' has a population OF more than 100,000 AND the following is a positive review; Review: ' || r.review)
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

En el siguiente ejemplo, se muestra el mismo ejemplo con el modelo que registraste en Usa un modelo de Gemini que sea compatible con tu región.

SELECT r.name, r.location_city
FROM restaurant_reviews r
WHERE
  AI.IF(r.location_city || ' has a population of more than 100,000 AND the following is a positive review; Review: ' || r.review, model_id => 'gemini-3.5-flash-lite')
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

Realiza una unión en una consulta que use el operador if

Para realizar una operación de unión, usa el operador ai.if/google_ml.if con join. En la siguiente consulta de ejemplo, se busca la cantidad de opiniones que mencionan cada elemento del menú del restaurante.

    SELECT item_name, COUNT(*)
    FROM menu_items JOIN user_reviews
      ON ai.if(
        prompt => 'Does the following user review talk about the menu item mentioned ? review: ' || user_reviews.review_text || ' menu item: ' || item_name)
    GROUP BY item_name;

Realiza filtrados con funciones basadas en arrays

En el siguiente ejemplo, se identifican los restaurantes con más de 10 opiniones positivas con un modelo de IA (gemini-3.5-flash-lite) para analizar la opinión de las opiniones y filtrar los resultados. ARRAY_AGG se usa para transformar filas individuales de datos en arrays estructurados para que el modelo de IA pueda procesarlos de forma masiva en lugar de una fila a la vez.

WITH initial_arrays AS (
  SELECT
    ARRAY_AGG(r.id ORDER BY r.id) AS review_ids,
    -- Assuming ai.if takes an array of prompts and returns a boolean array
    ai.if(
      prompts => ARRAY_AGG('Is the review positive: ' || r.review ORDER BY r.id),
      model_id => 'gemini-3.5-flash-lite',
      batch_size => 20
    ) AS truth_values
  FROM restaurant_reviews r
),
reviews AS (
SELECT
  initial_arrays.review_ids[i] AS review_id,
  initial_arrays.truth_values[i] AS truth_value
FROM
  initial_arrays,
  generate_series(1, array_length(initial_arrays.review_ids, 1)) AS i
)
SELECT rest_review.location_city, rest_review.name
FROM restaurant_reviews rest_review JOIN reviews review ON rest_review.id=review.review_id
WHERE review.truth_value = 't'
GROUP BY rest_review.location_city, rest_review.name
HAVING COUNT(*) > 10;

Realiza filtrados con cursores

En el siguiente ejemplo, se muestra cómo filtrar un conjunto grande de opiniones sobre restaurantes transmitiéndolas a través de un cursor.

Nota: Si no especificas un tamaño de lote, el tamaño predeterminado es 10.

CREATE TABLE filtered_results(input text, result bool);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    result_cursor REFCURSOR;
    rec RECORD;
BEGIN
    -- 1. Open a cursor for the input data
    OPEN prompt_cursor FOR
        SELECT r.location_city || ' has a population of > 100,000 and is a positive review; Review: ' || r.review
        FROM restaurant_reviews r;

    -- 2. Call the array-based function using the input cursor
    result_cursor := ai.if(
        'Is the given statement true? ',
        prompt_cursor,
        model_id => 'gemini-3.5-flash-lite'
    );

    -- 3. Fetch results from the output cursor and store them
    LOOP
        FETCH result_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO filtered_results VALUES(rec.input, rec.output);
    END LOOP;

    CLOSE result_cursor;
END $$;

Creación y resumen de textos

AlloyDB AI ofrece operadores de generación de texto, como ai.generate escalar, y ai.generate basados en arrays y cursores.

Para obtener más información sobre las funciones y los parámetros de los operadores, consulta la referencia de las funciones de los operadores. Para obtener guías dedicadas sobre tareas de texto específicas, consulta Resume contenido y Analiza la opinión del texto.

Genera texto con funciones escalares

La función ai.generate produce texto combinando los datos proporcionados con la instrucción del usuario.

-- Function signature
FUNCTION ai.generate(
  prompt TEXT,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS TEXT

Por ejemplo, puedes usar la siguiente consulta para generar un resumen conciso de cada opinión de los usuarios.

SELECT
  ai.generate(
    prompt => 'Summarize the review in 20 words or less. Review: ' || review) AS review_summary
FROM user_reviews;

Genera texto con funciones basadas en arrays

Esta función ai.generate te permite generar texto para varias instrucciones en lotes.

-- Function signature
FUNCTION ai.generate(
  prompts TEXT[],
  batch_size INT DEFAULT NULL,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS TEXT[]

En la siguiente consulta, se usan UNNEST y ai.generate para resumir varias opiniones de manera eficiente.

SELECT
  UNNEST(
    ai.generate(
      prompts => ARRAY_AGG('Summarize the review in 20 words or less. Review: ' || review),
      model_id => 'gemini-3.5-flash-lite'
    )
  ) AS review_summary
FROM user_reviews;

Genera texto con cursores

Para generar resúmenes o traducciones de millones de filas sin alcanzar cuellos de botella de memoria, usa la generación por lotes con cursores.

-- Function signature
FUNCTION ai.generate(
  prompt TEXT,
  input_cursor REFCURSOR,
  batch_size INT DEFAULT NULL,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS REFCURSOR

En el siguiente ejemplo, se muestra cómo generar resúmenes para grandes volúmenes de texto con cursores.

CREATE TABLE summary_results(summary text);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    summary_cursor REFCURSOR;
    rec RECORD;
BEGIN
    OPEN prompt_cursor FOR SELECT review_text FROM user_reviews ORDER BY id;

    summary_cursor := ai.generate(
        'Summarize the review in 20 words or less. Review:',
        prompt_cursor
    );

    LOOP
        FETCH summary_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO summary_results VALUES(rec.output);
    END LOOP;

    CLOSE summary_cursor;
END $$;

Asigna una puntuación a los resultados de tu consulta

Si necesitas ordenar los resultados de la consulta con instrucciones personalizadas en lenguaje natural, usa el operador ai.rank.

Realiza puntuaciones con funciones escalares

La siguiente función te permite proporcionar una instrucción que describa los criterios de clasificación y devuelva una puntuación para cada elemento.

-- Function signature
FUNCTION ai.rank(prompt TEXT, model_id VARCHAR(100) DEFAULT NULL) RETURNS real

Por ejemplo, la siguiente consulta obtiene las 20 opiniones más positivas sobre restaurantes con puntuaciones de un LLM.

SELECT review AS top20
FROM user_reviews
ORDER BY ai.rank(
  'Score the following review according to these rules:
  (1) Score OF 8 to 10 IF the review says the food IS excellent.
  (2) 4 to 7 IF the review says the food is ok.
  (3) 1 to 3 IF the review says the food is not good. Here is the review:' || review) DESC
LIMIT 20;

Realiza puntuaciones con funciones basadas en arrays

Esta función ai.rank te permite puntuar y clasificar los resultados de las consultas según instrucciones personalizadas en lenguaje natural.

-- Function signature
FUNCTION ai.rank(
  prompts TEXT[],
  batch_size INT DEFAULT NULL,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS real[]

En la siguiente consulta, se usan UNNEST y ai.rank para calificar varias opiniones de manera eficiente.

SELECT
  UNNEST(
    ai.rank(
      ARRAY_AGG('Score the following review according to these rules:
  (1) Score OF 8 to 10 IF the review says the food IS excellent.
  (2) 4 to 7 IF the review says the food is ok.
  (3) 1 to 3 IF the review says the food is not good. Here is the review:' || review)
    )
  ) as review_scores
FROM user_reviews;

Realiza la puntuación con cursores

Esta función se usa para calificar conjuntos de datos grandes sin alcanzar los límites de memoria.

-- Function signature
FUNCTION ai.rank(
  prompt TEXT,
  input_cursor REFCURSOR,
  batch_size INT DEFAULT NULL,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS REFCURSOR

En el siguiente ejemplo, se muestra cómo puntuar grandes volúmenes de texto según criterios específicos de lenguaje natural.

CREATE TABLE scored_results(input text, score real);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    score_cursor REFCURSOR;
    rec RECORD;
BEGIN
    OPEN prompt_cursor FOR SELECT review FROM user_reviews ORDER BY id;

    score_cursor := ai.rank(
        'Score the following review: (1) 8-10 if excellent, (2) 4-7 if ok, (3) 1-3 if not good. Review:',
        prompt_cursor
    );

    LOOP
        FETCH score_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO scored_results VALUES(rec.input, rec.output);
    END LOOP;

    CLOSE score_cursor;
END $$;

¿Qué sigue?

• Registra un extremo de modelo con la administración de extremos de modelos.

• Clasifica y puntúa los resultados de la búsqueda para RAG.

• Filtrar semánticamente consultas en SQL y clasificar los resultados

• Realiza previsiones de series temporales.

• Acelera las consultas con funciones de IA.

• Obtén más información sobre la referencia de administración de extremos de modelos.