Información general sobre el registro y la llamada de modelos de IA remotos en Cloud SQL

En esta página se describe cómo registrar un endpoint de modelo de IA e invocar predicciones con la gestión de endpoints de modelos en Cloud SQL. Para usar modelos de IA en entornos de producción, consulta Generar y gestionar incrustaciones de vectores.

Información general

La gestión de endpoints de modelos te permite registrar un endpoint de modelo, gestionar los metadatos de endpoints de modelos en tu instancia de Cloud SQL y, a continuación, interactuar con los modelos mediante consultas SQL. Puedes usar estos modelos para generar incrustaciones de vectores o invocar predicciones.

Puede registrar los siguientes tipos de modelos mediante la gestión de endpoints de modelos:

  • Modelos de inserciones de texto de Vertex AI.
  • Modelos de inserción de texto alojados de forma personalizada en redes de Google Cloud.

  • Modelos genéricos con una API basada en JSON. Estos son algunos ejemplos de estos modelos:

    • El modelo gemini-flash de Model Garden de Vertex AI
    • El modelo open_ai para los modelos de OpenAI
    • Modelos alojados en redes de Google Cloud

Cómo funciona

Puedes usar la gestión de endpoints de modelos para registrar un endpoint de modelo que cumpla los siguientes requisitos:

  • La entrada y la salida del modelo admiten el formato JSON.
  • Puedes usar el protocolo REST para llamar al modelo.

Cuando registras un endpoint de modelo con la gestión de endpoints de modelos, esta registra cada endpoint con un ID de modelo único como referencia al modelo. Puede usar este ID de modelo para consultar modelos, como se indica a continuación:

  • Genera incrustaciones para traducir las peticiones de texto a vectores numéricos. Puedes almacenar las inserciones generadas como datos vectoriales cuando habilites la compatibilidad con inserciones de vectores en tu instancia. Para obtener más información, consulta el artículo Habilitar e inhabilitar las inserciones vectoriales en tu instancia.

  • Invoca predicciones para llamar a un modelo mediante SQL en una transacción.

Para registrar y llamar a modelos de IA remotos con tu instancia de Cloud SQL, esta debe tener instalada la versión de mantenimiento MYSQL_VERSION.R20250531.01_14 o una posterior. Si tu instancia ejecuta una versión de mantenimiento anterior a MYSQL_VERSION.R20250531.01_14, solo puedes usar las siguientes funciones, tal como se documenta en la integración de Cloud SQL y Vertex AI.

Para actualizar tu instancia a la versión de mantenimiento MYSQL_VERSION.R20250531.01_14 o posterior, consulta Mantenimiento de autoservicio. Después de actualizar la instancia, puede usar las siguientes funciones:

Además, puedes usar las siguientes funciones con tu proveedor de modelos registrado:

Privilegios de usuario de la base de datos necesarios

Para registrar y llamar a modelos de IA remotos, debes iniciar sesión como usuario de base de datos MySQL al que se le hayan concedido los privilegios SELECT y EXECUTE en mysql.*.

De forma predeterminada, cualquier usuario con el rol cloudsqlsuperuser tiene estos privilegios o puede crear un usuario y concederle los privilegios necesarios.

Para obtener más información sobre el rol cloudsqlsuperuser en Cloud SQL, consulta los artículos Privilegios de usuario de MySQL 8.0 y Privilegios de usuario de MySQL 8.4.

Conceptos clave

Antes de empezar a usar la gestión de endpoints de modelos, familiarízate con los conceptos necesarios para conectarte a los modelos y usarlos.

Proveedor del modelo

Proveedor de modelos es el proveedor de alojamiento de modelos admitido. En la siguiente tabla se muestra el valor del proveedor del modelo que debe definir en función del proveedor del modelo que utilice:

Proveedor del modelo Definir en la función como…
Vertex AI (incluye Gemini) google
Anthropic anthropic
Hugging Face hugging_face
OpenAI open_ai
Otros modelos alojados fuera de Vertex AI,
Anthropic, Hugging Face y OpenAI		 custom

El proveedor de modelos predeterminado es custom.

Tipos de modelo

Los tipos de modelos son los tipos de modelos de IA. Cuando registras un endpoint de modelo, puedes definir los tipos de modelo text_embedding o generic para el endpoint.

Si usas Vertex AI como proveedor de modelos, no tienes que registrar ningún endpoint de modelo, ya que los endpoints se admiten automáticamente. De forma predeterminada, con Vertex AI, se usa el modelo text-embedding-005.

