Enregistrer et appeler des modèles d'IA distants dans AlloyDB Omni

Sélectionnez une version de la documentation :

Pour appeler des prédictions ou générer des embeddings à l'aide d'un modèle, enregistrez le point de terminaison du modèle avec la gestion des points de terminaison de modèle.

Pour en savoir plus sur la fonction google_ml.create_model(), consultez la documentation de référence sur la gestion des points de terminaison de modèle.

Avant d'enregistrer un point de terminaison de modèle avec la gestion des points de terminaison de modèle, vous devez activer l'extension google_ml_integration et configurer l'authentification en fonction du fournisseur de modèle, si votre point de terminaison de modèle nécessite une authentification.

Assurez-vous d'accéder à votre base de données avec le nom d'utilisateur par défaut postgres.

Activer l'extension

Vous devez ajouter et activer l'extension google_ml_integration avant de pouvoir utiliser les fonctions associées. La gestion des points de terminaison de modèle nécessite l'installation de l'extension google_ml_integration.

  1. Connectez-vous à votre base de données à l'aide de psql.

  2. Facultatif : Si l'extension google_ml_integration est déjà installée, modifiez-la pour passer à la dernière version :

        ALTER EXTENSION google_ml_integration UPDATE;

  3. Ajoutez l'extension google_ml_integration à l'aide de psql :

      CREATE EXTENSION google_ml_integration;

  4. Facultatif : accordez l'autorisation à un utilisateur PostgreSQL autre qu'un super-administrateur de gérer les métadonnées du modèle :

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

    Remplacez NON_SUPER_USER par le nom d'utilisateur PostgreSQL non super-utilisateur.

  5. Activez la gestion des points de terminaison de modèle sur votre base de données :

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

Configurer l'authentification

Les sections suivantes expliquent comment configurer l'authentification avant d'ajouter un point de terminaison de modèle Vertex AI ou des points de terminaison de modèle d'autres fournisseurs.

Configurer l'authentification pour Vertex AI

Pour utiliser les points de terminaison de modèle Google Vertex AI, vous devez ajouter des autorisations Vertex AI au compte de service que vous avez utilisé lors de l'installation d'AlloyDB Omni. Pour en savoir plus, consultez Configurer votre installation AlloyDB Omni pour interroger des modèles basés dans le cloud.

Configurer l'authentification pour d'autres fournisseurs de modèles

Pour tous les modèles, à l'exception des modèles Vertex AI, vous pouvez stocker vos clés API ou jetons du porteur dans Secret Manager. Cette étape est facultative si votre point de terminaison de modèle ne gère pas l'authentification via Secret Manager, par exemple s'il utilise des en-têtes HTTP pour transmettre les informations d'authentification ou s'il n'utilise pas du tout l'authentification.

Cette section explique comment configurer l'authentification si vous utilisez Secret Manager.

Pour créer et utiliser une clé API ou un jeton du porteur, procédez comme suit :

  1. Créez le secret dans Secret Manager. Pour en savoir plus, consultez Créer un secret et accéder à une version de secret.

    Le nom et le chemin du secret sont utilisés dans la fonction SQL google_ml.create_sm_secret().

  2. Accordez au cluster AlloyDB les autorisations d'accès au secret.

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

    Remplacez les éléments suivants :

    • SECRET_ID : ID du secret dans Secret Manager.

    • SERVICE_ACCOUNT_ID : ID du compte de service que vous avez créé à l'étape précédente. Assurez-vous qu'il s'agit du même compte que celui que vous avez utilisé lors de l'installation d'AlloyDB Omni. Cela inclut le suffixe complet PROJECT_ID.iam.gserviceaccount.com. Par exemple : my-service@my-project.iam.gserviceaccount.com.

      Vous pouvez également attribuer ce rôle au compte de service au niveau du projet. Pour en savoir plus, consultez Ajouter une association de stratégie Identity and Access Management.

Modèles d'embedding de texte avec prise en charge intégrée

Cette section explique comment enregistrer les points de terminaison de modèle pour lesquels la gestion des points de terminaison de modèle fournit une assistance intégrée.

