Chiamare i modelli utilizzando gli endpoint dei modelli in AlloyDB

L'anteprima della gestione degli endpoint dei modelli ti consente di registrare un endpoint del modello, gestire i metadati dell'endpoint del modello nel tuo cluster di database e quindi interagire con i modelli utilizzando query SQL. Fornisce l'estensione google_ml_integration che include funzioni per aggiungere e registrare i metadati dell'endpoint del modello correlati ai modelli e poi utilizzare i modelli per generare incorporamenti vettoriali o richiamare le previsioni.

Di seguito sono riportati alcuni esempi di tipi di modelli che puoi registrare utilizzando la gestione degli endpoint dei modelli:

  • Modelli di text embedding Vertex AI
  • Incorporamento di modelli forniti da provider di terze parti.
  • Modelli di text embedding ospitati personalizzati
  • Modelli generici con un'API basata su JSON, ad esempio il modello gemini-pro di Vertex AI Model Garden

Come funziona

Puoi utilizzare la gestione degli endpoint del modello per registrare un endpoint del modello conforme a quanto segue:

  • L'input e l'output del modello supportano il formato JSON.
  • Il modello può essere chiamato utilizzando il protocollo REST.

Quando registri un endpoint modello con la gestione degli endpoint modello, ogni endpoint viene registrato con un ID modello univoco che hai fornito come riferimento al modello. Puoi utilizzare questo ID modello per eseguire query sui modelli:

  • Genera incorporamenti per tradurre i prompt di testo in vettori numerici. Puoi archiviare gli embedding generati come dati vettoriali quando l'estensione pgvector è abilitata nel database.

  • Richiama le previsioni per chiamare un modello utilizzando SQL all'interno di una transazione.

Le tue applicazioni possono accedere alla gestione degli endpoint del modello utilizzando l'estensione google_ml_integration. Questa estensione fornisce le seguenti funzioni:

  • La funzione SQL google_ml.create_model(), utilizzata per registrare l'endpoint del modello utilizzato nella funzione di previsione o incorporamento.
  • La funzione SQL google_ml.create_sm_secret(), che utilizza i secret in Secret Manager, dove sono archiviate le chiavi API. Google Cloud
  • La funzione SQL google_ml.embedding(), che è una funzione di previsione che genera incorporamenti di testo.
  • La funzione SQL google_ml.predict_row() che genera previsioni quando chiami modelli generici che supportano il formato di input e output JSON.
  • Altre funzioni di assistenza che gestiscono la generazione di URL personalizzati, la generazione di intestazioni HTTP o il passaggio di funzioni di trasformazione per i modelli generici.
  • Funzioni per gestire gli endpoint e i secret del modello registrato.

Concetti fondamentali

Prima di iniziare a utilizzare la gestione degli endpoint del modello, comprendi i concetti necessari per connetterti ai modelli e utilizzarli.

Fornitore del modello

Fornitore del modello indica i provider di hosting dei modelli supportati. La tabella seguente mostra il valore del fornitore del modello che devi impostare in base al fornitore del modello che utilizzi:

Fornitore del modello Imposta in funzione come…
Vertex AI google
Altri modelli custom

Il fornitore di modelli predefinito è custom.

A seconda del tipo di provider, il metodo di autenticazione supportato varia. I modelli Vertex AI utilizzano il account di servizio Distributed Cloud per l'autenticazione, mentre altri provider possono utilizzare Secret Manager per l'autenticazione.

Tipo di modello

Model type indica il tipo di modello di AI. L'estensione supporta l'incorporamento di testo e qualsiasi tipo di modello generico. I tipi di modello supportati che puoi impostare durante la registrazione di un endpoint del modello sono text-embedding e generic. L'impostazione del tipo di modello è facoltativa quando registri endpoint di modelli generici, poiché generic è il tipo di modello predefinito.

