Classifica il testo

La funzione ai.classify è uno strumento AI di AlloyDB integrato che classifica gli input di testo in un insieme di classi o etichette definite da te. Incorporando questa funzionalità direttamente nel database, AlloyDB per PostgreSQL ti consente di elaborare dati non strutturati senza creare pipeline di estrazione, trasformazione e caricamento (ETL) complesse o integrazioni di servizi esterni.

La funzione di classificazione del testo offre i seguenti vantaggi:

  • Classificazione in tempo reale: porta la conoscenza del mondo di Gemini ai dati aziendali utilizzando SQL.
  • Scalabilità: supporta il batching smart per le funzioni AI, noto anche come accelerazione delle funzioni AI, una funzionalità di ottimizzazione automatica dell'esecuzione delle query in AlloyDB AI che raggruppa in modo trasparente le singole chiamate di funzioni AI scalari riga per riga in richieste di modelli in batch in background durante l'esecuzione delle query. Supporta anche l'elaborazione basata su array e cursori per gestire in modo efficiente migliaia di righe.
  • Semplicità: fornisce un'astrazione di alto livello che gestisce automaticamente la chiamata del modello e la preparazione dei dati.

La funzione di classificazione del testo di AlloyDB AI supporta diversi casi d'uso, tra cui:

  • Classificazione degli argomenti: assegna argomenti predefiniti (come sport, tecnologia o finanza) a documenti o articoli.
  • Rilevamento dello spam: identifica email, commenti o messaggi in arrivo come spam.
  • Riconoscimento dell'intent: determina l'obiettivo dell'utente alla base di una query, ad esempio prenotare un volo, controllare il meteo o ordinare cibo.

Prima di iniziare

Assicurati di soddisfare i seguenti requisiti prima di utilizzare la funzione ai.classify:

  • Versione PostgreSQL: la funzione ai.classify è supportata su PostgreSQL versione 18 e successive. Assicurati che nel cluster AlloyDB sia in esecuzione PostgreSQL 18 o versioni successive. Per ulteriori informazioni, consulta Versioni dei database supportate.
  • Versione dell'estensione: assicurati di avere installato l'ultima versione dell'estensione google_ml_integration (versione 1.6.1 o successive) con la funzionalità di anteprima abilitata.

Attiva l'estensione

Assicurati di aver installato l'ultima versione dell'estensione google_ml_integration (versione 1.6.1 o successive) con la funzionalità di anteprima attivata.

Per attivare i flag google_ml_integration.enable_ai_query_engine e google_ml_integration.enable_preview_ai_functions in AlloyDB, utilizza il comando SET. Questi flag controllano l'accesso al motore di query AI e alle funzioni AI in anteprima come ai.classify.

  1. Assicurati che l'estensione google_ml_integration sia della versione 1.6.1 o successiva. Per verificare la versione, esegui questo comando:

    SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

  2. Attiva i flag per la sessione corrente o per l'intero database. Per abilitare i flag per la sessione corrente, esegui questo comando:

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

    Questa modifica non richiede il riavvio del database. Il valore predefinito di questi flag è off.

Crea una tabella di esempio

Per seguire gli esempi della funzione classify in questo documento, crea una tabella e compilala con le seguenti recensioni prodotto di esempio.

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

Classifica una singola stringa

Per classificare un singolo input di testo, utilizza la versione scalare di ai.classify. Per una documentazione dettagliata dell'API, consulta il riferimento di 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.
);

Classifica il testo in categorie che si escludono a vicenda

L'esempio seguente mostra un caso d'uso di base della classificazione di un singolo testo in una delle diverse categorie che si escludono a vicenda:

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

Di seguito è riportato l'output di esempio:

Report

Classifica l'argomento con più etichette

L'esempio seguente classifica un titolo di notizie in più argomenti impostando output_mode su 'multi' e fornendo descrizioni delle categorie:

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

Di seguito è riportato l'output di esempio:

politics,technology,security

Utilizza categorie con descrizioni

L'esempio seguente mostra il modo preferito per fornire le categorie utilizzando un formato di array 2D con etichette e descrizioni per una maggiore chiarezza:

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

Di seguito è riportato l'output di esempio:

non-urgent

Fornisci esempi few-shot

L'esempio seguente mostra come guidare la classificazione del modello fornendo esempi di input e dei relativi output previsti:

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

Di seguito è riportato l'output di esempio:

policy

Utilizza un ID modello specifico

L'esempio seguente mostra come utilizzare un tipo o una versione di modello specifico facendo riferimento al suo 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'
);

Di seguito è riportato l'output di esempio:

positive

Sostituisci MODEL_ID con l'ID di un modello pre-registrato supportato o di un modello personalizzato che hai registrato. Per un elenco dei modelli pre-registrati supportati, consulta Modelli di AI supportati. Per istruzioni sulla registrazione di altri endpoint dei modelli, consulta Registra e chiama modelli di AI remoti utilizzando la gestione degli endpoint dei modelli.

Classifica in batch

Quando classifichi set di dati di grandi dimensioni su più righe, puoi ottimizzare le prestazioni utilizzando l'elaborazione batch intelligente per le funzioni AI o la versione basata su array di ai.classify.

Smart batching

Per accelerare le query che eseguono ai.classify scalari su più righe senza scrivere query di aggregazione di array complesse, attiva il batching smart per le funzioni AI impostando il flag di database google_ml_integration.enable_ai_function_acceleration su on:

SET google_ml_integration.enable_ai_function_acceleration = 'on';

Quando questo flag è abilitato, AlloyDB raggruppa automaticamente le singole chiamate scalari ai.classify in batch intelligenti in background.

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

Batching basato su array

Per un controllo esplicito sull'elaborazione batch di set di dati più grandi, utilizza la versione basata su array di ai.classify per elaborare più input contemporaneamente passando un array SQL di input. Per la documentazione dettagliata dell'API, consulta il riferimento 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.
);

L'esempio seguente classifica più recensioni contemporaneamente:

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;

Di seguito è riportato l'output di esempio:

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

Classifica utilizzando i cursori

La funzione basata su cursore elabora in modo efficiente set di dati di grandi dimensioni consentendo al sistema di trasmettere i dati tramite il modello di AI in batch gestibili senza richiedere che tutti i dati vengano caricati in memoria contemporaneamente. Per saperne di più, consulta il riferimento ai.classify.

La firma della funzione per la versione basata su cursore di ai.classify è la seguente:

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

L'esempio seguente mostra come utilizzare un cursore per fornire input 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 $$;

Passaggi successivi