Enregistrer et appeler des modèles d'IA distants à l'aide de la gestion des points de terminaison de modèle

Cette page explique comment appeler des prédictions ou générer des embeddings à l'aide d'un modèle, puis enregistrer le point de terminaison du modèle avec la gestion des points de terminaison de modèle.

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

Avant de commencer

• Configurez l'authentification en fonction du fournisseur de modèles.

• Connectez-vous à votre instance principale à l'aide d'un client mysql ou de Cloud SQL Studio.

• Assurez-vous de vous connecter à la base de données en tant qu'utilisateur de base de données MySQL disposant des droits d'accès décrits dans Droits d'accès requis pour les utilisateurs de base de données.

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 hébergés dans Trusted Cloud by S3NS.

Configurer l'authentification pour Vertex AI

Pour utiliser les points de terminaison des modèles Google Vertex AI, vous devez ajouter des autorisations Vertex AI au compte de service Cloud SQL basé sur IAM que vous utilisez pour vous connecter à la base de données. Pour en savoir plus sur l'intégration à Vertex AI, consultez Intégrer Cloud SQL à Vertex AI.

Configurer l'authentification pour les modèles hébergés personnalisés

Cette section explique comment configurer l'authentification si vous utilisez Secret Manager. Pour tous les modèles, à l'exception des points de terminaison de modèle Vertex AI, vous pouvez stocker vos clés API ou vos jetons du porteur dans Secret Manager.

Si le point de terminaison de votre modèle ne gère pas l'authentification via Secret Manager, cette section est facultative. Par exemple, si le point de terminaison de votre modèle utilise des en-têtes HTTP pour transmettre des informations d'authentification ou n'utilise pas du tout l'authentification, ne suivez pas les étapes de cette section.

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

1. Créez un 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 mysql.ml_create_sm_secret_registration().

2. Accordez à l'instance Cloud SQL les autorisations nécessaires pour accéder au secret.

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

   Remplacez les éléments suivants :

   • SECRET_ID : ID du secret dans Secret Manager.
   • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service Cloud SQL basé sur IAM. Pour trouver cette adresse e-mail, utilisez la commande gcloud sql instances describe INSTANCE_NAME et remplacez INSTANCE_NAME par le nom de l'instance. La valeur qui s'affiche à côté du paramètre serviceAccountEmailAddress est l'adresse e-mail.

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

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

Modèles d'embedding Vertex AI

La gestion des points de terminaison de modèle offre une compatibilité intégrée avec toutes les versions des modèles text-embedding-gecko, text-embedding et gemini-embedding 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 points de terminaison de modèles d'embedding Vertex AI sont compatibles par défaut avec la gestion des points de terminaison de modèles, vous pouvez utiliser n'importe lequel d'entre eux directement comme ID de modèle. Pour ces modèles, la fonction d'embedding effectue automatiquement la transformation des entrées et des sorties.

Assurez-vous que l'instance Cloud SQL et le modèle Vertex AI que vous interrogez se trouvent dans la même région.

Pour enregistrer le point de terminaison du modèle gemini-embedding-001, appelez la fonction ml_create_model_registration :

  CALL
    mysql.ml_create_model_registration(
      'gemini-embedding-001',
      'publishers/google/models/gemini-embedding-001',
      'google','text_embedding', 'gemini-embedding-001',
      'AUTH_TYPE_CLOUDSQL_SERVICE_AGENT_IAM',
       NULL,
      'mysql.cloudsql_ml_text_embedding_input_transform',
      'mysql.cloudsql_ml_text_embedding_output_transform', NULL);

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

Cette section explique comment enregistrer des points de terminaison de modèle personnalisés hébergés dans des réseaux au sein de Trusted Cloud by S3NS.

L'ajout de points de terminaison de modèles d'embedding de texte hébergés personnalisés implique la création de fonctions de transformation et, éventuellement, d'en-têtes HTTP personnalisés. En revanche, l'ajout de points de terminaison de modèles génériques hébergés de manière personnalisée implique de générer éventuellement des en-têtes HTTP personnalisés et de définir l'URL de la requête du modèle.

L'exemple suivant ajoute le point de terminaison du modèle d'embedding de texte custom-embedding-model hébergé par Cymbal, qui est hébergé dans Trusted Cloud by S3NS. 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. Appelez le secret stocké dans Secret Manager :

   CALL
     mysql.ml_create_sm_secret_registration(
       'SECRET_ID',
       '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 Trusted Cloud by S3NS .
   • VERSION_NUMBER : numéro de version de l'ID du secret.

2. 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
   DELIMITER $$
   CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
   RETURNS JSON
   DETERMINISTIC
   
   BEGIN
     RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
   END $$
   
   -- Output Transform Function corresponding to the custom model endpoint
   CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
   RETURNS BLOB
   DETERMINISTIC
   
   BEGIN
     RETURN STRING_TO_VECTOR(
            JSON_EXTRACT(
                 content,
                 '$.predictions[0].embeddings.values'
               )
        );
   
   END $$
   DELIMITER ;
   

3. Appelez la fonction de création de modèle pour enregistrer le point de terminaison du modèle d'embedding personnalisé :

   CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'REQUEST_URL',
        'custom',
        'text_embedding',
        'MODEL_QUALIFIED_NAME',
        'auth_type_secret_manager',
        'SECRET_ID'
        'database_name.cymbal_text_input_transform',
        'database_name.cymbal_text_output_transform', NULL);

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). Assurez-vous que le point de terminaison du modèle est accessible via une adresse IP interne. La gestion des points de terminaison de modèles n'est pas compatible avec les adresses IP externes.
• 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 mysql.ml_create_sm_secret_registration().

Modèles génériques

Cloud SQL n'est compatible qu'avec les points de terminaison de modèles disponibles dans Vertex AI Model Garden et les points de terminaison de modèles hébergés dans des réseaux situés dans Trusted Cloud by S3NS.

Modèle Gemini

L'exemple suivant utilise le point de terminaison du modèle gemini-2.5-flash de Vertex AI Model Garden.

Pour enregistrer le point de terminaison du modèle gemini-2.5-flash, appelez la fonction mysql.ml_create_model_registration :

    CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-flash:streamGenerateContent',
        'google',
        'auth_type_cloudsql_service_agent_iam',
        NULL, NULL, NULL, NULL);

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 Trusted Cloud by S3NS .

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

Étapes suivantes

• En savoir plus sur la documentation de référence sur la gestion des points de terminaison de modèle