Modelli di text embedding con supporto integrato
La gestione degli endpoint del modello fornisce il supporto integrato per tutte le versioni del modello textembedding-gecko di Vertex AI. Per registrare questi endpoint del modello, utilizza la funzione google_ml.create_model(). Distributed Cloud configura automaticamente le funzioni di trasformazione predefinite per questi modelli.
Il tipo di modello per questi modelli è text-embedding.
Altri modelli di text embedding
Per altri modelli di incorporamento di testo, devi creare funzioni di trasformazione per gestire i formati di input e output supportati dal modello. Facoltativamente, puoi utilizzare la funzione di generazione di intestazioni HTTP che genera le intestazioni personalizzate richieste dal tuo modello.
Il tipo di modello per questi modelli è text-embedding.
Modelli generici
La gestione degli endpoint del modello supporta anche la registrazione di tutti gli altri tipi di modelli, ad eccezione dei modelli di incorporamento di testo. Per richiamare le previsioni per i modelli generici, utilizza la funzione google_ml.predict_row(). Puoi impostare i metadati dell'endpoint del modello, come un endpoint di richiesta e intestazioni HTTP specifiche per il tuo modello.
Non puoi passare le funzioni di trasformazione quando registri un endpoint del modello generico. Assicurati che quando richiami le previsioni, l'input della funzione sia in formato JSON e di analizzare l'output JSON per derivare l'output finale.
Il tipo di modello per questi modelli è generic.

Autenticazione

I tipi di autenticazione indicano il tipo di autenticazione che puoi utilizzare per connetterti alla gestione degli endpoint del modello utilizzando l'estensione google_ml_integration. L'impostazione dell'autenticazione è facoltativa ed è necessaria solo se devi autenticarti per accedere al modello.

Per i modelli Vertex AI, per l'autenticazione viene utilizzato il account di servizio Distributed Cloud. Per altri modelli, è possibile utilizzare la chiave API o il token di autenticazione memorizzato come secret in Secret Manager con la funzione SQL google_ml.create_sm_secret().

La tabella seguente mostra i tipi di autenticazione che puoi impostare:

Metodo di autenticazione Imposta in funzione come… Fornitore del modello
Agente di servizio Distributed Cloud alloydb_service_agent_iam Fornitore di Vertex AI
Secret Manager secret_manager fornitori di terze parti

Funzioni di previsione

L'estensione google_ml_integration include le seguenti funzioni di previsione:

google_ml.embedding()
Utilizzato per chiamare un endpoint del modello di incorporamento di testo registrato per generare incorporamenti. Include il supporto integrato per il modello textembedding-gecko di Vertex AI.
Per i modelli di incorporamento di testo senza supporto integrato, i parametri di input e output sono univoci per un modello e devono essere trasformati affinché la funzione chiami il modello. Crea una funzione di input di trasformazione per trasformare l'input della funzione di previsione nell'input specifico del modello e una funzione di output di trasformazione per trasformare l'output specifico del modello nell'output della funzione di previsione.
google_ml.predict_row()
Utilizzato per chiamare un endpoint del modello generico registrato, a condizione che supporti l'API basata su JSON, per richiamare le previsioni.

Funzioni di trasformazione

Le funzioni di trasformazione modificano l'input in un formato comprensibile per il modello e convertono la risposta del modello nel formato previsto dalla funzione di previsione. Le funzioni di trasformazione vengono utilizzate durante la registrazione dell'endpoint del modello text-embedding senza supporto integrato. La firma delle funzioni di trasformazione dipende dalla funzione di previsione per il tipo di modello.

Non puoi utilizzare le funzioni di trasformazione quando registri un endpoint del modello generic.

Di seguito sono riportate le firme per la funzione di previsione per i modelli di incorporamento di testo:

// define custom model specific input/output transform functions.
CREATE OR REPLACE FUNCTION input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

CREATE OR REPLACE FUNCTION output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS real[];

Funzione di generazione dell'intestazione HTTP

La funzione di generazione delle intestazioni HTTP genera l'output in coppie chiave-valore JSON che vengono utilizzate come intestazioni HTTP. La firma della funzione di previsione definisce le firme della funzione di generazione dell'intestazione.

L'esempio seguente mostra la firma della funzione di previsione google_ml.embedding().

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON;

Per la funzione di previsione google_ml.predict_row(), la firma è la seguente:

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON;

Registra un modello

Per richiamare le previsioni o generare incorporamenti utilizzando un modello, registra l'endpoint del modello con la gestione degli endpoint del modello.

Per saperne di più sulla funzione google_ml.create_model(), consulta la documentazione di riferimento sulla gestione degli endpoint del modello.

