Descripción general de la administración de extremos de modelos

En esta página, se describe cómo registrar un extremo de modelo de IA y cómo invocar predicciones con la administración de extremos de modelos en Cloud SQL. Para usar modelos de IA en entornos de producción, consulta Genera y administra embeddings de vectores.

Descripción general

La administración de extremos de modelos te permite registrar un extremo de modelo, administrar los metadatos de extremos de modelos en tu instancia de Cloud SQL y, luego, interactuar con los modelos mediante consultas en SQL. Puedes usar estos modelos para generar embeddings de vectores o invocar predicciones.

Puedes registrar los siguientes tipos de modelos con la administración de extremos de modelos:

  • Modelos de embedding de texto de Agent Platform
  • Modelos de embedding de texto alojados de forma personalizada en redes dentro de Google Cloud.

  • Modelos genéricos con una API basada en JSON Entre los ejemplos de estos modelos, se incluyen los siguientes:

    • El modelo gemini-flash de Model Garden de Agent Platform
    • El modelo open_ai para modelos de OpenAI
    • Modelos alojados en redes dentro de Google Cloud

Cómo funciona

Puedes usar la administración de extremos de modelos para registrar un extremo de modelo que cumpla con lo siguiente:

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

Cuando registras un extremo de modelo con la administración de extremos de modelos, esta registra cada extremo con un ID de modelo único como referencia al modelo. Puedes usar este ID de modelo para consultar modelos de la siguiente manera:

  • Genera embeddings para traducir mensajes de texto a vectores numéricos. Puedes almacenar los embeddings generados como datos vectoriales cuando habilitas la compatibilidad con embeddings de vectores en tu instancia. Para obtener más información, consulta Habilita e inhabilita los embeddings de vectores en tu instancia.

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

Para registrar y llamar a modelos de IA remotos con tu instancia de Cloud SQL, esta debe estar instalada con 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, entonces solo puedes usar las siguientes funciones como se documenta con la integración de Cloud SQL y Agent Platform.

Para actualizar tu instancia a la versión de mantenimiento MYSQL_VERSION.R20250531.01_14 o una posterior, consulta Mantenimiento de autoservicio. Después de actualizar tu instancia, puedes 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 obligatorios

Para registrar y llamar a modelos de IA remotos, debes estar conectado como un usuario de la base de datos de MySQL al que se le otorgaron 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 otorgar los privilegios necesarios.

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

Conceptos clave

Antes de comenzar a usar la administración de extremos de modelos, comprende los conceptos necesarios para conectarte a los modelos y usarlos.

Proveedor de modelos

El proveedor de modelos es el proveedor de alojamiento de modelos compatible. En la siguiente tabla, se muestra el valor del proveedor de modelos que debes establecer según el proveedor de modelos que uses:

Proveedor de modelos Establecer en la función como…
Agent Platform (incluye Gemini) google
Anthropic anthropic
Hugging Face hugging_face
OpenAI open_ai
Otros modelos alojados fuera de Agent Platform,
Anthropic, Hugging Face y OpenAI		 custom

El proveedor de modelos predeterminado es custom.

Tipos de modelos

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

Si usas Agent Platform como proveedor de modelos, no necesitas registrar un extremo de modelo porque los extremos se admiten automáticamente. De forma predeterminada, con Agent Platform, usas el modelo text-embedding-005.

Otros modelos de embedding de texto
Para otros modelos de embedding de texto, debes crear funciones de transformación para controlar los formatos de entrada y salida que admite el modelo. De manera opcional, puedes usar la función de generación de encabezados HTTP que genera encabezados personalizados que requiere tu modelo.

El tipo de modelo para estos modelos es text_embedding.

Modelos genéricos
La administración de extremos de modelos también admite el registro de todos los demás tipos de modelos, además de los modelos de embedding de texto. Para invocar predicciones para modelos genéricos, usa la mysql.ml_predict_row() función. Puedes establecer metadatos de extremos de modelos, como un extremo de solicitud y encabezados HTTP que sean específicos de tu modelo.
No puedes pasar funciones de transformación cuando registras un extremo de modelo genérico. Asegúrate de que, cuando invoques predicciones, la entrada de la función esté en formato JSON y de que analices el resultado JSON para obtener el resultado final.
El tipo de modelo para estos modelos es generic. Como generic es el tipo de modelo predeterminado, si registras extremos de modelos para este tipo, establecer el tipo de modelo es opcional.
Con Agent Platform, la administración de extremos de modelos incluye compatibilidad pre registrada para el modelo gemini-2.5-flash.

Métodos de autenticación

Puedes habilitar la compatibilidad con embeddings de vectores en tu instancia de Cloud SQL para MySQL y, luego, especificar diferentes métodos de autenticación para acceder a tu modelo. Establecer estos métodos es opcional y solo es necesario si necesitas autenticarte para acceder a tu modelo.

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

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

Método de autenticación Establecer en la función como… Proveedor de modelos
Agente de servicio de Cloud SQL auth_type_cloudsql_service_agent_iam Proveedor de Agent Platform
Secret Manager auth_type_secret_manager Modelos alojados fuera de Agent Platform

Funciones de predicción

mysql.ml_embedding()
Llama a un extremo de modelo de embedding de texto registrado para generar embeddings. Incluye compatibilidad integrada para todos los modelos de embedding de Agent Platform.
Para los modelos de embedding de texto sin compatibilidad integrada, los parámetros de entrada y salida son únicos para un modelo y deben transformarse para que la función llame al modelo. Crea una función de entrada de transformación para transformar la entrada de la función de predicción en la entrada específica del modelo, y una función de salida de transformación 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 extremo de modelo genérico registrado, si el extremo admite APIs basadas en JSON para invocar predicciones.

Funciones de transformación

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

No puedes usar funciones de transformación cuando registras un extremo de modelo generic.

A continuación, se muestran las firmas de la función de predicción para los modelos de embedding 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 Ejemplo de funciones de transformación.

Función de generación de encabezados HTTP

La función de generación de encabezados HTTP genera el resultado 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;

Para 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 Ejemplo de función de generación de encabezados.

Limitaciones

  • Cuando ejecutas cualquiera de las funciones de registro de modelos o de administración de secretos, confirmas de forma implícita cualquier transacción abierta en la sesión. Las funciones de predicción no confirman transacciones de forma implícita.

  • Si exportas o importas tu base de datos con mysqldump, no se exporta el catálogo de extremos de modelos.

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

  • La administración de extremos de modelos solo está disponible para Cloud SQL para MySQL versión 8.0.36 y versiones posteriores.

¿Qué sigue?