Présentation de l'enregistrement et de l'appel de modèles d'IA distants dans Cloud SQL

Cette page explique comment enregistrer un point de terminaison de modèle d'IA et appeler des prédictions avec la gestion des points de terminaison de modèle dans Cloud SQL. Pour utiliser des modèles d'IA dans des environnements de production, consultez Générer et gérer des embeddings vectoriels.

Présentation

La gestion des points de terminaison de modèles vous permet d'enregistrer un point de terminaison de modèle, de gérer les métadonnées de point de terminaison de modèle dans votre instance Cloud SQL, puis d'interagir avec les modèles à l'aide de requêtes SQL. Vous pouvez utiliser ces modèles pour générer des embeddings vectoriels ou appeler des prédictions.

Vous pouvez enregistrer les types de modèles suivants à l'aide de la gestion des points de terminaison de modèle :

  • Modèles d'embedding textuel Vertex AI
  • Modèles d'embedding de texte hébergés sur mesure dans des réseaux au sein de Google Cloud.

  • Modèles génériques avec une API basée sur JSON. Voici quelques exemples de ces modèles :

    • Modèle gemini-flash de Vertex AI Model Garden
    • Modèle open_ai pour les modèles OpenAI
    • Modèles hébergés dans des réseaux au sein de Google Cloud

Fonctionnement

Vous pouvez utiliser la gestion des points de terminaison de modèle pour enregistrer un point de terminaison de modèle qui respecte les conditions suivantes :

  • Les entrées et sorties du modèle sont compatibles avec le format JSON.
  • Vous pouvez utiliser le protocole REST pour appeler le modèle.

Lorsque vous enregistrez un point de terminaison de modèle avec la gestion des points de terminaison de modèle, la gestion des points de terminaison de modèle enregistre chaque point de terminaison avec un ID de modèle unique comme référence au modèle. Vous pouvez utiliser cet ID de modèle pour interroger des modèles, comme suit :

  • Générez des embeddings pour traduire les requêtes de texte en vecteurs numériques. Vous pouvez stocker les embeddings générés sous forme de données vectorielles lorsque vous activez la compatibilité avec les embeddings vectoriels sur votre instance. Pour en savoir plus, consultez Activer et désactiver les embeddings vectoriels sur votre instance.

  • Appelez des prédictions pour appeler un modèle à l'aide de SQL dans une transaction.

Pour enregistrer et appeler des modèles d'IA à distance avec votre instance Cloud SQL, vous devez installer la version de maintenance MYSQL_VERSION.R20250531.01_14 ou ultérieure. Si votre instance exécute une version de maintenance antérieure à MYSQL_VERSION.R20250531.01_14, vous ne pouvez utiliser que les fonctions suivantes, comme indiqué dans l'intégration de Cloud SQL et Vertex AI.

Pour mettre à niveau votre instance vers la version de maintenance MYSQL_VERSION.R20250531.01_14 ou ultérieure, consultez Maintenance en libre-service. Une fois votre instance mise à niveau, vous pouvez utiliser les fonctions suivantes :

De plus, vous pouvez utiliser les fonctions suivantes avec votre fournisseur de modèles enregistré :

  • mysql.ml_embedding() : génère des embeddings de texte.
  • mysql.ml_predict_row() : génère des prédictions lorsque vous appelez des modèles génériques compatibles avec les formats d'entrée et de sortie JSON.

Droits d'utilisateur de base de données requis

Pour enregistrer et appeler des modèles d'IA à distance, vous devez être connecté en tant qu'utilisateur de base de données MySQL disposant des droits SELECT et EXECUTE sur mysql.*.

Par défaut, tout utilisateur disposant du rôle cloudsqlsuperuser dispose de ces droits ou peut créer un utilisateur et lui accorder les droits requis.

Pour en savoir plus sur le rôle cloudsqlsuperuser dans Cloud SQL, consultez Droits d'utilisateur de MySQL 8.0 et Droits d'utilisateur de MySQL 8.4.

Concepts clés

Avant de commencer à utiliser la gestion des points de terminaison de modèle, comprenez les concepts nécessaires pour vous connecter aux modèles et les utiliser.

Fournisseur de modèles

Le fournisseur de modèles est le fournisseur d'hébergement de modèles compatible. Le tableau suivant indique la valeur du fournisseur de modèle que vous devez définir en fonction du fournisseur de modèle que vous utilisez :

Fournisseur de modèles Définir la fonction sur…
Vertex AI (inclut Gemini) google
Anthropic anthropic
Hugging Face hugging_face
OpenAI open_ai
Autres modèles hébergés en dehors de Vertex AI,
Anthropic, Hugging Face et OpenAI		 custom

Le fournisseur de modèle par défaut est custom.

Types de modèles

Les types de modèles sont les types de modèles d'IA. Lorsque vous enregistrez un point de terminaison de modèle, vous pouvez définir les types de modèles text_embedding ou generic pour le point de terminaison.

Si vous utilisez Vertex AI comme fournisseur de modèles, vous n'avez pas besoin d'enregistrer de point de terminaison de modèle, car les points de terminaison sont compatibles automatiquement. Par défaut, avec Vertex AI, vous utilisez le modèle text-embedding-005.

Autres modèles d'embedding de texte
Pour les autres modèles d'embedding de texte, vous devez créer des fonctions de transformation pour gérer les formats d'entrée et de sortie compatibles avec le modèle. Vous pouvez également utiliser la fonction de génération d'en-têtes HTTP qui génère les en-têtes personnalisés requis par votre modèle.