Prima di registrare un endpoint del modello con la gestione degli endpoint del modello, devi attivare l'estensione google_ml_integration e configurare l'autenticazione in base al fornitore del modello, se l'endpoint del modello richiede l'autenticazione.

Assicurati di accedere al database con il nome utente predefinito postgres.

Configura l'autenticazione

Le sezioni seguenti mostrano come configurare l'autenticazione prima di aggiungere un endpoint del modello Vertex AI o endpoint del modello di altri provider.

Configura l'autenticazione per Vertex AI

Per utilizzare gli endpoint del modello Google Vertex AI, devi aggiungere le autorizzazioni Vertex AI all'account di servizio che hai utilizzato durante l'installazione di AlloyDB Omni.

Configurare l'autenticazione per altri fornitori di modelli

Per tutti i modelli, ad eccezione di quelli Vertex AI, puoi archiviare le chiavi API o i token di autenticazione in Secret Manager. Questo passaggio è facoltativo se l'endpoint del modello non gestisce l'autenticazione tramite Secret Manager, ad esempio, se l'endpoint del modello utilizza intestazioni HTTP per trasmettere le informazioni di autenticazione o non utilizza affatto l'autenticazione.

Questa sezione spiega come configurare l'autenticazione se utilizzi Secret Manager.

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

  1. Crea il secret in Secret Manager.

    Il nome e il percorso del secret vengono utilizzati nella funzione SQL google_ml.create_sm_secret().

  2. Concedi le autorizzazioni al cluster Distributed Cloud per accedere al secret.

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

    Sostituisci quanto segue:

    • SECRET_ID: l'ID secret in Secret Manager.

    • SERVICE_ACCOUNT_ID: l'ID del account di servizio che hai creato nel passaggio precedente. Assicurati che sia lo stesso account che hai utilizzato durante l'installazione di AlloyDB Omni. Ciò include il suffisso PROJECT_ID.iam.gserviceaccount.com completo. Ad esempio: my-service@my-project.iam.gserviceaccount.com.

      Puoi anche concedere questo ruolo al account di servizio a livello di progetto.

Generare incorporamenti

Questa sezione descrive un'anteprima che ti consente di sperimentare la registrazione di un endpoint del modello di AI e di richiamare le previsioni con la gestione degli endpoint del modello.

Dopo aver aggiunto e registrato gli endpoint del modello nella gestione degli endpoint del modello, puoi farvi riferimento utilizzando l'ID modello per generare incorporamenti.

Prima di iniziare

Assicurati di aver registrato l'endpoint del modello con la gestione degli endpoint del modello.

Generare incorporamenti

Utilizza la funzione SQL google_ml.embedding() per chiamare l'endpoint del modello registrato con il tipo di modello di incorporamento di testo per generare incorporamenti.

Per chiamare il modello e generare gli embedding, utilizza la seguente query SQL:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    content => 'CONTENT');

Sostituisci quanto segue:

  • MODEL_ID: l'ID modello che hai definito durante la registrazione dell'endpoint del modello.
  • CONTENT: il testo da tradurre in un embedding vettoriale.

Esempi

In questa sezione sono elencati alcuni esempi per la generazione di incorporamenti utilizzando l'endpoint del modello registrato.

Modelli di text embedding con supporto integrato

Per generare incorporamenti per un endpoint del modello textembedding-gecko@002 registrato, esegui la seguente istruzione:

    SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko@002',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Richiamare le previsioni

Questa sezione descrive un'anteprima che ti consente di sperimentare la registrazione di un endpoint del modello di AI e di richiamare le previsioni con la gestione degli endpoint del modello.

Dopo aver aggiunto e registrato gli endpoint del modello nella gestione degli endpoint del modello, puoi farvi riferimento utilizzando l'ID modello per richiamare le previsioni.

Prima di iniziare

Assicurati di aver registrato l'endpoint del modello con la gestione degli endpoint del modello.

Richiamare le previsioni per i modelli generici

Utilizza la funzione SQL google_ml.predict_row() per chiamare un endpoint del modello generico registrato per richiamare le previsioni. Puoi utilizzare la funzione google_ml.predict_row() con qualsiasi tipo di modello.

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