Modèles d'embedding Vertex AI

La gestion des points de terminaison de modèle offre une compatibilité intégrée pour toutes les versions du modèle text-embedding-gecko de Vertex AI. Utilisez le nom qualifié pour définir la version du modèle sur textembedding-gecko@001 ou textembedding-gecko@002.

Étant donné que les ID de point de terminaison de modèle textembedding-gecko et textembedding-gecko@001 sont préenregistrés avec la gestion des points de terminaison de modèle, vous pouvez les utiliser directement comme ID de modèle. Pour ces modèles, l'extension configure automatiquement les fonctions de transformation par défaut.

Pour enregistrer la version du point de terminaison du modèle textembedding-gecko@002, procédez comme suit :

Pour AlloyDB Omni, assurez-vous de configurer AlloyDB Omni pour interroger les modèles Vertex AI basés dans le cloud.

  1. Créez et activez l'extension google_ml_integration.

  2. Connectez-vous à votre base de données à l'aide de psql.

  3. Créez et activez l'extension google_ml_integration.

  4. Appelez la fonction de création de modèle pour ajouter le point de terminaison du modèle 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.

Modèle d'embedding textuel Open AI

La gestion des points de terminaison de modèle offre une compatibilité intégrée avec le modèle text-embedding-ada-002 d'OpenAI.L'extension google_ml_integration configure automatiquement les fonctions de transformation par défaut et appelle le modèle distant.

L'exemple suivant ajoute le point de terminaison du modèle OpenAI text-embedding-ada-002.

  1. Connectez-vous à votre base de données à l'aide de psql.
  2. Créez et activez l'extension google_ml_integration.
  3. Ajoutez la clé API OpenAI en tant que secret à Secret Manager pour l'authentification.

  4. Appelez le secret stocké dans 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');

    Remplacez les éléments suivants :

    • SECRET_ID : ID secret que vous avez défini et qui est utilisé par la suite lors de l'enregistrement d'un point de terminaison de modèle (par exemple, key1).
    • SECRET_MANAGER_SECRET_ID : ID du secret défini dans Secret Manager lorsque vous avez créé le secret.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • VERSION_NUMBER : numéro de version de l'ID du secret.

  5. Appelez la fonction de création de modèle pour enregistrer le point de terminaison du modèle 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');

    Remplacez les éléments suivants :

    • MODEL_ID : ID unique du point de terminaison du modèle que vous définissez. Cet ID de modèle est référencé pour les métadonnées dont le point de terminaison du modèle a besoin pour générer des embeddings ou appeler des prédictions.
    • SECRET_ID : ID du secret que vous avez utilisé précédemment dans la procédure google_ml.create_sm_secret().

Pour générer des embeddings, découvrez comment générer des embeddings pour les points de terminaison de modèle avec prise en charge intégrée.

Autres modèles d'embedding de texte

Cette section explique comment enregistrer des points de terminaison de modèle d'embedding de texte hébergés sur mesure ou des points de terminaison de modèle d'embedding de texte fournis par des fournisseurs d'hébergement de modèles. En fonction des métadonnées de votre point de terminaison de modèle, vous devrez peut-être ajouter des fonctions de transformation, générer des en-têtes HTTP ou définir des points de terminaison.

Modèle d'embedding de texte hébergé sur mesure

Cette section explique comment enregistrer un point de terminaison de modèle hébergé personnalisé, créer des fonctions de transformation et, éventuellement, des en-têtes HTTP personnalisés. AlloyDB Omni est compatible avec tous les points de terminaison de modèles hébergés sur mesure, quel que soit leur emplacement.

L'exemple suivant ajoute le point de terminaison du modèle personnalisé custom-embedding-model hébergé par Cymbal. Les fonctions de transformation cymbal_text_input_transform et cymbal_text_output_transform permettent de transformer le format d'entrée et de sortie du modèle en format d'entrée et de sortie de la fonction de prédiction.

