Clasificar texto

La función ai.classify es una herramienta de IA integrada de AlloyDB AI que clasifica las entradas de texto en un conjunto de clases o etiquetas que definas. Incorporando esta capacidad directamente en la base de datos, AlloyDB para PostgreSQL te permite procesar datos no estructurados sin compilar canalizaciones complejas de extracción, transformación y carga (ETL) ni integraciones de servicios externos.

La función de clasificación de texto ofrece los siguientes beneficios:

  • Clasificación en tiempo real: Lleva el conocimiento del mundo de Gemini a los datos empresariales con SQL.
  • Escalabilidad: Admite procesamiento por lotes inteligente para funciones de IA, también conocido como aceleración de funciones de IA, que es una función de optimización de la ejecución de consultas automática en AlloyDB AI que agrupa de forma transparente llamadas a funciones de IA escalares individuales, fila por fila, en solicitudes de modelos por lotes en segundo plano durante la ejecución de la consulta. También admite el procesamiento basado en arrays y cursores para controlar miles de filas de manera eficiente.
  • Simplicidad: Proporciona una abstracción de alto nivel que administra la invocación del modelo y la preparación de los datos de forma automática.

La función de clasificación de texto de AlloyDB AI admite varios casos de uso, incluidos los siguientes:

  • Clasificación de temas: asigna temas predefinidos (como deportes, tecnología o finanzas) a documentos o artículos.
  • Detección de spam: Identifica los correos electrónicos, comentarios o mensajes entrantes como spam.
  • Reconocimiento de intents: Determina el objetivo del usuario detrás de una consulta, como reservar un vuelo, consultar el clima o pedir comida.

Antes de comenzar

Asegúrate de cumplir con los siguientes requisitos antes de usar la función ai.classify:

  • Versión de PostgreSQL: La función ai.classify es compatible con la versión 18 y posteriores de PostgreSQL. Asegúrate de que tu clúster de AlloyDB ejecute PostgreSQL 18 o una versión posterior. Para obtener más información, consulta las versiones de bases de datos compatibles.
  • Versión de la extensión: Asegúrate de tener instalada la versión más reciente de la extensión de google_ml_integration (versión 1.6.1 o posterior) con la funcionalidad de vista previa habilitada.

Habilita la extensión

Asegúrate de tener instalada la versión más reciente de la extensión google_ml_integration (versión 1.6.1 o posterior) con la funcionalidad de versión preliminar habilitada.

Para habilitar las marcas google_ml_integration.enable_ai_query_engine y google_ml_integration.enable_preview_ai_functions en AlloyDB, usa el comando SET. Estas marcas controlan el acceso al motor de consultas de IA y a las funciones IA en versión preliminar, como ai.classify.

  1. Asegúrate de que la extensión google_ml_integration sea la versión 1.6.1 o una posterior. Para verificar la versión, ejecuta el siguiente comando:

    SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

  2. Habilita las marcas para la sesión actual o para toda la base de datos. Para habilitar las marcas en tu sesión actual, ejecuta lo siguiente:

    SET google_ml_integration.enable_ai_query_engine = 'on';
SET google_ml_integration.enable_preview_ai_functions = 'on';

    Este cambio no requiere que se reinicie la base de datos. El valor predeterminado de estas marcas es off.

Crea una tabla de ejemplo

Para seguir los ejemplos de la función de clasificación de este documento, crea una tabla y compleméntala con las siguientes opiniones sobre productos de ejemplo.

CREATE TABLE IF NOT EXISTS product_reviews (
    id INT PRIMARY KEY,
    review TEXT
);

INSERT INTO product_reviews (id, review) VALUES
(1, 'Fantastic, would buy again!'),
(2, 'Broken on arrival.'),
(3, 'Mediocre, not worth the price.');

Clasifica una sola cadena

Para categorizar una sola entrada de texto, usa la versión escalar de ai.classify. Para obtener documentación detallada de la API, consulta la referencia de ai.classify.

SELECT ai.classify(
  input => 'TEXT_CONTENT',
  categories => ARRAY['CATEGORY1', 'CATEGORY2', 'CATEGORY3'],
  examples => 'EXAMPLES', -- Optional
  output_mode => 'OUTPUT_MODE', -- Optional. Can be 'single' or 'multi'.
  model_id => 'MODEL_ID' -- Optional. The default value is gemini-3.5-flash-lite.
);

Clasificar texto en categorías mutuamente excluyentes

En el siguiente ejemplo, se muestra un caso de uso básico para clasificar un solo fragmento de texto en una de varias categorías mutuamente excluyentes:

SELECT ai.classify(
  input => 'This is a sales report for Q1.',
  categories => ARRAY['Report', 'Invoice', 'Memo']
);

El siguiente es el resultado de ejemplo:

Report

Clasifica temas con varias etiquetas

En el siguiente ejemplo, se clasifica un titular de noticias en varios temas estableciendo output_mode en 'multi' y proporcionando descripciones de categorías:

SELECT ai.classify(
  input => 'The government announced new regulations on AI development, citing both economic opportunities and potential security risks.',
  categories => ARRAY[
    ARRAY['politics', 'Questions about politics'],
    ARRAY['technology', 'Questions about technology'],
    ARRAY['security', 'Questions about security']
  ],
  output_mode => 'multi'
);

El siguiente es el resultado de ejemplo:

politics,technology,security

Usa categorías con descripciones

En el siguiente ejemplo, se muestra la forma preferida de proporcionar categorías con un formato de array en 2D con etiquetas y descripciones para mayor claridad:

SELECT ai.classify(
  input => 'The patient reported mild fever and headache.',
  categories => ARRAY[
    ARRAY['urgent', 'Requires immediate medical attention'],
    ARRAY['non-urgent', 'Routine check-up or minor symptoms'],
    ARRAY['query', 'A question about services or appointments']
  ]
);

