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

Pour appeler des prédictions ou générer des représentations vectorielles continues à l'aide d'un modèle, enregistrez le point de terminaison du modèle dans la gestion des points de terminaison du 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 du 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 du 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 non super-administrateur de gérer les métadonnées de 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.

  5. Activez la gestion des points de terminaison du modèle dans 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 par 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 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 vos jetons d'accès dans Secret Manager. Cette étape est facultative si le point de terminaison de votre modèle ne gère pas l'authentification via Secret Manager (par exemple, s'il utilise des en-têtes HTTP pour transmettre des 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 porteur, procédez comme suit:

  1. Créez le secret dans Secret Manager. Pour en savoir plus, consultez la section Créer un secret et y accéder.

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

  2. Accordez des autorisations au cluster AlloyDB pour qu'il puisse accéder 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 PROJECT_ID.iam.gserviceaccount.com complet. 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 liaison de stratégie Identity and Access Management.

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

Cette section explique comment enregistrer des points de terminaison de modèle pour lesquels la gestion des points de terminaison de modèle est compatible.

Modèles d'embedding Vertex AI

La gestion des points de terminaison du modèle est compatible avec toutes les versions du modèle text-embedding-gecko par 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 l'ID de point de terminaison du modèle textembedding-gecko et textembedding-gecko@001 est préenregistré avec la gestion des points de terminaison du 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 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 du modèle est compatible 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 les appels au 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 de secret que vous définissez et qui est ensuite utilisé 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 représentations vectorielles continues 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'embeddings de texte

Cette section explique comment enregistrer un point de terminaison de modèle d'embedding de texte hébergé en mode personnalisé 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é en interne

Cette section explique comment enregistrer un point de terminaison de modèle hébergé par l'utilisateur, ainsi que 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èle hébergés en mode personnalisé, quel que soit l'emplacement de l'hébergement.

L'exemple suivant ajoute le point de terminaison de 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èle d'embedding textuel hébergé en interne, 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 de secret que vous définissez et qui est ensuite utilisé 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 en savoir plus sur la création de 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'embeddings textuels 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. Identifiant 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 représentations vectorielles continues ou appeler des prédictions.
    • REQUEST_URL : Obligatoire. Point de terminaison spécifique au modèle lorsque vous ajoutez des représentations vectorielles continues de texte personnalisées et des 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 au cas où 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 de petite et grande taille

Vous pouvez enregistrer les points de terminaison de modèle OpenAI text-embedding-3-small et text-embedding-3-large à l'aide de la fonction de prédiction d'encapsulation 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 OpenAI.

Pour enregistrer le point de terminaison du modèle d'encapsulation 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 définissez et qui est ensuite utilisé 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 en savoir plus sur la création de 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 la section Embeddings.

    Vous trouverez ci-dessous des exemples de fonctions de transformation pour les points de terminaison des modèles 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 représentations vectorielles continues 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, découvrez comment générer des embeddings pour d'autres points de terminaison de modèles d'embeddings textuels.

Modèles génériques

Cette section explique comment enregistrer n'importe quel point de terminaison de modèle générique disponible sur un fournisseur de modèles hébergé 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 à partir de Vertex AI Model Garden, qui n'est pas compatible avec la prise en charge intégrée.

Vous pouvez enregistrer n'importe quel point de terminaison de modèle générique tant que l'entrée et la sortie sont au format JSON. En fonction des métadonnées de votre point de terminaison de 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 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 définissez et qui est ensuite utilisé 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 représentations vectorielles continues ou appeler des prédictions.
    • REQUEST_URL: point de terminaison spécifique au modèle lorsque vous ajoutez un embedding de texte personnalisé et des 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 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 représentations vectorielles continues ou appeler des prédictions.
    • PROJECT_ID: ID de votre projet Google Cloud .

Pour en savoir plus, découvrez comment appeler des prédictions pour des points de terminaison de modèle génériques.

Étape suivante