Otros modelos de inserciones de texto
En el caso de otros modelos de inserción de texto, debes crear funciones de transformación para gestionar los formatos de entrada y salida que admite el modelo. También puedes usar la función de generación de encabezados HTTP que genera los encabezados personalizados que necesita tu modelo.

El tipo de modelo de estos modelos es text_embedding.

Modelos genéricos
La gestión de endpoints de modelos también admite el registro de todos los demás tipos de modelos, excepto los modelos de inserción de texto. Para invocar predicciones de modelos genéricos, usa la función mysql.ml_predict_row(). Puedes definir metadatos de puntos de conexión de modelos, como un punto de conexión de solicitud y encabezados HTTP específicos de tu modelo.
No puedes transferir funciones de transformación al registrar un endpoint de modelo genérico. Asegúrate de que, cuando invoques las predicciones, la entrada de la función esté en formato JSON y de que analices la salida JSON para obtener la salida final.
El tipo de modelo de estos modelos es generic. Como generic es el tipo de modelo predeterminado, si registra endpoints de modelo de este tipo, no es necesario definir el tipo de modelo.
Con Vertex AI, la gestión de endpoints de modelos incluye asistencia pre-registrada para el modelo gemini-2.5-flash.

Métodos de autenticación

Puedes habilitar la compatibilidad con inserciones vectoriales en tu instancia de Cloud SQL para MySQL y, a continuación, especificar diferentes métodos de autenticación para acceder a tu modelo. Configurar estos métodos es opcional y solo es necesario si tienes que autenticarte para acceder a tu modelo.

En el caso de los modelos de Vertex AI, la cuenta de servicio de Cloud SQL se usa para la autenticación. En otros modelos, la clave de API o el token de portador que se almacena como secreto en Secret Manager se puede usar con la función SQL mysql.ml_create_sm_secret_registration().

En la siguiente tabla se muestran los métodos de autenticación que puedes configurar:

Método de autenticación Definir en la función como… Proveedor del modelo
Agente de servicio de Cloud SQL auth_type_cloudsql_service_agent_iam Proveedor de Vertex AI
Secret Manager auth_type_secret_manager Modelos alojados fuera de Vertex AI

Funciones de predicción

mysql.ml_embedding()
Llama a un endpoint de modelo de incrustaciones de texto registrado para generar incrustaciones. Incluye compatibilidad integrada con todos los modelos de inserciones de Vertex AI.
En el caso de los modelos de inserción de texto que no tienen asistencia integrada, los parámetros de entrada y salida son únicos para cada modelo y deben transformarse para que la función pueda llamar al modelo. Crea una función de transformación de entrada para transformar la entrada de la función de predicción en la entrada específica del modelo y una función de transformación de salida para transformar la salida específica del modelo en la salida de la función de predicción.
mysql.ml_predict_row()
Llama a un endpoint de modelo genérico registrado si el endpoint admite APIs basadas en JSON para invocar predicciones.

Transformar funciones

Las funciones de transformación modifican la entrada a un formato que el modelo entiende y convierten la respuesta del modelo al formato que espera la función de predicción. Las funciones de transformación se usan al registrar el endpoint del modelo text-embedding sin compatibilidad integrada. La firma de las funciones de transformación depende de la función de predicción del tipo de modelo.

No puedes usar funciones de transformación al registrar un endpoint de modelo generic.

A continuación, se muestran las firmas de la función de predicción de los modelos de inserción de texto:

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

Para obtener más información sobre cómo crear funciones de transformación, consulta el ejemplo de funciones de transformación.

Función de generación de encabezados HTTP

La función de generación de encabezados HTTP genera la salida en pares clave-valor JSON que se usan como encabezados HTTP. La firma de la función de predicción define las firmas de la función de generación de encabezados.

En el siguiente ejemplo se muestra la firma de la función de predicción mysql.ml_embedding():

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

En el caso de la función de predicción mysql.ml_predict_row(), la firma es la siguiente:

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

Para obtener más información sobre cómo crear una función de generación de encabezados, consulta el ejemplo de función de generación de encabezados.

Limitaciones

  • Cuando ejecutas cualquiera de las funciones de registro de modelos o de gestión de secretos, se confirman implícitamente las transacciones abiertas en la sesión. Las funciones de predicción no confirman las transacciones de forma implícita.

  • Si exportas o importas tu base de datos con mysqldump, no se exportará el catálogo de endpoints del modelo.

  • Una base de datos de usuarios que contenga funciones de transformación no puede tener un punto ('.') en su nombre. Por ejemplo, no se admite una base de datos llamada my.sql.

  • La gestión de endpoints de modelos solo está disponible en Cloud SQL para MySQL 8.0.36 y versiones posteriores.

Siguientes pasos