Sostituisci quanto segue:

  • MODEL_ID: l'ID modello che hai definito durante la registrazione dell'endpoint del modello.
  • REQUEST_BODY: i parametri della funzione di previsione, in formato JSON.

Esempi

In questa sezione sono elencati alcuni esempi di invocazione delle previsioni utilizzando gli endpoint del modello registrato.

Per generare previsioni per un endpoint del modello gemini-pro registrato, esegui la seguente istruzione:

    SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-pro',
            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';

Riferimento API per la gestione degli endpoint del modello

Questa sezione elenca i parametri per le diverse funzioni fornite dall'estensione google_ml_integration per registrare e gestire gli endpoint modello e i secret con la gestione degli endpoint modello.

Devi impostare il flag del database google_ml_integration.enable_model_support su on prima di poter iniziare a utilizzare l'estensione.

Modelli

Utilizza questo riferimento per comprendere i parametri delle funzioni che ti consentono di gestire gli endpoint del modello.

google_ml.create_model() funzione

Di seguito viene mostrato come chiamare la funzione SQL google_ml.create_model() utilizzata per registrare i metadati dell'endpoint del modello:

  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');
Parametro Obbligatorio Descrizione
MODEL_ID obbligatorio per tutti gli endpoint del modello Un ID univoco per l'endpoint del modello che definisci.
REQUEST_URL facoltativo per altri endpoint del modello di incorporamento di testo con supporto integrato L'endpoint specifico del modello quando si aggiungono altri endpoint di incorporamento di testo e di modelli generici. Per AlloyDB per PostgreSQL, fornisci un URL https.

L'URL della richiesta che la funzione genera per gli endpoint dei modelli integrati fa riferimento al progetto e alla regione o alla località del cluster. Se vuoi fare riferimento a un altro progetto, assicurati di specificare model_request_url in modo esplicito.

Per gli endpoint dei modelli personalizzati ospitati, assicurati che l'endpoint del modello sia accessibile dalla rete in cui si trova Distributed Cloud.
PROVIDER_ID obbligatorio per gli endpoint del modello di incorporamento di testo con supporto integrato Il fornitore dell'endpoint del modello. Il valore predefinito è custom.

Imposta uno dei seguenti valori:
  • google per gli endpoint dei modelli Vertex AI
  • custom per altri fornitori
MODEL_TYPE facoltativo per gli endpoint del modello generico Il tipo di modello.

Imposta uno dei seguenti valori:
  • text_embedding per gli endpoint del modello di incorporamento di testo
  • generic per tutti gli altri endpoint del modello
MODEL_QUALIFIED_NAME obbligatorio per i modelli di incorporamento di testo con supporto integrato; facoltativo per altri endpoint del modello Il nome completo dei modelli di incorporamento di testo con supporto integrato.
AUTH_TYPE facoltativo, a meno che l'endpoint del modello non abbia requisiti di autenticazione specifici Il tipo di autenticazione utilizzato dall'endpoint del modello.

Puoi impostarlo su alloydb_service_agent_iam per i modelli Vertex AI o su secret_manager per altri provider, se utilizzano Secret Manager per l'autenticazione.

Non devi impostare questo valore se utilizzi le intestazioni di autenticazione.
AUTH_ID non impostare per gli endpoint dei modelli Vertex AI; obbligatorio per tutti gli altri endpoint dei modelli che archiviano i secret in Secret Manager L'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello.
GENERATE_HEADER_FUNCTION facoltativo Il nome della funzione che genera intestazioni personalizzate.

La firma di questa funzione dipende dalla funzione di previsione che utilizzi.
INPUT_TRANSFORM_FUNCTION facoltativo per gli endpoint del modello di incorporamento di testo con supporto integrato; non impostare per gli endpoint del modello generico La funzione per trasformare l'input della funzione di previsione corrispondente nell'input specifico del modello.
OUTPUT_TRANSFORM_FUNCTION facoltativo per gli endpoint del modello di incorporamento di testo con supporto integrato; non impostare per gli endpoint del modello generico La funzione per trasformare l'output specifico del modello nell'output della funzione di previsione.

google_ml.alter_model()

Di seguito viene mostrato come chiamare la funzione SQL google_ml.alter_model() utilizzata per aggiornare i metadati dell'endpoint del modello:

    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

