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.

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. Vérifiez que l'option de base de données google_ml_integration.enable_model_support est définie sur on pour une instance. Pour en savoir plus sur la configuration des options de base de données, consultez Configurer des options de base de données.

  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 IF NOT EXISTS 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();

  6. Assurez-vous que la connectivité sortante est activée.

Configurer l'authentification

Les sections suivantes expliquent comment configurer l'authentification avant d'enregistrer un point de terminaison de modèle.

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 à l'aide de 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 si votre point de terminaison de modèle utilise des en-têtes HTTP pour transmettre les informations d'authentification ou n'utilise pas du tout l'authentification.

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 chemin secret est utilisé 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_NAME' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"

    Remplacez les éléments suivants :

    • SECRET_NAME : nom 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.

Configurer l'authentification à l'aide d'en-têtes

L'exemple suivant montre comment configurer l'authentification à l'aide d'une fonction qui renvoie un objet JSON contenant les en-têtes requis pour envoyer une requête au modèle d'intégration.

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

Remplacez les éléments suivants :

  • HEADER_GEN_FUNCTION : nom de la fonction de génération d'en-tête que vous pouvez utiliser lors de l'enregistrement d'un modèle.
  • API_KEY : clé API du fournisseur de modèles.

Modèles d'embedding de texte

Cette section explique comment enregistrer des points de terminaison de modèle avec la gestion des points de terminaison de modèle.

La gestion des points de terminaison de modèle est compatible avec certains modèles d'embedding de texte et Vertex AI génériques en tant que points de terminaison de modèle préenregistrés. Vous pouvez utiliser directement l'ID du modèle pour générer des embeddings ou appeler des prédictions, en fonction du type de modèle. Pour en savoir plus sur les modèles préenregistrés compatibles, consultez Modèles Vertex AI préenregistrés.

Par exemple, pour appeler le modèle textembedding-gecko préenregistré, vous pouvez appeler directement le modèle à l'aide de la fonction d'intégration :

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

De même, pour appeler le modèle gemini-1.5-pro:generateContent préenregistré, vous pouvez appeler directement le modèle à l'aide de la fonction de prédiction :

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

Pour générer des embeddings, consultez Générer des embeddings pour les points de terminaison de modèles préenregistrés. Pour appeler des prédictions, découvrez comment appeler des prédictions pour les points de terminaison de modèles préenregistrés.

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

La gestion des points de terminaison de modèle offre une compatibilité intégrée pour certains modèles de Vertex AI et d'OpenAI. Pour obtenir la liste des modèles compatibles, consultez Modèles compatibles.

Pour les modèles avec prise en charge intégrée, vous pouvez définir le nom qualifié comme nom qualifié du modèle et spécifier l'URL de la requête. La gestion des points de terminaison de modèle identifie automatiquement le modèle et configure les fonctions de transformation par défaut.

Modèles d'embedding Vertex AI

Les étapes suivantes montrent comment enregistrer des modèles Vertex AI avec prise en charge intégrée. Le point de terminaison du modèle text-embedding-005 et text-multilingual-embedding-002 est utilisé comme exemple.

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

    text-embedding-005 

      CALL
    google_ml.create_model(
      model_id => 'text-embedding-005',
      model_request_url => 'publishers/google/models/text-embedding-005',
      model_provider => 'google',
      model_qualified_name => 'text-embedding-005',
      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');

L'URL de la requête générée par la fonction fait référence au projet associé au compte de service AlloyDB Omni. Si vous souhaitez faire référence à un autre projet, assurez-vous de spécifier explicitement model_request_url.

Si le modèle est stocké dans un autre projet et une autre région que votre cluster AlloyDB, définissez l'URL de la requête sur projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID, où REGION_ID correspond à la région dans laquelle votre modèle est hébergé et MODEL_ID au nom qualifié du modèle.

De plus, attribuez le rôle Utilisateur Vertex AI (roles/aiplatform.user) au compte de service du projet dans lequel AlloyDB Omni est installé afin que le modèle hébergé dans l'autre projet soit accessible.

Modèle d'embedding textuel Open AI

L'extension google_ml_integration configure automatiquement les fonctions de transformation par défaut et appelle les modèles OpenAI à distance. Pour obtenir la liste des modèles OpenAI compatibles, consultez Modèles compatibles.

L'exemple suivant ajoute le point de terminaison du modèle OpenAI text-embedding-ada-002. Vous pouvez enregistrer les points de terminaison des modèles OpenAI text-embedding-3-small et text-embedding-3-large en suivant les mêmes étapes et en définissant les noms qualifiés de modèle spécifiques aux modèles.

  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.

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. Tous les points de terminaison de modèles hébergés personnalisés sont acceptés, quel que soit leur emplacement d'hébergement.

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 génériques

Cette section explique comment enregistrer un 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, Anthropic 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, d'un modèle gemini-pro générique de Vertex AI Model Garden et du point de terminaison de modèle claude-haiku.

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 URL de requête.

Pour en savoir plus sur les modèles génériques préenregistrés et les modèles avec prise en charge intégrée, consultez Modèles compatibles.

Modèle Gemini

Étant donné que certains modèles gemini-pro sont préenregistrés, vous pouvez appeler directement l'ID du modèle pour appeler les prédictions. Assurez-vous de configurer AlloyDB Omni pour interroger les modèles Vertex AI basés sur le cloud.

L'exemple suivant utilise le point de terminaison du modèle gemini-1.5-pro:generateContent 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 des prédictions à l'aide de l'ID du modèle préenregistré :

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

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 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. 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 => 'hugging_face',
    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 générique Anthropic

L'exemple suivant ajoute le point de terminaison du modèle claude-3-opus-20240229. La gestion des points de terminaison de modèle fournit la fonction d'en-tête requise pour enregistrer les modèles Anthropic.

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

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

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

    Secret Manager

    1. Ajoutez le jeton du porteur en tant que secret à Secret Manager pour l'authentification.

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

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

      Remplacez les éléments suivants :

      • MODEL_ID : ID unique du point de terminaison du modèle que vous définissez (par exemple, anthropic-opus). 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.anthropic.com/v1/messages).

    En-tête d'autorisation

    1. Utilisez la fonction de génération d'en-tête par défaut google_ml.anthropic_claude_header_gen_fn ou créez une fonction de génération d'en-tête.

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

      Remplacez les éléments suivants :

      • ANTHROPIC_API_KEY : clé API Anthropic.
      • ANTHROPIC_VERSION (facultatif) : version spécifique du modèle que vous souhaitez utiliser (par exemple, 2023-06-01).

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

      Remplacez les éléments suivants :

      • MODEL_ID : ID unique du point de terminaison du modèle que vous définissez (par exemple, anthropic-opus). 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.anthropic.com/v1/messages).

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

Étapes suivantes