Esegui 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 per PostgreSQL per eseguire operazioni di dati intelligenti. Questa funzionalità include funzioni integrate per quanto segue:

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

Queste funzioni AI utilizzano il motore di query AI di AlloyDB per aiutare l'applicazione a elaborare i dati utilizzando modelli di intelligenza artificiale su varie scale, dalle risposte a riga singola 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 riserva e crea lo ai schema.

Esistono tre categorie di funzioni AI che differiscono in base alla modalità di gestione dei dati di input e dell'allocazione della memoria: funzioni scalari, basate su array e cursore. La scelta della funzione AI corretta dipende dalla scalabilità dei dati e dai requisiti di prestazioni. Utilizza la tabella seguente 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, one-to-one. Accetta un singolo input e restituisce un singolo output.

Utilizza questa funzione quando 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.

Utilizza questa funzione per set di dati di piccole e medie dimensioni in cui l'intero array di righe idonee può rientrare nei limiti di memoria. Questa funzione fornisce un throughput elevato per le operazioni basate su set.

Cursore

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

Utilizza questa funzione per elaborare un numero elevato di righe, ad esempio 10.000 righe.

Prima di iniziare

Esegui l'integrazione con Agent Platform e installa l'estensione

  1. Configura l'accesso utente ai modelli di Agent Platform.
  2. Verifica che sia installata l'ultima versione di google_ml_integration.

    1. Per controllare la versione installata, esegui il seguente 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'Google Cloud assistenza.

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

    SQL

    1. Attiva il motore di query AI per la sessione corrente.
      SET google_ml_integration.enable_ai_query_engine = on;
    2. Attiva le funzionalità per un database specifico tra le 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 tra sessioni e database.
      ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';

    Console

    Per modificare il valore del flag google_ml_integration.enable_ai_query_engine, segui i passaggi in Configurare i flag di database di un'istanza.

    gcloud

    Per utilizzare gcloud CLI, puoi installare e inizializzare Google Cloud CLI oppure puoi utilizzare Cloud Shell.

    Puoi modificare il valore del flag google_ml_integration.enable_ai_query_engine. Per saperne di più, consulta Configurare i flag di database di un'istanza. 

    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

Utilizza un modello Gemini supportato nella tua regione

Se il cluster AlloyDB per PostgreSQL si trova in una regione in cui gemini-2.5-flash-lite non è supportato, puoi utilizzare uno degli altri modelli Gemini disponibili nella tua regione utilizzando il model_id parameter.

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

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

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

Utilizza i modelli Gemini 3.0

Alcuni modelli Gemini, come gemini-3.0-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 Agent Platform. L' account di servizio AlloyDB deve avere il ruolo Utente Vertex AI in quel progetto.

Dopo aver registrato il modello, puoi utilizzarlo nelle funzioni AI come segue:

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.

Esegui il filtraggio utilizzando le funzioni scalari

Per valutare se una condizione espressa in linguaggio naturale è soddisfatta, utilizza l'operatore ai.if/google_ml.if. La funzione restituisce il 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 i 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 posizione della città. L'operatore ai.if ti aiuta a comprendere il sentiment della recensione e a combinare le località del database con la conoscenza generale di Gemini sulla popolazione in 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 è riportato lo stesso esempio utilizzando il modello 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-2.5-flash-lite')
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

Esegui un'operazione di 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 dal 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 filtraggio utilizzando le funzioni basate su array

L'esempio seguente identifica i ristoranti con più di 10 recensioni positive utilizzando un modello AI (gemini-2.5-flash-lite) per analizzare il sentiment delle recensioni e filtrare i risultati. ARRAY_AGG viene utilizzato per trasformare le singole righe di dati in array strutturati in modo che possano essere elaborati dal modello 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-2.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.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.city, rest_review.name
HAVING COUNT(*) > 10;

Esegui il filtraggio utilizzando i cursori

L'esempio seguente mostra come filtrare un set di recensioni di ristoranti di grandi dimensioni 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-2.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 basato su array e cursore.

Esegui la generazione di testo utilizzando le 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 riassunto conciso di ogni recensione dell'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 le funzioni basate su array

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

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

Esegui la generazione di testo utilizzando i cursori

Per generare riassunti o traduzioni per milioni di righe senza raggiungere i colli di bottiglia della memoria, utilizza la generazione 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 $$;

Assegna un punteggio ai risultati della query

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

Esegui l'assegnazione di punteggi 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 l'assegnazione di punteggi utilizzando le funzioni basate su array

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

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

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

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 l'assegnazione di punteggi utilizzando i cursori

Questa funzione viene utilizzata per assegnare punteggi a set di dati di grandi dimensioni senza raggiungere i limiti di memoria.

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

L'esempio seguente mostra come assegnare punteggi a grandi volumi di testo in base a criteri specifici in 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