El siguiente es el resultado de ejemplo:

non-urgent

Proporciona ejemplos con pocos intentos

En el siguiente ejemplo, se muestra cómo guiar la clasificación del modelo proporcionando ejemplos de entradas y sus resultados esperados:

SELECT ai.classify(
  input => 'Is this item returnable after 90 days?',
  categories => ARRAY[
    ARRAY['policy', 'Questions about return, warranty, or other policies'],
    ARRAY['shipping', 'Questions about order shipment and delivery'],
    ARRAY['payment', 'Questions about payment methods or issues'],
    ARRAY['other', 'Any other type of question']
  ],
  examples => '[
    {"input": "When will my order arrive?", "output": "shipping"},
    {"input": "What is the warranty on this?", "output": "policy"},
    {"input": "My discount code isn''t working.", "output": "payment"}
  ]'
);

El siguiente es el resultado de ejemplo:

policy

Usa un ID de modelo específico

En el siguiente ejemplo, se muestra cómo usar una versión o un tipo de modelo específicos haciendo referencia a su ID:

SELECT ai.classify(
  input => 'This new song is a banger!',
  categories => ARRAY[
    ARRAY['positive', 'Expresses approval or enjoyment'],
    ARRAY['negative', 'Expresses disapproval or dislike']
  ],
  model_id => 'MODEL_ID'
);

El siguiente es el resultado de ejemplo:

positive

Reemplaza MODEL_ID por el ID de un modelo compatible con registro previo o un modelo personalizado que hayas registrado. Para obtener una lista de los modelos registrados previamente compatibles, consulta Modelos de IA compatibles. Para obtener instrucciones sobre cómo registrar otros extremos de modelos, consulta Registra y llama a modelos de IA remotos con la administración de extremos de modelos.

Clasifica en lotes

Cuando clasificas conjuntos de datos grandes en varias filas, puedes optimizar el rendimiento con la creación de lotes inteligente para las funciones IA o la versión basada en arrays de ai.classify.

Procesamiento por lotes inteligente

Para acelerar las consultas que ejecutan ai.classify escalares en varias filas sin escribir consultas complejas de agregación de arrays, habilita el procesamiento por lotes inteligente para las funciones IA configurando la marca de base de datos google_ml_integration.enable_ai_function_acceleration en on:

SET google_ml_integration.enable_ai_function_acceleration = 'on';

Cuando se habilita esta marca, AlloyDB agrupa automáticamente las llamadas ai.classify escalares individuales en lotes inteligentes en segundo plano.

SELECT
  id,
  ai.classify(
    input => review,
    categories => ARRAY['positive', 'neutral', 'negative']
  ) AS sentiment
FROM product_reviews
ORDER BY id;

Procesamiento por lotes basado en arrays

Para tener un control explícito sobre el procesamiento por lotes en conjuntos de datos más grandes, usa la versión basada en arrays de ai.classify para procesar varias entradas a la vez pasando un array de entradas de SQL. Para obtener documentación detallada de la API, consulta la referencia de ai.classify.

SELECT ai.classify(
  inputs => TEXT[],
  categories => TEXT[][],
  examples => TEXT, -- Optional.
  output_mode => VARCHAR, -- Optional. The default value is single.
  batch_size => INT, -- Optional. The default value is 10.
  model_id => VARCHAR(100) -- Optional. The default value is gemini-3.5-flash-lite.
);

En el siguiente ejemplo, se clasifican varias opiniones a la vez:

SELECT unnest(
  ai.classify(
    inputs => ARRAY(SELECT review FROM product_reviews ORDER BY id),
    categories => ARRAY[
      ARRAY['positive', 'Good sentiment'],
      ARRAY['neutral',  'Neither good nor bad sentiment'],
      ARRAY['negative', 'Bad sentiment']
    ],
    batch_size => 5
  )
) AS sentiment;

El siguiente es el resultado de ejemplo:

 sentiment
-----------
 positive
 negative
 negative

Clasifica con cursores

La función basada en cursores procesa grandes conjuntos de datos de manera eficiente, ya que permite que el sistema transmita datos a través del modelo de IA en lotes manejables sin necesidad de cargar todos los datos en la memoria a la vez. Para obtener más información, consulta la referencia de ai.classify.

La firma de la función para la versión basada en cursores de ai.classify es la siguiente:

CREATE OR REPLACE FUNCTION ai.classify(
    input_cursor REFCURSOR,
    categories TEXT[][],
    examples TEXT DEFAULT NULL,
    output_mode VARCHAR DEFAULT NULL,
    batch_size INT DEFAULT NULL,
    model_id VARCHAR(100) DEFAULT NULL)
  RETURNS REFCURSOR

En el siguiente ejemplo, se muestra cómo usar un cursor para proporcionar entradas a ai.classify:

DO $$
DECLARE
  cur REFCURSOR;
  result_cur REFCURSOR;
  input_val TEXT;
  sentiment TEXT;
BEGIN
  OPEN cur FOR SELECT review FROM product_reviews ORDER BY id;

  result_cur := ai.classify(
    input_cursor => cur,
    categories => ARRAY[
      ARRAY['positive', 'Good sentiment'],
      ARRAY['neutral',  'Neither good nor bad sentiment'],
      ARRAY['negative', 'Bad sentiment']
    ],
    batch_size => 20
  );

  LOOP
    FETCH result_cur INTO input_val, sentiment;
    EXIT WHEN NOT FOUND;
    RAISE NOTICE 'Sentiment: %', sentiment;
  END LOOP;

  CLOSE result_cur;
  CLOSE cur;
END $$;

¿Qué sigue?