Registra e chiama i modelli di IA remota utilizzando la gestione degli endpoint dei modelli

Questa pagina descrive come richiamare le previsioni o generare embedding utilizzando un modello registrando l'endpoint del modello con la gestione degli endpoint del modello.

Prima di iniziare

• Verifica che l'estensione google_ml_integration sia installata.

• Verifica che il flag google_ml_integration.enable_model_support sia impostato su on

Configurare l'estensione

1. Connettiti al database utilizzando psql o AlloyDB for PostgreSQL Studio utilizzando l'utente postgres.

2. (Facoltativo) Richiedi l'accesso per interagire con le funzionalità di AI di AlloyDB per PostgreSQL (anteprima), incluso il supporto per modelli multimodali, modelli di ranking e funzioni di operatore.

3. (Facoltativo) Concedi l'autorizzazione a un utente PostgreSQL non superutente per gestire i metadati del modello:

     GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
   

   Sostituisci la seguente variabile:

   • NON_SUPER_USER: il nome utente PostgreSQL non superutente.

4. Assicurati che l'IP in uscita sia abilitato per accedere ai modelli ospitati al di fuori del tuo VPC, ad esempio modelli di terze parti. Per saperne di più, vedi Aggiungere la connettività in uscita.

Configura l'autenticazione

Le sezioni seguenti mostrano come configurare l'autenticazione prima di registrare un endpoint del modello.

Integrare Vertex AI e installare l'estensione

Per utilizzare gli endpoint del modello Vertex AI, devi aggiungere le autorizzazioni Vertex AI al account di servizio AlloyDB basato su IAM che utilizzi per connetterti al database.

1. Configura l'accesso degli utenti ai modelli 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, 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.

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

   SQL

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

                    SET google_ml_integration.enable_ai_query_engine = true;
                    

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

Configurare l'autenticazione utilizzando Secret Manager

Questa sezione spiega come configurare l'autenticazione se utilizzi Secret Manager per archiviare i dettagli di autenticazione per fornitori di terze parti.

Questo passaggio è facoltativo se l'endpoint del modello non gestisce l'autenticazione tramite Secret Manager, ad esempio se l'endpoint del modello utilizza le intestazioni HTTP per trasmettere le informazioni di autenticazione o non utilizza affatto l'autenticazione.

Per creare e utilizzare una chiave API o un token di autenticazione, completa i seguenti passaggi:

1. Crea il secret in Secret Manager. Per saperne di più, consulta Creare un secret e accedere a una versione del secret.

   Il percorso del secret viene utilizzato nella funzione SQL google_ml.create_sm_secret().

2. Concedi le autorizzazioni al cluster AlloyDB per accedere al secret.

     gcloud secrets add-iam-policy-binding 'SECRET_NAME' \
         --member="serviceAccount:SERVICE_ACCOUNT_ID" \
         --role="roles/secretmanager.secretAccessor"
   

   Sostituisci quanto segue:

   • SECRET_NAME: il nome del secret in Secret Manager.

   • SERVICE_ACCOUNT_ID: l'ID del account di servizio basato su IAM nel formato serviceAccount:[e-mail], ad esempio [e-mail].

     Puoi anche concedere questo ruolo al account di servizio a livello di progetto. Per saperne di più, consulta Aggiungere un binding di policy Identity and Access Management.

Configurare l'autenticazione utilizzando le intestazioni

L'esempio seguente mostra come configurare l'autenticazione utilizzando una funzione. La funzione restituisce un oggetto JSON che contiene le intestazioni necessarie per effettuare una richiesta al modello di incorporamento.

  CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
    model_id VARCHAR(100),
    input_text TEXT
  )
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  DECLARE
    api_key VARCHAR(255) := 'API_KEY';
    header_json JSON;
  BEGIN
    header_json := json_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || api_key
    );
    RETURN header_json;
  END;
  $$;

Sostituisci quanto segue:

• HEADER_GEN_FUNCTION: il nome della funzione di generazione dell'intestazione che puoi utilizzare durante la registrazione di un modello.
• API_KEY: la chiave API del fornitore del modello.