Pour enregistrer des points de terminaison de modèles d'embedding de texte hébergés sur mesure, procédez comme suit :

  1. Connectez-vous à votre base de données à l'aide de psql.

  2. Créez et activez l'extension google_ml_integration.

  3. Facultatif : Ajoutez la clé API en tant que secret à Secret Manager pour l'authentification.

  4. Appelez le secret stocké dans 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');

    Remplacez les éléments suivants :

    • SECRET_ID : ID secret que vous avez défini et qui est utilisé par la suite lors de l'enregistrement d'un point de terminaison de modèle (par exemple, key1).
    • SECRET_MANAGER_SECRET_ID : ID du secret défini dans Secret Manager lorsque vous avez créé le secret.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • VERSION_NUMBER : numéro de version de l'ID du secret.

  5. Créez les fonctions de transformation d'entrée et de sortie en fonction de la signature suivante pour la fonction de prédiction des points de terminaison du modèle d'embedding de texte. Pour savoir comment créer des fonctions de transformation, consultez Exemple de fonctions de transformation.

    Voici des exemples de fonctions de transformation spécifiques au point de terminaison du modèle d'embedding de texte 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. Appelez la fonction de création de modèle pour enregistrer le point de terminaison du modèle d'embedding personnalisé :

    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');

    Remplacez les éléments suivants :

    • MODEL_ID : Obligatoire. ID unique du point de terminaison du modèle que vous définissez (par exemple, custom-embedding-model). Cet ID de modèle est référencé pour les métadonnées dont le point de terminaison du modèle a besoin pour générer des embeddings ou appeler des prédictions.
    • REQUEST_URL : Obligatoire. Point de terminaison spécifique au modèle lors de l'ajout d'embeddings de texte personnalisés et de points de terminaison de modèle génériques (par exemple, https://cymbal.com/models/text/embeddings/v1).
    • MODEL_QUALIFIED_NAME : obligatoire si le point de terminaison de votre modèle utilise un nom qualifié. Nom complet si le point de terminaison du modèle comporte plusieurs versions.
    • SECRET_ID : ID du secret que vous avez utilisé précédemment dans la procédure google_ml.create_sm_secret().

Modèles OpenAI Text Embedding 3 Small et Large

Vous pouvez enregistrer les points de terminaison des modèles OpenAI text-embedding-3-small et text-embedding-3-large à l'aide de la fonction de prédiction d'embedding et des fonctions de transformation spécifiques au point de terminaison du modèle. L'exemple suivant montre comment enregistrer le point de terminaison du modèle text-embedding-3-small d'OpenAI.

Pour enregistrer le point de terminaison du modèle d'embedding text-embedding-3-small, procédez comme suit :

  1. Connectez-vous à votre base de données à l'aide de psql.
  2. Créez et activez l'extension google_ml_integration.
  3. Ajoutez la clé API OpenAI en tant que secret à Secret Manager pour l'authentification. Si vous avez déjà créé un secret pour un autre modèle OpenAI, vous pouvez le réutiliser.

  4. Appelez le secret stocké dans 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');

    Remplacez les éléments suivants :

    • SECRET_ID : ID secret que vous avez défini et qui est utilisé par la suite lors de l'enregistrement d'un point de terminaison de modèle.
    • SECRET_MANAGER_SECRET_ID : ID du secret défini dans Secret Manager lorsque vous avez créé le secret.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • VERSION_NUMBER : numéro de version de l'ID du secret.

  5. Créez les fonctions de transformation d'entrée et de sortie en fonction de la signature suivante pour la fonction de prédiction des modèles d'embedding de texte. Pour savoir comment créer des fonctions de transformation, consultez Exemple de fonctions de transformation. Pour en savoir plus sur les formats d'entrée et de sortie attendus par les points de terminaison de modèle OpenAI, consultez Embeddings.

    Vous trouverez ci-dessous des exemples de fonctions de transformation pour les points de terminaison de modèle d'embedding de texte OpenAI text-embedding-ada-002, text-embedding-3-small et 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. Appelez la fonction de création de modèle pour enregistrer le point de terminaison du modèle d'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');

    Remplacez les éléments suivants :

    • MODEL_ID : ID unique du point de terminaison du modèle que vous définissez (par exemple, openai-te-3-small). Cet ID de modèle est référencé pour les métadonnées dont le point de terminaison du modèle a besoin pour générer des embeddings ou appeler des prédictions.
    • SECRET_ID : ID du secret que vous avez utilisé précédemment dans la procédure google_ml.create_sm_secret().

Pour en savoir plus, consultez Générer des embeddings pour d'autres points de terminaison de modèles d'embedding de texte.

Modèles génériques

Cette section explique comment enregistrer n'importe quel point de terminaison de modèle générique disponible chez un fournisseur de modèles hébergés tel que Hugging Face, OpenAI, Vertex AI ou tout autre fournisseur. Cette section présente des exemples d'enregistrement d'un point de terminaison de modèle générique hébergé sur Hugging Face et d'un modèle gemini-pro générique de Vertex AI Model Garden, qui ne sont pas compatibles par défaut.

Vous pouvez enregistrer n'importe quel point de terminaison de modèle générique, à condition que l'entrée et la sortie soient au format JSON. En fonction des métadonnées du point de terminaison de votre modèle, vous devrez peut-être générer des en-têtes HTTP ou définir des points de terminaison.

Modèle générique sur Hugging Face

L'exemple suivant ajoute le point de terminaison du modèle de classification personnalisé facebook/bart-large-mnli hébergé sur Hugging Face.

  1. Connectez-vous à votre base de données à l'aide de psql.
  2. Créez et activez l'extension google_ml_integration.
  3. Ajoutez le jeton du porteur en tant que secret à Secret Manager pour l'authentification.

  4. Appelez le secret stocké dans 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');

    Remplacez les éléments suivants :

    • SECRET_ID : ID secret que vous avez défini et qui est utilisé par la suite lors de l'enregistrement d'un point de terminaison de modèle.
    • SECRET_MANAGER_SECRET_ID : ID du secret défini dans Secret Manager lorsque vous avez créé le secret.
    • PROJECT_ID : ID de votre projet Google Cloud .
    • VERSION_NUMBER : numéro de version de l'ID du secret.

  5. Appelez la fonction de création de modèle pour enregistrer le point de terminaison du modèle 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');

    Remplacez les éléments suivants :

    • MODEL_ID : ID unique du point de terminaison du modèle que vous définissez (par exemple, custom-classification-model). Cet ID de modèle est référencé pour les métadonnées dont le point de terminaison du modèle a besoin pour générer des embeddings ou appeler des prédictions.
    • REQUEST_URL : point de terminaison spécifique au modèle lors de l'ajout d'embeddings de texte personnalisés et de points de terminaison de modèle génériques (par exemple, https://api-inference.huggingface.co/models/facebook/bart-large-mnli).
    • MODEL_QUALIFIED_NAME : nom complet de la version du point de terminaison du modèle, par exemple facebook/bart-large-mnli.
    • SECRET_ID : ID du secret que vous avez utilisé précédemment dans la procédure google_ml.create_sm_secret().

Modèle Gemini

Assurez-vous de configurer AlloyDB Omni pour interroger les modèles Vertex AI basés sur le cloud.

L'exemple suivant ajoute le point de terminaison du modèle gemini-1.0-pro à partir de Vertex AI Model Garden.

  1. Connectez-vous à votre base de données à l'aide de psql.
  2. Créez et activez l'extension google_ml_integration.

  3. Appelez la fonction de création de modèle pour enregistrer le modèle 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');

    Remplacez les éléments suivants :

    • MODEL_ID : ID unique du point de terminaison du modèle que vous définissez (par exemple, gemini-1). Cet ID de modèle est référencé pour les métadonnées dont le point de terminaison du modèle a besoin pour générer des embeddings ou appeler des prédictions.
    • PROJECT_ID : ID de votre projet Google Cloud .

Pour en savoir plus, consultez Appeler des prédictions pour les points de terminaison de modèles génériques.

Étapes suivantes