Esegui query SQL intelligenti utilizzando le funzioni AI

Seleziona una versione della documentazione:

Questa pagina mostra come utilizzare il motore di query AlloyDB Omni AI ed eseguire query SQL intelligenti utilizzando le funzioni AI.

Le funzioni AI di AlloyDB integrano i modelli linguistici di grandi dimensioni (LLM) come Gemini direttamente con i dati di AlloyDB Omni per eseguire operazioni intelligenti sui dati. Questa funzionalità include funzioni integrate per:

  • Filtro (ai.if)
  • Ranking semantico (ai.rank)
  • Generazione di testo (ai.generate)

Queste funzioni AI utilizzano il motore di query di AlloyDB AI per aiutare la tua applicazione a elaborare i dati utilizzando modelli di intelligenza artificiale su varie scale, dalle risposte su singola riga alle operazioni di database su larga scala. Puoi utilizzare gli operatori ai.if, ai.rank e ai.generate per combinare il linguaggio naturale con le query SQL. AlloyDB AI prenota e crea lo schema ai.

Esistono tre categorie di funzioni AI che si differenziano in base al modo in cui gestiscono i dati di input e l'allocazione della memoria: funzioni scalari, basate su array e cursore. La scelta della funzione AI giusta dipende dalla scala dei tuoi dati e dai requisiti di prestazioni. Utilizza la seguente tabella per scoprire di più su queste funzioni e sui relativi casi d'uso:

Category

Descrizione

Caso d'uso consigliato

Scalare

Progettato per l'elaborazione di base, uno a uno. Accetta un singolo input e restituisce un singolo output.

Utilizzala se vuoi una funzione di base che fornisca prestazioni accettabili per le query che effettuano un numero ridotto (meno di 50) di chiamate di funzioni scalari.

Basato su array

Elabora i dati come un array di righe in una singola chiamata di funzione. Accetta un array come input e restituisce un array come output.

Utilizzala per set di dati di piccole e medie dimensioni in cui l'intero array di righe idonee può rientrare nei limiti di memoria. In questo modo, viene fornito un throughput elevato per le operazioni basate su set.

Cursore

Utilizza un cursore come input e restituisce un cursore come output.

Utilizzala per elaborare un numero elevato di righe, ad esempio 10.000 righe.

Prima di iniziare

  1. Configura l'accesso degli utenti ai modelli di Vertex AI.

  2. Verifica che sia installata l'ultima versione di google_ml_integration.

    1. Per controllare la versione installata, esegui questo comando:

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

    2. Se l'estensione non è installata o se la versione installata è precedente alla 1.5.2, aggiorna l'estensione. 

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

      Se riscontri problemi durante l'esecuzione dei comandi precedenti o se l'estensione non viene aggiornata alla versione 1.5.2 dopo l'esecuzione dei comandi precedenti, contatta l'assistenzaGoogle Cloud .

  3. Per utilizzare la funzionalità del motore di query AlloyDB AI, imposta il flag google_ml_integration.enable_ai_query_engine su on.

    SQL

    1. Abilita il motore di query AI per la sessione corrente.

      SET google_ml_integration.enable_ai_query_engine = on;

    2. Abilitare le funzionalità per un database specifico in più sessioni.

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

    3. Attiva il motore di query AI per un utente specifico in tutte le sessioni e i database. 

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

  4. Utilizza un modello Gemini supportato nella tua regione. Gemini 3.5 Flash-Lite è il modello predefinito del motore di query AI. Se non specifichi un modello Gemini nella query, il motore di query AI utilizza il modello predefinito.

Utilizza un modello Gemini supportato nella tua regione

Il modello predefinito del motore di query AI è gemini-3.5-flash-lite. Se non specifichi un model_id nelle funzioni AI, le query utilizzano questo modello. Per verificare la disponibilità dei modelli, consulta Regioni supportate. Per i dettagli sui prezzi, consulta Prezzi di Agent Platform.

Se il tuo cluster AlloyDB Omni si trova in una regione in cui gemini-3.5-flash-lite non è supportato, puoi specificare un altro modello Gemini disponibile utilizzando il parametro model_id. Per saperne di più, consulta Posizioni degli endpoint dei modelli Google.

In alternativa, puoi registrare un endpoint del modello Gemini e fornire l'ID del modello agli operatori AI. Per saperne di più, consulta Registra e chiama modelli di AI remoti utilizzando la gestione degli endpoint dei modelli.

L'esempio seguente mostra come registrare un altro endpoint Gemini. In questo esempio, questo secondo endpoint Gemini è l'endpoint globale per gemini-3.5-flash-lite. Puoi utilizzare questo modello registrato con gli operatori AI passando model_id => 'gemini-3.5-flash-lite-global' come argomento aggiuntivo.

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

