Registra e chiama modelli di IA remoti in AlloyDB Omni

Seleziona una versione della documentazione:

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

Per ulteriori informazioni sulla funzione google_ml.create_model(), consulta la documentazione di riferimento per la gestione degli endpoint del modello.

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

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

Abilita l'estensione

Devi aggiungere e abilitare l'estensione google_ml_integration prima di poter iniziare a utilizzare le funzioni associate. La gestione degli endpoint del modello richiede l'installazione dell'estensione google_ml_integration.

  1. Connettiti al database utilizzando psql.

  2. (Facoltativo) Se l'estensione google_ml_integration è già installata, modificala per eseguire l'aggiornamento alla versione più recente:

        ALTER EXTENSION google_ml_integration UPDATE;

  3. Aggiungi l'estensione google_ml_integration utilizzando psql:

      CREATE EXTENSION google_ml_integration;

  4. (Facoltativo) Concedi a un utente PostgreSQL non superuser l'autorizzazione a gestire i metadati del modello:

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

    Sostituisci NON_SUPER_USER con il nome utente PostgreSQL non superuser.

  5. Abilita la gestione degli endpoint del modello nel database:

      ALTER SYSTEM SET google_ml_integration.enable_model_support=on;
  SELECT pg_reload_conf();

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 al account di servizio che hai utilizzato durante l'installazione di AlloyDB Omni. Per saperne di più, consulta Configurare l'installazione di AlloyDB Omni per eseguire query sui modelli basati sul cloud.

Configura l'autenticazione per altri provider di modelli

Per tutti i modelli, ad eccezione dei modelli 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 le 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, segui questi passaggi:

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

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

  2. Concedi al cluster AlloyDB le autorizzazioni 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 del 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. Include il suffisso PROJECT_ID.iam.gserviceaccount.com completo. Ad esempio: my-service@my-project.iam.gserviceaccount.com

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

Modelli di text embedding con supporto integrato

Questa sezione mostra come registrare gli endpoint del modello per i quali la gestione degli endpoint del modello fornisce supporto integrato.

Modelli di embedding Vertex AI

La gestione degli endpoint del modello fornisce supporto integrato per tutte le versioni del modello text-embedding-gecko di Vertex AI. Utilizza il nome completo per impostare la versione del modello su textembedding-gecko@001 o textembedding-gecko@002.

Poiché l'ID endpoint del modello textembedding-gecko e textembedding-gecko@001 è preregistrato con la gestione degli endpoint del modello, puoi utilizzarli direttamente come ID modello. Per questi modelli, l'estensione configura automaticamente le funzioni di trasformazione predefinite.

Per registrare la versione dell'endpoint del modello textembedding-gecko@002, segui questi passaggi:

Per AlloyDB Omni, assicurati di configurare AlloyDB Omni per eseguire query sui modelli Vertex AI basati sul cloud.

  1. Crea e abilita l'estensione google_ml_integration.

  2. Connettiti al database utilizzando psql.

  3. Crea e abilita l'estensione google_ml_integration.

  4. Chiama la funzione di creazione del modello per aggiungere l'endpoint del modello textembedding-gecko@002:

    CALL
  google_ml.create_model(
    model_id => 'textembedding-gecko@002',
    model_provider => 'google',
    model_qualified_name => 'textembedding-gecko@002',
    model_type => 'text_embedding',
    model_auth_type => 'alloydb_service_agent_iam');

  The request URL that the function generates refers to the project associated with the AlloyDB Omni service account. If you want to refer to another project, then ensure that you specify the `model_request_url` explicitly.

Modello di text embedding OpenAI

La gestione degli endpoint del modello fornisce supporto integrato per il modello text-embedding-ada-002 di OpenAI.L'estensione google_ml_integration configura automaticamente le funzioni di trasformazione predefinite e richiama le chiamate al modello remoto.

L'esempio seguente aggiunge l'endpoint del modello OpenAI text-embedding-ada-002.

  1. Connettiti al database utilizzando psql.
  2. Crea e abilita 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 del secret che hai impostato e che viene utilizzato in seguito durante la registrazione di un endpoint del modello, ad esempio key1.
    • SECRET_MANAGER_SECRET_ID: l'ID del 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 del 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 di cui l'endpoint del modello ha bisogno per generare embedding o richiamare le previsioni.
    • SECRET_ID: l'ID del secret che hai utilizzato in precedenza nella procedura google_ml.create_sm_secret().

Per generare embedding, scopri come generare embedding per gli endpoint del modello con supporto integrato.

Altri modelli di text embedding

Questa sezione mostra come registrare qualsiasi endpoint del modello di text embedding ospitato dal cliente o endpoint del modello di text embedding forniti dai provider di hosting di modelli. In base ai metadati dell'endpoint del modello, potresti dover aggiungere funzioni di trasformazione, generare intestazioni HTTP o definire endpoint.

Modello di text embedding ospitato dal cliente