Per informazioni sui valori che devi impostare per ogni parametro, vedi Crea un modello.

google_ml.drop_model() funzione

Di seguito viene mostrato come chiamare la funzione SQL google_ml.drop_model() utilizzata per eliminare un endpoint del modello:

  CALL google_ml.drop_model('MODEL_ID');
Parametro Descrizione
MODEL_ID Un ID univoco per l'endpoint del modello che hai definito.

google_ml.list_model() funzione

Di seguito viene mostrato come chiamare la funzione SQL google_ml.list_model() utilizzata per elencare le informazioni sull'endpoint del modello:

  SELECT google_ml.list_model('MODEL_ID');
Parametro Descrizione
MODEL_ID Un ID univoco per l'endpoint del modello che hai definito.

google_ml.model_info_view visualizzazione

Di seguito viene illustrato come chiamare la visualizzazione google_ml.model_info_view utilizzata per elencare le informazioni sugli endpoint del modello per tutti gli endpoint del modello:

  SELECT * FROM google_ml.model_info_view;

Secret

Utilizza questo riferimento per comprendere i parametri delle funzioni che ti consentono di gestire i secret.

google_ml.create_sm_secret() funzione

Di seguito viene mostrato come chiamare la funzione SQL google_ml.create_sm_secret() utilizzata per aggiungere il secret creato 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');
Parametro Descrizione
SECRET_ID L'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello.
PROJECT_ID L'ID del tuo progetto Google Cloud che contiene il secret. Questo progetto può essere diverso da quello che contiene il cluster AlloyDB per PostgreSQL.

Per AlloyDB Omni, l'ID del tuo Google Cloud progetto che contiene il secret.
SECRET_MANAGER_SECRET_ID L'ID secret impostato in Secret Manager durante la creazione del secret.
VERSION_NUMBER Il numero di versione dell'ID secret.

google_ml.alter_sm_secret() funzione

Di seguito viene mostrato come chiamare la funzione SQL google_ml.alter_sm_secret() utilizzata per aggiornare le informazioni sul secret:

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

Per informazioni sui valori che devi impostare per ogni parametro, vedi Creare un secret.

google_ml.drop_sm_secret() funzione

Di seguito viene mostrato come chiamare la funzione SQL google_ml.drop_sm_secret() utilizzata per eliminare un secret:

  CALL google_ml.drop_sm_secret('SECRET_ID');
Parametro Descrizione
SECRET_ID L'ID secret che hai impostato e che è stato utilizzato successivamente durante la registrazione di un endpoint del modello.

Funzioni di previsione

Utilizza questo riferimento per comprendere i parametri delle funzioni che ti consentono di generare incorporamenti o richiamare previsioni.

google_ml.embedding() funzione

Di seguito viene mostrato come generare incorporamenti:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');
Parametro Descrizione
MODEL_ID Un ID univoco per l'endpoint del modello che definisci.
CONTENT Il testo da tradurre in un embedding vettoriale.

google_ml.predict_row() funzione

Di seguito viene mostrato come richiamare le previsioni:

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');
Parametro Descrizione
MODEL_ID Un ID univoco per l'endpoint del modello che definisci.
REQUEST_BODY I parametri della funzione di previsione, in formato JSON.

Funzioni di trasformazione

Utilizza questo riferimento per comprendere i parametri delle funzioni di trasformazione di input e output.

Funzione di trasformazione dell'input

Di seguito è riportata la firma della funzione di previsione per gli endpoint del modello di incorporamento di testo:

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
Parametro Descrizione
INPUT_TRANSFORM_FUNCTION La funzione per trasformare l'input della funzione di previsione corrispondente nell'input specifico dell'endpoint del modello.

Funzione di trasformazione dell'output

Di seguito è riportata la firma della funzione di previsione per gli endpoint del modello di incorporamento di testo:

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];
Parametro Descrizione
OUTPUT_TRANSFORM_FUNCTION La funzione per trasformare l'output specifico dell'endpoint del modello nell'output della funzione di previsione.

Esempio di funzioni di trasformazione

Per capire meglio come creare funzioni di trasformazione per l'endpoint del modello, considera un endpoint del modello di incorporamento di testo ospitato personalizzato che richiede input e output JSON.