Utilizza i modelli Gemini 3

Alcuni modelli Gemini, come gemini-3-pro-preview, sono disponibili solo tramite l'endpoint globale. Devi registrare questi modelli come segue:

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

Sostituisci PROJECT_ID con l'ID del progetto in cui è disponibile il modello di AI Vertex AI. Tieni presente che il account di servizio AlloyDB Omni deve avere il ruolo Vertex AI User in quel progetto.

Dopo aver registrato il modello, puoi utilizzarlo nelle funzioni AI nel seguente modo:

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

Utilizza i filtri nelle query

AlloyDB AI offre funzioni SQL basate sull'AI che ti consentono di utilizzare l'elaborazione del linguaggio naturale e gli LLM direttamente nelle query del database, inclusi gli operatori ai.if e ai.rank.

Eseguire il filtro utilizzando funzioni scalari

Per valutare se una condizione espressa in linguaggio naturale è soddisfatta, utilizza l'operatore ai.if/google_ml.if. La funzione restituisce un valore booleano true o false e restituisce false se l'output non viene rilevato chiaramente.

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

L'esempio seguente mostra l'utilizzo dell'operatore ai.if come filtro per trovare ristoranti con più di 500 recensioni positive situati in città con una popolazione superiore a 100.000 abitanti. L'esempio utilizza restaurant_reviews e contiene dati come recensioni e località della città. L'operatore ai.if ti aiuta a comprendere il sentiment delle recensioni e a combinare le località del database con le conoscenze generali di Gemini sulla popolazione di queste località.

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;

Di seguito viene mostrato lo stesso esempio utilizzando il modello che hai registrato in Utilizza un modello Gemini supportato nella tua regione.

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;

Esegui un join su una query che utilizza l'operatore if

Per eseguire un'operazione di join, utilizza l'operatore ai.if/google_ml.if con join. La seguente query di esempio trova il numero di recensioni che menzionano ogni voce di menu del ristorante.

    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;

Esegui il filtro utilizzando funzioni basate su array

L'esempio seguente identifica i ristoranti con più di 10 recensioni positive utilizzando un modello di AI (gemini-3.5-flash-lite) per analizzare il sentiment delle recensioni e filtrare i risultati. ARRAY_AGG viene utilizzato per trasformare singole righe di dati in array strutturati in modo che possano essere elaborate dal modello di AI in blocco anziché una riga alla volta.

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;

Esegui il filtro utilizzando i cursori

L'esempio seguente mostra come filtrare un ampio insieme di recensioni di ristoranti trasmettendole in streaming tramite un cursore.

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 $$;

Generazione e riassunto di testo

AlloyDB AI offre operatori di generazione di testo come ai.generate scalare e ai.generate basati su array e cursori.

Esegui la generazione di testo utilizzando funzioni scalari

La funzione ai.generate produce testo combinando i dati forniti con il prompt dell'utente.

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

Ad esempio, puoi utilizzare la seguente query per generare un riepilogo conciso di ogni recensione utente.

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

Esegui la generazione di testo utilizzando funzioni basate su array

La seguente query utilizza UNNEST e ai.generate per riassumere più recensioni in modo efficiente.

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 testo utilizzando i cursori

Per generare riepiloghi o traduzioni per milioni di righe senza colli di bottiglia della memoria, utilizza la generazione in batch con i cursori.

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 $$;

Valuta i risultati della query

Se devi ordinare i risultati della query utilizzando istruzioni personalizzate in linguaggio naturale, utilizza l'operatore ai.rank.

Esegui lo scoring utilizzando le funzioni scalari

La seguente funzione ti consente di fornire un prompt che descrive i criteri di ranking e restituisce un punteggio per ogni elemento.

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

Ad esempio, la seguente query recupera le 20 recensioni di ristoranti più positive, utilizzando i punteggi di 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;

Esegui lo scoring utilizzando funzioni basate su array

Questa funzione ai.rank ti consente di assegnare un punteggio e classificare i risultati delle query in base a istruzioni personalizzate in linguaggio naturale.

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

La seguente query utilizza UNNEST e ai.rank per valutare più recensioni in modo efficiente.

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;

Esegui il calcolo del punteggio utilizzando i cursori

Questa funzione viene utilizzata per assegnare un punteggio a set di dati di grandi dimensioni senza superare i limiti di memoria.

FUNCTION ai.rank(context TEXT, input_cursor REFCURSOR, batch_size INT DEFAULT NULL, model_id VARCHAR(100) DEFAULT NULL) RETURNS REFCURSOR

L'esempio seguente mostra come valutare grandi volumi di testo in base a criteri specifici del linguaggio naturale.

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 $$;

Passaggi successivi