Modelli di text embedding

Questa sezione mostra come registrare gli endpoint del modello con la gestione degli endpoint del modello.

La gestione degli endpoint del modello supporta alcuni modelli generici e di text embedding di Vertex AI come endpoint del modello preregistrati. Puoi utilizzare direttamente l'ID modello per generare embedding o richiamare previsioni, in base al tipo di modello. Per ulteriori informazioni sui modelli preregistrati supportati, consulta Modelli di Vertex AI preregistrati.

Nota :il supporto dei modelli Vertex AI è regolato dalle linee guida relative al controllo delle versioni e al ciclo di vita dei modelli Vertex AI. Per ulteriori informazioni sulle versioni stabili, vedi Versioni e ciclo di vita del modello.

Il modello gemini-embedding-001 è disponibile solo nella regione us-central1.

Ad esempio, per chiamare il modello gemini-embedding-001 preregistrato, puoi chiamarlo direttamente utilizzando la funzione di embedding:

SELECT
      embedding(
        model_id => 'gemini-embedding-001',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Se il cluster AlloyDB e l'endpoint Vertex AI si trovano in progetti diversi, imposta model_id sul percorso qualificato dell'endpoint, ad esempio projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/gemini-embedding-001.

Allo stesso modo, per chiamare il modello gemini-1.5-pro:generateContent preregistrato, puoi chiamarlo direttamente utilizzando la funzione di previsione:

 SELECT google_ml.predict_row(
            model_id => 'gemini-1.5-pro:generateContent',
            request_body => '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation. Only provide SQL query with no explanation."
                    }
                ]
            }
        ]
        }')-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

Per generare gli incorporamenti, scopri come generare l'incorporamento di testo. Per richiamare le previsioni, scopri come richiamarle.

Modelli di text embedding con supporto integrato

La gestione degli endpoint del modello fornisce il supporto integrato per alcuni modelli di Vertex AI e OpenAI. Per l'elenco dei modelli con supporto integrato, consulta Modelli con supporto integrato.

Per i modelli con supporto integrato, puoi impostare il nome completo come nome completo del modello e specificare l'URL della richiesta. La gestione degli endpoint del modello identifica automaticamente il modello e configura le funzioni di trasformazione predefinite.

Modelli di embedding Vertex AI

Nota :utilizza la funzione public.embedding() per eseguire query sui modelli Vertex AI senza registrazione o personalizzazione. Per trasmettere informazioni personalizzate come il tipo di attività, devi registrare il modello Vertex AI e poi utilizzare la funzione google_ml.embedding().

I passaggi seguenti mostrano come registrare i modelli Vertex AI con supporto integrato. L'endpoint del modello gemini-embedding-001 e text-multilingual-embedding-002 viene utilizzato come esempio.

Nota :solo l'endpoint del modello text-multilingual-embedding-002 richiede la configurazione delle funzioni di trasformazione fornite dalla gestione degli endpoint del modello.

Assicurati che sia il cluster AlloyDB sia il modello Vertex AI su cui esegui le query si trovino nella stessa regione.

1. Connettiti al tuo database utilizzando psql.

2. Configura l'estensione google_ml_integration.