Le type de modèle pour ces modèles est text_embedding.

Modèles génériques
La gestion des points de terminaison de modèle permet également d'enregistrer tous les autres types de modèles, à l'exception des modèles d'embeddings textuels.
Pour appeler des prédictions pour des modèles génériques, utilisez la fonction mysql.ml_predict_row(). Vous pouvez définir des métadonnées de point de terminaison de modèle, telles qu'un point de terminaison de requête et des en-têtes HTTP spécifiques à votre modèle.
Vous ne pouvez pas transmettre de fonctions de transformation lorsque vous enregistrez un point de terminaison de modèle générique. Assurez-vous que, lorsque vous appelez des prédictions, l'entrée de la fonction est au format JSON et que vous analysez la sortie JSON pour obtenir la sortie finale.
Le type de modèle pour ces modèles est generic. Étant donné que generic est le type de modèle par défaut, si vous enregistrez des points de terminaison de modèle pour ce type, la définition du type de modèle est facultative.
Avec Vertex AI, la gestion des points de terminaison de modèle inclut une assistance préenregistrée pour le modèle gemini-2.5-flash.

Méthodes d'authentification

Vous pouvez activer la compatibilité avec les embeddings vectoriels dans votre instance Cloud SQL pour MySQL, puis spécifier différentes méthodes d'authentification pour accéder à votre modèle. La configuration de ces méthodes est facultative et n'est requise que si vous devez vous authentifier pour accéder à votre modèle.

Pour les modèles Vertex AI, le compte de service Cloud SQL est utilisé pour l'authentification. Pour les autres modèles, la clé API ou le jeton du porteur stockés en tant que secret dans Secret Manager peuvent être utilisés avec la fonction SQL mysql.ml_create_sm_secret_registration().

Le tableau suivant présente les méthodes d'authentification que vous pouvez définir :

Méthode d'authentification Définir la fonction sur… Fournisseur de modèles
Agent de service Cloud SQL auth_type_cloudsql_service_agent_iam Fournisseur Vertex AI
Secret Manager auth_type_secret_manager Modèles hébergés en dehors de Vertex AI

Fonctions de prédiction

mysql.ml_embedding()
Appelle un point de terminaison de modèle d'embedding de texte enregistré pour générer des embeddings. Il inclut une compatibilité intégrée avec tous les modèles d'embedding de Vertex AI.
Pour les modèles d'embedding de texte sans prise en charge intégrée, les paramètres d'entrée et de sortie sont propres à un modèle et doivent être transformés pour que la fonction appelle le modèle. Créez une fonction de transformation d'entrée pour transformer l'entrée de la fonction de prédiction en entrée spécifique au modèle, et une fonction de transformation de sortie pour transformer la sortie spécifique au modèle en sortie de la fonction de prédiction.
mysql.ml_predict_row()
Appelle un point de terminaison de modèle générique enregistré, si le point de terminaison est compatible avec les API basées sur JSON pour appeler des prédictions.

Fonctions de transformation

Les fonctions de transformation modifient l'entrée dans un format que le modèle comprend et convertissent la réponse du modèle au format attendu par la fonction de prédiction. Les fonctions de transformation sont utilisées lors de l'enregistrement du point de terminaison du modèle text-embedding sans prise en charge intégrée. La signature des fonctions de transformation dépend de la fonction de prédiction pour le type de modèle.

Vous ne pouvez pas utiliser de fonctions de transformation lorsque vous enregistrez un point de terminaison de modèle generic.

Vous trouverez ci-dessous les signatures de la fonction de prédiction pour les modèles d'embedding de texte :

// define custom model specific input/output transform functions.
CREATE FUNCTION IF NOT EXISTS input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

// the returned BLOB should be of type VECTOR
CREATE FUNCTION IF NOT EXISTS output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

Pour savoir comment créer des fonctions de transformation, consultez Exemple de fonctions de transformation.

Fonction de génération d'en-tête HTTP

La fonction de génération d'en-tête HTTP génère la sortie sous forme de paires clé/valeur JSON qui sont utilisées comme en-têtes HTTP. La signature de la fonction de prédiction définit les signatures de la fonction de génération d'en-tête.

L'exemple suivant montre la signature de la fonction de prédiction mysql.ml_embedding() :

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON DETERMINISTIC;

Pour la fonction de prédiction mysql.ml_predict_row(), la signature est la suivante :

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON DETERMINISTIC;

Pour savoir comment créer une fonction de génération d'en-tête, consultez Exemple de fonction de génération d'en-tête.

Limites

  • Lorsque vous exécutez l'une des fonctions d'enregistrement de modèle ou de gestion des secrets, vous validez implicitement toutes les transactions ouvertes dans la session. Les fonctions de prédiction n'effectuent pas de commit implicite des transactions.

  • Si vous exportez ou importez votre base de données avec mysqldump, le catalogue de points de terminaison de modèle n'est pas exporté.

  • Le nom d'une base de données utilisateur contenant des fonctions de transformation ne peut pas comporter de point ('.'). Par exemple, une base de données appelée my.sql n'est pas acceptée.

  • La gestion des points de terminaison de modèle n'est disponible que pour Cloud SQL pour MySQL version 8.0.36 et ultérieures.

Étapes suivantes