Esegui query SQL intelligenti utilizzando le funzioni AI

Le funzioni AI di AlloyDB AI integrano modelli linguistici di grandi dimensioni (LLM) come Gemini direttamente con i tuoi dati AlloyDB per PostgreSQL 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 di 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 a una sola 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 riserva e crea lo schema ai.

Esistono tre categorie di funzioni di AI che differiscono in base a come gestiscono i dati di input e l'allocazione della memoria: funzioni scalari, basate su array e basate su cursore. La scelta della funzione AI giusta dipende dalla scala dei dati e dai requisiti di rendimento. 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.	Utilizza questa opzione quando vuoi una funzione di base che offra 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 l'array come output.	Utilizza per set di dati di dimensioni ridotte o medie in cui l'intero array di righe idonee può rientrare nei limiti di memoria. Ciò garantisce un throughput elevato per le operazioni basate su set.
Cursore	Accetta un cursore come input e restituisce un cursore come output.	Utilizzalo per elaborare un numero elevato di righe, ad esempio 10.000 righe.

Prima di iniziare

Verifica che l'estensione google_ml_integration sia installata e che tu stia utilizzando la versione 1.5.2 o successive. Per ottenere ulteriori vantaggi in termini di prestazioni con le funzioni basate su array, utilizza la versione 1.5.4 o successive.
Verifica che il flag google_ml_integration.enable_ai_query_engine sia impostato su on.
Esegui l'integrazione con Vertex AI.
Utilizza un modello Gemini supportato nella tua regione. Gemini 2.0 Flash è il modello predefinito del motore di query AI. Se non specifica un modello Gemini nella query, viene scelto il modello predefinito del motore di query AI per le query.

Integrare Vertex AI e installare l'estensione

Configura l'accesso degli utenti ai modelli Vertex AI.
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, aggiornala.
```
        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.
Per utilizzare la funzionalità del motore di query AlloyDB AI, imposta il flag google_ml_integration.enable_ai_query_engine 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 in tutte le sessioni e i 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 descritti 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
            
```

Utilizzare un modello Gemini supportato nella tua regione

Se il tuo cluster AlloyDB per PostgreSQL si trova in una regione in cui gemini-2.0-flash non è supportato, puoi utilizzare uno degli altri modelli Gemini disponibili nella tua regione utilizzando 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 Registra e chiama modelli di AI remoti utilizzando la gestione degli endpoint del modello.

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

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

Utilizzare 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 nel seguente modo:

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 Vertex AI. Tieni presente che 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 nel seguente modo:

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

Utilizzare i filtri nelle query

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

Eseguire 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 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 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 Utilizzare 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')
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

Eseguire 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 del 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;

Eseguire il filtraggio utilizzando funzioni basate su array

L'esempio seguente identifica i ristoranti con più di 10 recensioni positive utilizzando un modello di AI (gemini-2.0-flash) 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 elaborati dal modello di AI in blocco anziché una riga alla volta.

WITH initial_arrays AS (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',
      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;

Eseguire il filtraggio 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-2.5-flash'
    );

    -- 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 riepilogo di testo

AlloyDB AI offre operatori di generazione di testo come ai.generate scalare e ai.generate basato su array e cursore.

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

Eseguire la generazione di testo utilizzando 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',
    )
  ) AS review_summary
FROM user_reviews;

Eseguire la generazione di testo utilizzando i cursori

Per generare riepiloghi o traduzioni per milioni di righe senza riscontrare 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 $$;

Assegnare un punteggio ai risultati della query

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

Eseguire la valutazione 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;

Eseguire la valutazione 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[], model_id VARCHAR(100) DEFAULT NULL) RETURNS real[]

La seguente query utilizza UNNEST e ai.rank per valutare in modo efficiente 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;

Eseguire la valutazione 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, model_id VARCHAR(100) DEFAULT NULL) RETURNS REFCURSOR

L'esempio seguente mostra come assegnare un punteggio a 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 $$;