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

MySQL | PostgreSQL | SQL Server

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 mysql.ml_create_model_registration() fonction, 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èle.

Connectez-vous à votre instance principale à l'aide d'un client mysql ou 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 à la base de données décrits dans la section Droits d'accès requis pour l'utilisateur de la 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 Agent Platform ou des points de terminaison de modèle hébergés dans Google Cloud.

Configurer l'authentification pour Agent Platform

Pour utiliser les points de terminaison de modèle Google Agent Platform, vous devez ajouter des autorisations Agent Platform 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 à Agent Platform, consultez Intégrer Cloud SQL à Agent Platform.

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

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 Agent Platform, vous pouvez stocker vos clés API ou vos jetons de support dans Secret Manager.

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

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

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 d'accès du secret sont utilisés dans la mysql.ml_create_sm_secret_registration() fonction SQL.
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 gcloud sql instances describe INSTANCE_NAME commande 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'embeddings textuels 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 Agent Platform

La gestion des points de terminaison de modèle offre une compatibilité intégrée pour toutes les versions des text-embedding-gecko, text-embedding et gemini-embedding modèles d' Agent Platform. 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 d'embedding Agent Platform sont compatibles par défaut avec la gestion des points de terminaison de modèle, 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 Agent Platform que vous interrogez se trouvent dans la même région.

Pour enregistrer le point de terminaison de 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'embeddings textuels 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 dans Google Cloud.

L'ajout de points de terminaison de modèle d'embedding textuel hébergés sur mesure 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èle génériques hébergés sur mesure implique éventuellement la génération d'en-têtes HTTP personnalisés et la définition de l'URL de la requête de modèle.

L'exemple suivant ajoute le modèle d'embedding textuel custom-embedding-model point de terminaison hébergé par Cymbal, qui est hébergé dans Google Cloud. Les fonctions de transformation cymbal_text_input_transform et cymbal_text_output_transform sont utilisées pour 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és sur mesure, procédez comme suit :

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 de 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 de secret défini dans Secret Manager lorsque vous avez créé le secret.
- PROJECT_ID : ID de votre Google Cloud projet.
- VERSION_NUMBER : numéro de version de l'ID de secret.
Remarque : Secret Manager génère un en-tête Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER pour l'authentification par défaut. Si ce format correspond au format de jeton de support d'autorisation de votre point de terminaison de modèle, vous n'avez pas besoin de générer d'en-têtes d'authentification à l'aide de la fonction de génération d'en-tête.

Créez les fonctions de transformation d'entrée et de sortie en fonction de la signature suivante pour la fonction de prédiction pour les points de terminaison des modèles d'embeddings textuels. 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 de modèle d'embedding textuel 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 ;

Appelez la fonction de création de modèle pour enregistrer le point de terminaison de 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 de 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 de 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 utilisé lors de l'ajout de points de terminaison de modèle génériques et d'embeddings textuels personnalisés (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èle n'est pas compatible avec les adresses IP externes.
MODEL_QUALIFIED_NAME : obligatoire si votre point de terminaison de modèle utilise un nom qualifié. Nom complet si le point de terminaison du modèle comporte plusieurs versions.
SECRET_ID: ID de secret que vous avez utilisé précédemment dans la procédure mysql.ml_create_sm_secret_registration().

Modèles génériques

Cette section explique comment enregistrer un point de terminaison de modèle gemini-flash générique à partir d'Agent Platform Model Garden, qui est pré-enregistré dans le catalogue par défaut. Vous pouvez enregistrer n'importe quel point de terminaison de modèle générique hébergé dans Google Cloud.

Cloud SQL n'est compatible qu'avec les points de terminaison de modèle disponibles via Agent Platform Model Garden et les points de terminaison de modèle hébergés dans des réseaux dans Google Cloud.

Modèle Gemini

L'exemple suivant utilise le point de terminaison de modèle gemini-2.5-flash d'Agent Platform Model Garden.

Pour enregistrer le point de terminaison de 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);