3. Chiama la funzione di creazione del modello per aggiungere l'endpoint del modello:

   gemini-embedding-001

     CALL
       google_ml.create_model(
         model_id => 'gemini-embedding-001',
         model_request_url => 'publishers/google/models/gemini-embedding-001',
         model_provider => 'google',
         model_qualified_name => 'gemini-embedding-001',
         model_type => 'text_embedding',
         model_auth_type => 'alloydb_service_agent_iam');
   

   text-multilingual-embedding-002

     CALL
       google_ml.create_model(
         model_id => 'text-multilingual-embedding-002',
         model_request_url => 'publishers/google/models/text-multilingual-embedding-002',
         model_provider => 'google',
         model_qualified_name => 'text-multilingual-embedding-002',
         model_type => 'text_embedding',
         model_auth_type => 'alloydb_service_agent_iam'
         model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
         model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');
   

Se il modello è archiviato in un progetto e in una regione diversi dal cluster AlloyDB, imposta l'URL della richiesta su projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID, dove REGION_ID è la regione in cui è ospitato il modello e MODEL_ID è il nome qualificato del modello.

Inoltre, concedi il ruolo Utente Vertex AI (roles/aiplatform.user) all'account di servizio AlloyDB del progetto in cui si trova l'istanza AlloyDB in modo che AlloyDB possa accedere al modello ospitato nell'altro progetto.

Modello di text embedding Open AI

L'estensione google_ml_integration configura automaticamente le funzioni di trasformazione predefinite e richiama le chiamate ai modelli OpenAI remoti. Per l'elenco dei modelli OpenAI con supporto integrato, consulta Modelli con supporto integrato.

L'esempio seguente aggiunge l'endpoint del modello text-embedding-ada-002 OpenAI. Puoi registrare gli endpoint dei modelli text-embedding-3-small e text-embedding-3-large di OpenAI utilizzando gli stessi passaggi e impostando i nomi qualificati dei modelli specifici per i modelli.

1. Connettiti al database utilizzando psql.
2. Configura l'estensione google_ml_integration.
3. Aggiungi la chiave API OpenAI come secret a Secret Manager per l'autenticazione.

4. Chiama il secret archiviato in Secret Manager:

   CALL
   google_ml.create_sm_secret(
     secret_id => 'SECRET_ID',
     secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   Sostituisci quanto segue:

   • SECRET_ID: l'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello, ad esempio key1.
   • SECRET_MANAGER_SECRET_ID: l'ID secret impostato in Secret Manager quando hai creato il secret.
   • PROJECT_ID: l'ID del tuo Google Cloud progetto.
   • VERSION_NUMBER: il numero di versione dell'ID secret.

5. Chiama la funzione di creazione del modello per registrare l'endpoint del modello text-embedding-ada-002:

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_provider => 'open_ai',
       model_type => 'text_embedding',
       model_qualified_name => 'text-embedding-ada-002',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID');
   

   Sostituisci quanto segue:

   • MODEL_ID: un ID univoco per l'endpoint del modello che definisci. Questo ID modello viene utilizzato come riferimento per i metadati necessari all'endpoint del modello per generare embedding o richiamare le previsioni.
   • SECRET_ID: l'ID secret utilizzato in precedenza nella procedura google_ml.create_sm_secret().

Per generare gli embedding, consulta Generare embedding di testo.

Modello di text embedding ospitato dal cliente

Questa sezione mostra come registrare un endpoint del modello ospitato personalizzato, creare funzioni di trasformazione e, facoltativamente, intestazioni HTTP personalizzate. Tutti gli endpoint dei modelli ospitati personalizzati sono supportati indipendentemente dalla loro posizione di hosting.

L'esempio seguente aggiunge l'endpoint del modello personalizzato custom-embedding-model ospitato da Cymbal. Le funzioni di trasformazione cymbal_text_input_transform e cymbal_text_output_transform vengono utilizzate per trasformare il formato di input e output del modello nel formato di input e output della funzione di previsione.

Per registrare gli endpoint del modello di text embedding ospitato dal cliente, completa i seguenti passaggi:

1. Connettiti al tuo database utilizzando psql.

2. Configura l'estensione google_ml_integration.

3. (Facoltativo) Aggiungi la chiave API come secret a Secret Manager per l'autenticazione.

4. Chiama il secret archiviato in Secret Manager:

   CALL
     google_ml.create_sm_secret(
       secret_id => 'SECRET_ID',
       secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   Sostituisci quanto segue:

   • SECRET_ID: l'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello, ad esempio key1.
   • SECRET_MANAGER_SECRET_ID: l'ID secret impostato in Secret Manager quando hai creato il secret.
   • PROJECT_ID: l'ID del tuo Google Cloud progetto.
   • VERSION_NUMBER: il numero di versione dell'ID secret.
   Nota:Secret Manager genera un'intestazione Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER per l'autenticazione per impostazione predefinita. Se questo formato corrisponde al formato del token di autenticazione dell'endpoint del modello, non devi generare intestazioni di autenticazione utilizzando la funzione di generazione delle intestazioni.

5. Crea le funzioni di trasformazione di input e output in base alla seguente firma per la funzione di previsione per gli endpoint del modello di text embedding. Per saperne di più su come creare funzioni di trasformazione, consulta Esempio di funzioni di trasformazione.

   Di seguito sono riportate funzioni di trasformazione di esempio specifiche per l'endpoint del modello di text embedding custom-embedding-model:

   -- Input Transform Function corresponding to the custom model endpoint
   CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
   RETURNS JSON
   LANGUAGE plpgsql
   AS $$
   DECLARE
     transformed_input JSON;
     model_qualified_name TEXT;
   BEGIN
     SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
     RETURN transformed_input;
   END;
   $$;
   -- Output Transform Function corresponding to the custom model endpoint
   CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
   RETURNS REAL[]
   LANGUAGE plpgsql
   AS $$
   DECLARE
     transformed_output REAL[];
   BEGIN
     SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
     RETURN transformed_output;
   END;
   $$;
   

6. Chiama la funzione di creazione del modello per registrare l'endpoint del modello di embedding personalizzato:

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_request_url => 'REQUEST_URL',
       model_provider => 'custom',
       model_type => 'text_embedding',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID',
       model_qualified_name => 'MODEL_QUALIFIED_NAME',
       model_in_transform_fn => 'cymbal_text_input_transform',
       model_out_transform_fn => 'cymbal_text_output_transform');
   

   Sostituisci quanto segue:

   • MODEL_ID: obbligatorio. Un ID univoco per l'endpoint del modello che definisci, ad esempio custom-embedding-model. Questo ID modello viene utilizzato come riferimento per i metadati necessari all'endpoint del modello per generare embedding o richiamare le previsioni.
   • REQUEST_URL: obbligatorio. L'endpoint specifico del modello quando aggiungi endpoint di modelli generici e di text embedding personalizzati, ad esempio https://cymbal.com/models/text/embeddings/v1. Assicurati che l'endpoint del modello sia accessibile tramite un indirizzo IP interno. La gestione degli endpoint del modello non supporta gli indirizzi IP pubblici.
   • MODEL_QUALIFIED_NAME: obbligatorio se l'endpoint del modello utilizza un nome qualificato. Il nome completo nel caso in cui l'endpoint del modello abbia più versioni.
   • SECRET_ID: l'ID secret utilizzato in precedenza nella procedura google_ml.create_sm_secret().

Modello multimodale con supporto integrato

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Per informazioni sull'accesso a questa versione, consulta la pagina di richiesta di accesso.

Nota: questo lancio sperimentale è un'offerta pre-GA.

Integrare Vertex AI e installare l'estensione

Nota: per utilizzare le funzioni di AlloyDB AI, devi eseguire upgrade_to_preview_version.

1. Configura l'accesso degli utenti ai modelli 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, 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.

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

   SQL

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

                    SET google_ml_integration.enable_ai_query_engine = true;
                    

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

Chiama il modello per generare embedding multimodali

Poiché la gestione degli endpoint del modello fornisce il supporto integrato per il modello multimodalembedding@001 di Vertex AI, puoi chiamare direttamente il modello per generare incorporamenti multimodali.

L'esempio seguente utilizza il nome del modello qualificato multimodalembedding@001 come ID modello per generare incorporamenti di immagini multimodali:

1. Connettiti al database utilizzando psql.
2. Configura l'estensione google_ml_integration.

3. Genera embedding di immagini multimodali:

   SELECT
     ai.image_embedding(
       model_id => 'multimodalembedding@001',
       image => 'IMAGE_PATH_OR_TEXT',
       mimetype => 'MIMETYPE');
   

Sostituisci quanto segue:

• IMAGE_PATH_OR_TEXT con il percorso Cloud Storage dell'immagine, ad esempio gs://cymbal_user_data/image-85097193-cd9788aacebb.jpeg per tradurla in un incorporamento vettoriale o in una stringa base64 dell'immagine.
• MIMETYPE con il tipo MIME dell'immagine.

Modelli di ranking

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Per informazioni sull'accesso a questa versione, consulta la pagina di richiesta di accesso.

Nota: questa funzionalità è un'offerta sperimentale pre-GA.

Modelli di ranking Vertex AI

Puoi utilizzare i modelli Vertex AI menzionati in Modelli supportati senza registrazione.

Per scoprire come classificare i risultati di ricerca utilizzando un modello di classificazione Vertex AI, consulta Classificare i risultati di ricerca.

Nota: per utilizzare le funzioni di AlloyDB AI, devi eseguire upgrade_to_preview_version. Per ulteriori informazioni, consulta Eseguire l'integrazione con Vertex AI e installare l'estensione.

Registrazione di un modello di ranking di terze parti

L'esempio seguente mostra come registrare un modello di riassegnazione del ranking di Cohere.

CREATE OR REPLACE FUNCTION cohere_rerank_input_transform(
    model_id VARCHAR(100),
    search_string TEXT,
    documents TEXT[],
    top_n INT DEFAULT NULL
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
  transformed_input JSONB;
BEGIN
  -- Basic Input Validation
  IF search_string IS NULL OR search_string = '' THEN
    RAISE EXCEPTION 'Invalid input: search_string cannot be NULL or empty.';
  END IF;

  IF documents IS NULL OR array_length(documents, 1) IS NULL OR array_length(documents, 1) = 0 THEN
    RAISE EXCEPTION 'Invalid input: documents array cannot be NULL or empty.';
  END IF;

  IF top_n IS NOT NULL AND top_n < 0 THEN
    RAISE EXCEPTION 'Invalid input: top_n must be greater than or equal to zero. Provided value: %', top_n;
  END IF;

  -- Construct the base JSON payload for Cohere Rerank API
  transformed_input := jsonb_build_object(
    'model', google_ml.model_qualified_name_of(model_id),
    'query', search_string,
    'documents', to_jsonb(documents), -- Convert TEXT[] directly to JSON array
    'return_documents', false -- Explicitly set to false (optional, as its default)
  );

  -- Add top_n to the payload only if it's provided and valid
  IF top_n IS NOT NULL THEN
     transformed_input := transformed_input || jsonb_build_object('top_n', top_n);
  END IF;

  -- Return the final JSON payload
  RETURN transformed_input::JSON;

END;
$$;

CREATE OR REPLACE FUNCTION cohere_rerank_output_transform(
    model_id VARCHAR(100),
    response_json JSON
)
RETURNS TABLE (index INT, score REAL)
LANGUAGE plpgsql
AS $$
DECLARE
  result_item JSONB;
  response_jsonb JSONB;
  cohere_index INT; -- 0-based index from Cohere response
BEGIN
  -- Validate response_json
  IF response_json IS NULL THEN
    RAISE EXCEPTION 'Invalid model response: response cannot be NULL.';
  END IF;

  -- Convert JSON to JSONB for easier processing
  response_jsonb := response_json::JSONB;

  -- Check top-level structure
  IF jsonb_typeof(response_jsonb) != 'object' THEN
    RAISE EXCEPTION 'Invalid model response: response must be a JSON object. Found: %', jsonb_typeof(response_jsonb);
  END IF;

  -- Check for the 'results' array
  IF response_jsonb->'results' IS NULL OR jsonb_typeof(response_jsonb->'results') != 'array' THEN
    -- Check for potential Cohere error structure
    IF response_jsonb->'message' IS NOT NULL THEN
       RAISE EXCEPTION 'Cohere API Error: %', response_jsonb->>'message';
    ELSE
       RAISE EXCEPTION 'Invalid model response: response does not contain a valid "results" array.';
    END IF;
  END IF;

  -- Loop through the 'results' array (JSONB array indices are 0-based)
  FOR i IN 0..jsonb_array_length(response_jsonb->'results') - 1 LOOP
    result_item := response_jsonb->'results'->i;

    -- Validate individual result item structure
    IF result_item IS NULL OR jsonb_typeof(result_item) != 'object' THEN
      RAISE WARNING 'Skipping invalid result item at array index %.', i;
      CONTINUE;
    END IF;

    IF result_item->'index' IS NULL OR jsonb_typeof(result_item->'index') != 'number' THEN
       RAISE WARNING 'Missing or invalid "index" field in result item at array index %.', i;
       CONTINUE;
    END IF;

    IF result_item->'relevance_score' IS NULL OR jsonb_typeof(result_item->'relevance_score') != 'number' THEN
       RAISE WARNING 'Missing or invalid "relevance_score" field in result item at array index %.', i;
       CONTINUE;
    END IF;

    -- Extract values
    BEGIN
      cohere_index := (result_item->>'index')::INT;
      -- Assign values to the output table columns
      -- Cohere returns 0-based index, map it to 1-based for consistency
      -- with input document array position
      index := cohere_index + 1;
      score := (result_item->>'relevance_score')::REAL;
      RETURN NEXT; -- Return the current row
    EXCEPTION WHEN others THEN
      RAISE WARNING 'Error processing result item at array index %: %', i, SQLERRM;
      CONTINUE; -- Skip this item and continue with the next
    END;
  END LOOP;

  RETURN; -- End of function
END;
$$;

CALL
  google_ml.create_sm_secret(
    '<SECRET_ID>',
    'projects/<PROJECT_NUMBER>/secrets/<SECRET_ID>/versions/latest');

CALL
  google_ml.create_model(
    model_id => 'cohere-reranker',
    model_type => 'reranking',
    model_provider => 'custom',
    model_request_url => 'https://api.cohere.com/v2/rerank',
    model_qualified_name => 'rerank-v3.5',
    model_auth_type => 'secret_manager',
    model_auth_id => '<SECRET_ID>',
    model_in_transform_fn => 'cohere_rerank_input_transform',
    model_out_transform_fn => 'cohere_rerank_output_transform'
  );

Modelli generici

Questa sezione mostra come registrare qualsiasi endpoint del modello generico disponibile su un provider di modelli ospitati come Hugging Face, OpenAI, Vertex AI, Anthropic o qualsiasi altro provider. Questa sezione mostra esempi per registrare un endpoint del modello generico ospitato su Hugging Face, un modello generico gemini-pro da Vertex AI Model Garden e l'endpoint del modello claude-haiku.

Puoi registrare qualsiasi endpoint del modello generico, purché l'input e l'output siano in formato JSON. In base ai metadati dell'endpoint del modello, potresti dover generare intestazioni HTTP o definire URL di richiesta.

Per saperne di più sui modelli generici preregistrati e sui modelli con supporto integrato, consulta Modelli supportati.

Modelli Gemini generici

Questa sezione mostra come registrare i modelli Gemini generici.

modello gemini-1.5-pro

Poiché alcuni modelli gemini-pro sono preregistrati, puoi chiamare direttamente l'ID modello per richiamare le previsioni.

L'esempio seguente utilizza l'endpoint del modello gemini-1.5-pro:generateContent di Vertex AI Model Garden.

1. Connettiti al database utilizzando psql.
2. Configura l'estensione google_ml_integration.

3. Richiama le previsioni utilizzando l'ID modello preregistrato:

   SELECT
       json_array_elements(
       google_ml.predict_row(
           model_id => 'gemini-1.5-pro:generateContent',
           request_body => '{
       "contents": [
           {
               "role": "user",
               "parts": [
                   {
                       "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                   }
               ]
           }
       ]
       }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';
   

Modello generico su Hugging Face

L'esempio seguente aggiunge l'endpoint del modello di classificazione personalizzata facebook/bart-large-mnli ospitato su Hugging Face.

1. Connettiti al database utilizzando psql.
2. Configura l'estensione google_ml_integration.
3. Aggiungi la chiave API OpenAI come secret a Secret Manager per l'autenticazione. Se hai già creato un secret per un altro modello OpenAI, puoi riutilizzarlo.

4. Chiama il secret archiviato in Secret Manager:

   CALL
     google_ml.create_sm_secret(
       secret_id => 'SECRET_ID',
       secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   Sostituisci quanto segue:

   • SECRET_ID: l'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello.
   • SECRET_MANAGER_SECRET_ID: l'ID secret impostato in Secret Manager quando hai creato il secret.
   • PROJECT_ID: l'ID del tuo Google Cloud progetto.
   • VERSION_NUMBER: il numero di versione dell'ID secret.

5. Chiama la funzione di creazione del modello per registrare l'endpoint del modello facebook/bart-large-mnli:

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_provider => 'hugging_face',
       model_request_url => 'REQUEST_URL',
       model_qualified_name => 'MODEL_QUALIFIED_NAME',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID');
   

   Sostituisci quanto segue:

   • MODEL_ID: un ID univoco per l'endpoint del modello che definisci, ad esempio custom-classification-model. Questo ID modello viene utilizzato come riferimento per i metadati necessari all'endpoint del modello per generare embedding o richiamare le previsioni.
   • REQUEST_URL: l'endpoint specifico del modello quando aggiungi l'embedding di testo personalizzato e gli endpoint del modello generico, ad esempio https://api-inference.huggingface.co/models/facebook/bart-large-mnli.
   • MODEL_QUALIFIED_NAME: il nome completo della versione dell'endpoint del modello, ad esempio facebook/bart-large-mnli.
   • SECRET_ID: l'ID secret utilizzato in precedenza nella procedura google_ml.create_sm_secret().

Modello generico Anthropic

L'esempio seguente aggiunge l'endpoint del modello claude-3-opus-20240229. La gestione degli endpoint del modello fornisce la funzione di intestazione necessaria per registrare i modelli Anthropic.

1. Connettiti al database utilizzando psql.

2. Crea e attiva l'estensione google_ml_integration.

   Secret Manager

   1. Aggiungi il token di autenticazione come secret a Secret Manager per l'autenticazione.

   2. Chiama il secret archiviato in Secret Manager:

      CALL
        google_ml.create_sm_secret(
          secret_id => 'SECRET_ID',
          secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
      

      Sostituisci quanto segue:

      • SECRET_ID: l'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello.
      • SECRET_MANAGER_SECRET_ID: l'ID secret impostato in Secret Manager quando hai creato il secret.
      • PROJECT_ID: l'ID del tuo Google Cloud progetto.
      • VERSION_NUMBER: il numero di versione dell'ID secret.

   3. Chiama la funzione di creazione del modello per registrare l'endpoint del modello claude-3-opus-20240229.

      CALL
        google_ml.create_model(
          model_id => 'MODEL_ID',
          model_provider => 'anthropic',
          model_request_url => 'REQUEST_URL',
          model_auth_type => 'secret_manager',
          model_auth_id => 'SECRET_ID',
          generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');
      

      Sostituisci quanto segue:

      • MODEL_ID: un ID univoco per l'endpoint del modello che definisci, ad esempio anthropic-opus. Questo ID modello viene utilizzato come riferimento per i metadati necessari all'endpoint del modello per generare embedding o richiamare le previsioni.
      • REQUEST_URL: l'endpoint specifico del modello quando aggiungi l'embedding di testo personalizzato e gli endpoint del modello generico, ad esempio https://api.anthropic.com/v1/messages.

   Intestazione autorizzazione

   1. Utilizza la funzione di generazione dell'intestazione predefinita google_ml.anthropic_claude_header_gen_fn o crea una funzione di generazione dell'intestazione.

        CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON)
        RETURNS JSON
        LANGUAGE plpgsql
        AS $$
        #variable_conflict use_variable
        BEGIN
              RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON;
        END;
        $$;
      

      Sostituisci quanto segue:

      • ANTHROPIC_API_KEY: la chiave API di Anthropic.
      • ANTHROPIC_VERSION (facoltativo): la versione specifica del modello che vuoi utilizzare, ad esempio 2023-06-01.

   2. Chiama la funzione di creazione del modello per registrare l'endpoint del modello claude-3-opus-20240229.

      CALL
        google_ml.create_model(
          model_id => 'MODEL_ID',
          model_provider => 'anthropic',
          model_request_url => 'REQUEST_URL',
          generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');
      

      Sostituisci quanto segue:

      • MODEL_ID: un ID univoco per l'endpoint del modello che definisci, ad esempio anthropic-opus. Questo ID modello viene utilizzato come riferimento per i metadati necessari all'endpoint del modello per generare embedding o richiamare le previsioni.
      • REQUEST_URL: l'endpoint specifico del modello quando aggiungi l'embedding di testo personalizzato e gli endpoint del modello generico, ad esempio https://api.anthropic.com/v1/messages.

Per saperne di più, scopri come richiamare le previsioni per gli endpoint del modello generico.

Modelli di Vertex AI Model Garden

Oltre ai modelli generici, puoi registrare modelli da Vertex AI Model Garden ottimizzati per attività specifiche. La procedura comune prevede innanzitutto il deployment di un modello da Model Garden a un endpoint Vertex AI pubblico, quindi la registrazione di questo endpoint con AlloyDB per PostgreSQL. Questi modelli specifici per attività vengono spesso registrati con un model_type dedicato e utilizzati con funzioni SQL specializzate.

Previsione di serie temporali con il modello TimesFM

Un caso d'uso comune per i modelli specifici per attività è l'esecuzione di previsioni di serie temporali con il modello TimesFM.

Per eseguire il deployment e registrare questo modello, completa i seguenti passaggi:

1. Esegui il deployment del modello TimesFM da Model Garden a un endpoint Vertex AI per ottenere un URL di richiesta del modello nel seguente modo:

   1. Vai alla pagina Model Garden nella console Google Cloud :

      Vai a Model Garden

   2. Trova il modello TimesFM e seleziona Esegui il deployment.

   3. Nelle impostazioni di deployment, seleziona Pubblico (endpoint condiviso) in Accesso all'endpoint per rendere l'endpoint accessibile pubblicamente e raggiungibile da AlloyDB per PostgreSQL.

   4. Al termine del deployment, vai alla pagina dei dettagli dell'endpoint e copia l'URL della richiesta del modello dal riquadro Richiesta di esempio.

2. Per registrare il modello TimesFM di cui è stato eseguito il deployment in AlloyDB per PostgreSQL, utilizza la funzione google_ml.create_model. Per la previsione delle serie temporali, model_type deve essere ts_forecasting:

CALL
google_ml.create_model(
  model_id => 'vertex_timesfm',
  model_qualified_name => 'timesfm_v2',
  model_type => 'ts_forecasting',
  model_provider => 'google',
  model_request_url => 'https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints/ENDPOINT_ID:predict',
  model_auth_type => 'alloydb_service_agent_iam'
);

Nota: se la tua istanza AlloyDB per PostgreSQL si trova in un progetto Google Cloud diverso dall'endpoint del modello Vertex AI, devi concedere all'account di servizio AlloyDB per PostgreSQL il ruolo Vertex AI User - roles/aiplatform.user - nel progetto in cui è ospitato il modello.

Dopo aver registrato il modello, puoi utilizzare la funzione ai.forecast() o google_ml.forecast() per generare previsioni.

Passaggi successivi

• Scopri di più sul riferimento alla gestione degli endpoint del modello.
• Utilizza i modelli di esempio per registrare gli endpoint del modello.
• Genera embedding multimodali.
• Classifica e punteggio dei risultati di ricerca per RAG.
• Utilizza un linguaggio naturale negli operatori SQL.