La seguente richiesta cURL di esempio crea incorporamenti basati sul prompt e sull'endpoint del modello:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["AlloyDB Embeddings"]}'

Viene restituita la seguente risposta di esempio:

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

In base a questo input e a questa risposta, possiamo dedurre quanto segue:

  • Il modello prevede un input JSON tramite il campo prompt. Questo campo accetta un array di input. Poiché la funzione google_ml.embedding() è una funzione a livello di riga, prevede un input di testo alla volta. Pertanto,devi creare una funzione di trasformazione dell'input che crei un array con un singolo elemento.

  • La risposta del modello è un array di embedding, uno per ogni prompt inserito nel modello. Poiché la funzione google_ml.embedding() è una funzione a livello di riga, restituisce un singolo input alla volta. Pertanto, devi creare una funzione di trasformazione dell'output che possa essere utilizzata per estrarre l'incorporamento dall'array.

L'esempio seguente mostra le funzioni di trasformazione di input e output utilizzate per questo endpoint del modello quando viene registrato con la gestione degli endpoint del modello:

funzione di trasformazione dell'input

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

funzione di trasformazione dell'output

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

Funzione di generazione dell'intestazione HTTP

Di seguito è riportata la firma della funzione di generazione dell'intestazione che può essere utilizzata con la funzione di previsione google_ml.embedding() durante la registrazione di altri endpoint del modello di incorporamento di testo.

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Per la funzione di previsione google_ml.predict_row(), la firma è la seguente:

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;
Parametro Descrizione
GENERATE_HEADERS La funzione per generare intestazioni personalizzate. Puoi anche trasmettere l'intestazione di autorizzazione generata dalla funzione di generazione dell'intestazione durante la registrazione dell'endpoint del modello.

Esempio di funzione di generazione dell'intestazione

Per comprendere meglio come creare una funzione che genera output in coppie chiave-valore JSON utilizzate come intestazioni HTTP, considera un endpoint del modello di incorporamento di testo ospitato personalizzato.

La seguente richiesta cURL di esempio passa l'intestazione HTTP version utilizzata dall'endpoint del modello:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["AlloyDB Embeddings"]}'

Il modello prevede l'input di testo tramite il campo version e restituisce il valore della versione in formato JSON. L'esempio seguente mostra la funzione di generazione dell'intestazione utilizzata per questo endpoint del modello di incorporamento di testo quando viene registrato con la gestione degli endpoint del modello:

CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;

Funzione di generazione dell'intestazione utilizzando la chiave API

I seguenti esempi mostrano come configurare l'autenticazione utilizzando la chiave API.

modello di embedding

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

Sostituisci API_KEY con la chiave API del fornitore del modello.

modello generico

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'model-version', '2023-06-01')::JSON;
END;
$$;

Sostituisci API_KEY con la chiave API del fornitore del modello.

Generazione dell'URL di richiesta

Utilizza la funzione di generazione degli URL di richiesta per dedurre gli URL di richiesta per gli endpoint del modello con supporto integrato. Di seguito è riportata la firma di questa funzione:

CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)
Parametro Descrizione
GENERATE_REQUEST_URL La funzione per generare l'URL della richiesta generato dall'estensione per gli endpoint del modello con supporto integrato.

Modelli supportati

Puoi utilizzare la gestione degli endpoint del modello per registrare qualsiasi endpoint di modello generico o di incorporamento di testo. La gestione degli endpoint dei modelli include anche i modelli Vertex AI preregistrati e i modelli con supporto integrato.

Modelli Vertex AI preregistrati

Tipo di modello ID modello Versione estensione
generic
  • gemini-1.5-pro:streamGenerateContent
  • gemini-1.5-pro:generateContent
  • gemini-1.0-pro:generateContent
 versione 1.4.2 e successive
text_embedding
  • textembedding-gecko
  • text-embedding-gecko@001
 versione 1.3 e successive

Modelli con supporto integrato

Vertex AI

Nome del modello qualificato Tipo di modello
text-embedding-gecko@001 text-embedding
text-embedding-gecko@003 text-embedding
text-embedding-004 text-embedding
text-embedding-preview-0815 text-embedding
text-multilingual-embedding-002 text-embedding