Questa sezione mostra come registrare un endpoint del modello ospitato dal cliente, creare funzioni di trasformazione e, facoltativamente, intestazioni HTTP personalizzate. AlloyDB Omni supporta tutti gli endpoint del modello ospitati dal cliente, indipendentemente dalla loro posizione.

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 ospitati dal cliente, segui questi passaggi:

  1. Connettiti al database utilizzando psql.

  2. Crea e abilita 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 del secret che hai impostato e che viene utilizzato in seguito durante la registrazione di un endpoint del modello, ad esempio key1.
    • SECRET_MANAGER_SECRET_ID: l'ID del 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 del secret.

  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 le 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 di cui l'endpoint del modello ha bisogno per generare embedding o richiamare le previsioni.
    • REQUEST_URL: obbligatorio. L'endpoint specifico del modello quando aggiungi endpoint del modello generici e di text embedding personalizzati, ad esempio https://cymbal.com/models/text/embeddings/v1.
    • MODEL_QUALIFIED_NAME: obbligatorio se l'endpoint del modello utilizza un nome completo. Il nome completo nel caso in cui l'endpoint del modello abbia più versioni.
    • SECRET_ID: l'ID del secret che hai utilizzato in precedenza nella procedura google_ml.create_sm_secret().

Modelli di text embedding OpenAI Text Embedding 3 Small e Large

Puoi registrare gli endpoint del modello OpenAI text-embedding-3-small e text-embedding-3-large utilizzando la funzione di previsione dell'embedding e le funzioni di trasformazione specifiche per l'endpoint del modello. L'esempio seguente mostra come registrare l'endpoint del modello OpenAI text-embedding-3-small.

Per registrare l'endpoint del modello di embedding text-embedding-3-small:

  1. Connettiti al database utilizzando psql.
  2. Crea e abilita 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 del secret che hai impostato e che viene utilizzato in seguito durante la registrazione di un endpoint del modello.
    • SECRET_MANAGER_SECRET_ID: l'ID del 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 del secret.

  5. Crea le funzioni di trasformazione di input e output in base alla seguente firma per la funzione di previsione per i modelli di text embedding. Per saperne di più su come creare funzioni di trasformazione, consulta Esempio di funzioni di trasformazione. Per scoprire di più sui formati di input e output previsti dagli endpoint del modello OpenAI, consulta Embedding.

    Di seguito sono riportate le funzioni di trasformazione di esempio per gli endpoint del modello di text embedding OpenAI text-embedding-ada-002, text-embedding-3-small e text-embedding-3-large. 

    -- Input Transform Function corresponding to openai_text_embedding model endpoint family
CREATE OR REPLACE FUNCTION openai_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT google_ml.model_qualified_name_of(model_id) INTO model_qualified_name;
  SELECT json_build_object('input', input_text, 'model', model_qualified_name)::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;

-- Output Transform Function corresponding to openai_text_embedding model endpoint family
CREATE OR REPLACE FUNCTION openai_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->'data'->0->'embedding')) INTO transformed_output;
  RETURN transformed_output;
END;
$$;

  6. Chiama la funzione di creazione del modello per registrare l'endpoint del modello di embedding text-embedding-3-small:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'open_ai',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'text-embedding-3-small',
    model_in_transform_fn => 'openai_text_input_transform',
    model_out_transform_fn => 'openai_text_output_transform');

    Sostituisci quanto segue:

    • MODEL_ID: un ID univoco per l'endpoint del modello che definisci, ad esempio openai-te-3-small. Questo ID modello viene utilizzato come riferimento per i metadati di cui l'endpoint del modello ha bisogno per generare embedding o richiamare le previsioni.
    • SECRET_ID: l'ID del secret che hai utilizzato in precedenza nella procedura google_ml.create_sm_secret().

Per saperne di più, consulta Come generare embedding per altri endpoint del modello di text embedding.

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 o qualsiasi altro provider. Questa sezione mostra esempi per registrare un endpoint del modello generico ospitato su Hugging Face e un modello generico gemini-pro da Model Garden di Vertex AI, che non ha supporto integrato.

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

Modello generico su Hugging Face

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

  1. Connettiti al database utilizzando psql.
  2. Crea e abilita l'estensione google_ml_integration.
  3. Aggiungi il token di autenticazione 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/SECRE_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

    Sostituisci quanto segue:

    • SECRET_ID: l'ID del secret che hai impostato e che viene utilizzato in seguito durante la registrazione di un endpoint del modello.
    • SECRET_MANAGER_SECRET_ID: l'ID del 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 del 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 => 'custom',
    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 di cui l'endpoint del modello ha bisogno per generare embedding o richiamare le previsioni.
    • REQUEST_URL: l'endpoint specifico del modello quando aggiungi endpoint del modello generici e di text embedding personalizzati, 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 del secret che hai utilizzato in precedenza nella procedura google_ml.create_sm_secret().

Modello Gemini

Assicurati di configurare AlloyDB Omni per eseguire query sui modelli Vertex AI basati sul cloud.

L'esempio seguente aggiunge l'endpoint del modello gemini-1.0-pro da Model Garden di Vertex AI.

  1. Connettiti al database utilizzando psql.
  2. Crea e abilita l'estensione google_ml_integration.

  3. Chiama la funzione di creazione del modello per registrare il modello gemini-1.0-pro:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'alloydb_service_agent_iam');

    Sostituisci quanto segue:

    • MODEL_ID: un ID univoco per l'endpoint del modello che definisci, ad esempio gemini-1. Questo ID modello viene utilizzato come riferimento per i metadati di cui l'endpoint del modello ha bisogno per generare embedding o richiamare le previsioni.
    • PROJECT_ID: l'ID del tuo Google Cloud progetto.

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

Passaggi successivi

  • Scopri di più sulla documentazione di riferimento per la gestione degli endpoint del modello.