Classificar texto

A função ai.classify é uma ferramenta de IA integrada do AlloyDB que categoriza entradas de texto em um conjunto de classes ou rótulos que você define. Ao incorporar esse recurso diretamente no banco de dados, o AlloyDB para PostgreSQL permite processar dados não estruturados sem criar pipelines complexos de extração, transformação e carregamento (ETL) ou integrações de serviços externos.

A função de classificação de texto oferece os seguintes benefícios:

  • Classificação em tempo real: leva o conhecimento do mundo real do Gemini para os dados corporativos usando SQL.
  • Escalonabilidade: oferece suporte ao lote inteligente para funções de IA, também conhecido como aceleração de funções de IA, que é um recurso de otimização automática de execução de consultas na IA do AlloyDB que agrupa de forma transparente chamadas de funções de IA escalares individuais, linha por linha, em solicitações de modelo em lote em segundo plano durante a execução da consulta. Também oferece suporte ao processamento baseado em matrizes e em cursores para lidar com milhares de linhas de maneira eficiente.
  • Simplicidade: fornece uma abstração de alto nível que gerencia automaticamente a invocação de modelos e a preparação de dados.

A função de classificação de texto da IA do AlloyDB é compatível com vários casos de uso, incluindo os seguintes:

  • Classificação de tópicos: atribua tópicos predefinidos (como esportes, tecnologia ou finanças) a documentos ou artigos.
  • Detecção de spam: identificar e-mails, comentários ou mensagens recebidos como spam.
  • Reconhecimento de intenção: determine o objetivo do usuário por trás de uma consulta, como reservar um voo, verificar o clima ou pedir comida.

Antes de começar

Verifique se você atende aos seguintes requisitos antes de usar a função ai.classify:

  • Versão do PostgreSQL: a função ai.classify é compatível com o PostgreSQL versão 18 e mais recentes. Verifique se o cluster do AlloyDB está executando o PostgreSQL 18 ou mais recente. Para mais informações, consulte Versões de banco de dados compatíveis.
  • Versão da extensão: verifique se você tem a versão mais recente da extensão google_ml_integration (versão 1.6.1 ou mais recente) instalada com a funcionalidade de pré-lançamento ativada.

Ativar a extensão

Verifique se você tem a versão mais recente da extensão google_ml_integration (versão 1.6.1 ou mais recente) instalada com a funcionalidade de pré-lançamento ativada.

Para ativar as flags google_ml_integration.enable_ai_query_engine e google_ml_integration.enable_preview_ai_functions no AlloyDB, use o comando SET. Essas flags controlam o acesso ao mecanismo de consulta de IA e às funções de IA em pré-lançamento, como ai.classify.

  1. Verifique se a extensão google_ml_integration é da versão 1.6.1 ou mais recente. Para verificar a versão, execute o seguinte:

    SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

  2. Ative as flags para a sessão atual ou para todo o banco de dados. Para ativar as flags na sessão atual, execute o seguinte:

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

    Essa mudança não exige a reinicialização do banco de dados. O valor padrão dessas flags é off.

Criar uma tabela de exemplo

Para seguir os exemplos da função de classificação neste documento, crie uma tabela e preencha-a com as seguintes avaliações do produto de amostra.

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.');

Classificar uma única string

Para categorizar uma única entrada de texto, use a versão escalar de ai.classify. Para uma documentação detalhada da API, consulte a referência do 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.
);

Classificar texto em categorias mutuamente exclusivas

O exemplo a seguir mostra um caso de uso básico de classificação de um único texto em uma das várias categorias mutuamente exclusivas:

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

Veja um exemplo de saída:

Report

Classificar assunto com vários rótulos

O exemplo a seguir classifica uma manchete de notícias em vários tópicos definindo output_mode como 'multi' e fornecendo descrições de categoria:

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'
);

Veja um exemplo de saída:

politics,technology,security

Usar categorias com descrições

O exemplo a seguir demonstra a maneira preferencial de fornecer categorias usando um formato de matriz 2D com rótulos e descrições para maior clareza:

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']
  ]
);

Veja um exemplo de saída:

non-urgent

Fornecer exemplos de poucos disparos (few-shot)

O exemplo a seguir mostra como orientar a classificação do modelo fornecendo exemplos de entradas e as saídas esperadas:

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"}
  ]'
);

Veja um exemplo de saída:

policy

Usar um ID de modelo específico

O exemplo a seguir demonstra como usar uma versão ou um tipo de modelo específico referenciando o ID dele:

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'
);

Veja um exemplo de saída:

positive

Substitua MODEL_ID pelo ID de um modelo pré-registrado compatível ou de um modelo personalizado que você registrou. Para uma lista de modelos pré-registrados compatíveis, consulte Modelos de IA compatíveis. Para instruções sobre como registrar outros endpoints de modelo, consulte Registrar e chamar modelos de IA remotos usando o gerenciamento de endpoints de modelo.

Classificar em lotes

Ao classificar grandes conjuntos de dados em várias linhas, é possível otimizar o desempenho usando lotes inteligentes para funções de IA ou a versão baseada em matriz de ai.classify.

Lote inteligente

Para acelerar as consultas que executam ai.classify escalar em várias linhas sem escrever consultas complexas de agregação de matrizes, ative o lote inteligente para funções de IA definindo a flag de banco de dados google_ml_integration.enable_ai_function_acceleration como on:

SET google_ml_integration.enable_ai_function_acceleration = 'on';

Quando essa flag está ativada, o AlloyDB agrupa automaticamente chamadas escalares individuais de ai.classify em lotes inteligentes em segundo plano.

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

Processamento em lote baseado em matriz

Para ter controle explícito sobre o processamento em lote em conjuntos de dados maiores, use a versão baseada em matriz de ai.classify para processar várias entradas de uma só vez transmitindo uma matriz SQL de entradas. Para ver a documentação detalhada da API, consulte a referência 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.
);

O exemplo a seguir classifica várias avaliações de uma só 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;

Veja um exemplo de saída:

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

Classificar usando cursores

A função baseada em cursor processa grandes conjuntos de dados de forma eficiente, permitindo que o sistema transmita dados pelo modelo de IA em lotes gerenciáveis, sem exigir que todos os dados sejam carregados na memória de uma só vez. Para mais informações, consulte a referência de ai.classify.

A assinatura de função para a versão baseada em cursor de ai.classify é a seguinte:

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

O exemplo a seguir mostra como usar um cursor para alimentar entradas para 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 $$;

A seguir