Descripción general de cómo registrar y llamar a modelos de IA remotos en Cloud SQL

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 Cómo generar y administrar embeddings de vectores.

Descripción general

La administración de extremos de modelos te permite registrar un extremo de modelo, administrar los metadatos del extremo de modelo en tu instancia de Cloud SQL y, luego, interactuar con los modelos usando consultas de 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 incorporación de texto de Vertex AI
  • Modelos de incorporación de texto alojados de forma personalizada en redes dentro de Google Cloud.

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

    • El modelo gemini-flash de Vertex AI Model Garden
    • El modelo open_ai para los 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 del modelo con la administración de extremos del modelo, esta registra cada extremo con un ID de modelo único como referencia al modelo. Puedes usar este ID del modelo para consultar modelos, de la siguiente manera:

  • Genera embeddings para traducir instrucciones de texto en vectores numéricos. Puedes almacenar los embeddings generados como datos de vectores cuando habilitas la compatibilidad con embeddings de vectores en tu instancia. Para obtener más información, consulta Cómo habilitar y, luego, inhabilitar las incorporaciones vectoriales en tu instancia.

  • Invoca predicciones para llamar a un modelo a través de SQL dentro de 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 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 con 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 tu instancia, puedes usar las siguientes funciones:

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

Privilegios de usuario de base de datos obligatorios

Para registrar y llamar a modelos de IA remotos, debes acceder como usuario de la base de datos de MySQL al que se le otorgaron privilegios SELECT y EXECUTE en mysql.*.

De forma predeterminada, cualquier usuario con el rol cloudsqlsuperuser tiene estos privilegios o puede crear un usuario y otorgarle 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, debes comprender los conceptos necesarios para conectarte a los modelos y usarlos.

Proveedor del modelo

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

Proveedor del modelo Establecer 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 modelos

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

Si usas Vertex AI como proveedor de modelos, no necesitas registrar un extremo del modelo, ya que los extremos se admiten automáticamente. De forma predeterminada, con Vertex AI, usas el modelo text-embedding-005.

Otros modelos de embeddings de texto
Para otros modelos de incorporación 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 los 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 incorporación de texto. Para invocar predicciones para modelos genéricos, usa la función mysql.ml_predict_row(). Puedes configurar los metadatos del extremo del modelo, como un extremo de solicitud y encabezados HTTP 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. Dado que generic es el tipo de modelo predeterminado, si registras extremos de modelos para este tipo, la configuración del tipo de modelo es opcional.
Con Vertex AI, la administración de extremos de modelos incluye asistencia 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. Configurar estos métodos es opcional y solo es necesario si necesitas 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 almacenan como secreto en Secret Manager se pueden usar con la función de 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 Establecer 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 extremo de modelo de incorporación de texto registrado para generar incorporaciones. Incluye compatibilidad integrada con todos los modelos de incorporación de Vertex AI.
En el caso de los modelos de incorporación de texto sin compatibilidad integrada, los parámetros de entrada y salida son únicos para cada 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 del modelo generic.

A continuación, se muestran las firmas de la función de predicción para los modelos de incorporació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 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 exportará el catálogo de extremos del modelo.

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

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

¿Qué sigue?