Esta página se ha traducido con Cloud Translation API.

Registrar y llamar a modelos de IA remotos mediante la gestión de endpoints de modelos

MySQL | PostgreSQL | SQL Server

En esta página se describe cómo invocar predicciones o generar inserciones mediante un modelo y, a continuación, registrar el endpoint del modelo con la gestión de endpoints de modelos.

Para obtener más información sobre la función mysql.ml_create_model_registration(), consulta la referencia de gestión de endpoints de modelos.

Antes de empezar

En función del proveedor del modelo, configura la autenticación.

Conéctate a tu instancia principal mediante un mysql cliente o Cloud SQL Studio.
Asegúrate de conectarte a la base de datos como usuario de la base de datos MySQL con los privilegios de base de datos descritos en Privilegios de usuario de base de datos necesarios.

Configurar la autenticación

En las siguientes secciones se muestra cómo configurar la autenticación antes de añadir un endpoint de modelo de Vertex AI o endpoints de modelo alojados en Google Cloud.

Configurar la autenticación de Vertex AI

Para usar los endpoints del modelo de Google Vertex AI, debes añadir permisos de Vertex AI a la cuenta de servicio de Cloud SQL basada en IAM que uses para conectarte a la base de datos. Para obtener más información sobre la integración con Vertex AI, consulta Integrar Cloud SQL con Vertex AI.

Configurar la autenticación para modelos alojados de forma personalizada

En esta sección se explica cómo configurar la autenticación si usas Secret Manager. En el caso de todos los modelos, excepto los endpoints de modelos de Vertex AI, puedes almacenar tus claves de API o tokens de portador en Secret Manager.

Si el endpoint de tu modelo no gestiona la autenticación a través de Secret Manager, esta sección es opcional. Por ejemplo, si el endpoint de tu modelo usa encabezados HTTP para transferir información de autenticación o no usa autenticación, no completes los pasos de esta sección.

Para crear y usar una clave de API o un token de portador, sigue estos pasos:

Crea un secreto en Secret Manager. Para obtener más información, consulta Crear un secreto y acceder a una versión de un secreto.

El nombre y la ruta del secreto se usan en la función SQL mysql.ml_create_sm_secret_registration().
Concede permisos a la instancia de Cloud SQL para acceder al secreto.
```
  gcloud secrets add-iam-policy-binding SECRET_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role="roles/secretmanager.secretAccessor"
```
Haz los cambios siguientes:
- SECRET_ID: el ID del secreto en Secret Manager.
- SERVICE_ACCOUNT_EMAIL: la dirección de correo de la cuenta de servicio de Cloud SQL basada en gestión de identidades y accesos. Para encontrar esta dirección de correo, usa el comando gcloud sql instances describe INSTANCE_NAME y sustituye INSTANCE_NAME por el nombre de la instancia. El valor que aparece junto al parámetro serviceAccountEmailAddress es la dirección de correo electrónico.

Modelos de inserción de texto con asistencia integrada

En esta sección se muestra cómo registrar endpoints de modelos para gestionar los endpoints de modelos.

Modelos de inserciones de Vertex AI

La gestión de endpoints de modelos ofrece compatibilidad integrada con todas las versiones de los modelos text-embedding-gecko, text-embedding y gemini-embedding de Vertex AI. Usa el nombre completo para definir la versión del modelo como textembedding-gecko@001 o textembedding-gecko@002.

Como los IDs de endpoint de modelos de inserción de Vertex AI se admiten de forma predeterminada con la gestión de endpoints de modelos, puedes usar cualquiera de ellos directamente como ID de modelo. En estos modelos, la función de inserción realiza automáticamente la transformación de entrada y salida.

Asegúrate de que tanto la instancia de Cloud SQL como el modelo de Vertex AI que estás consultando se encuentren en la misma región.

Para registrar el endpoint del modelo gemini-embedding-001, llama a la función 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);

Modelos de inserción de texto alojados de forma personalizada

En esta sección se muestra cómo registrar endpoints de modelos personalizados alojados en redes de Google Cloud.

Para añadir endpoints de modelos de inserción de texto alojados de forma personalizada, debes crear funciones de transformación y, opcionalmente, encabezados HTTP personalizados. Por otro lado, para añadir endpoints de modelos genéricos alojados de forma personalizada, se pueden generar encabezados HTTP personalizados y definir la URL de solicitud del modelo.

En el siguiente ejemplo se añade el endpoint del modelo de inserción de texto custom-embedding-model alojado por Cymbal, que se aloja en Google Cloud. Las funciones de transformación cymbal_text_input_transform y cymbal_text_output_transform se usan para transformar el formato de entrada y salida del modelo en el formato de entrada y salida de la función de predicción.

Para registrar endpoints de modelos de inserción de texto alojados de forma personalizada, sigue estos pasos:

Llama al secreto almacenado en Secret Manager:
```
CALL
  mysql.ml_create_sm_secret_registration(
    'SECRET_ID',
    'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
```
Haz los cambios siguientes:
- SECRET_ID: el ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo. Por ejemplo, key1.
- SECRET_MANAGER_SECRET_ID: el ID de secreto definido en Secret Manager al crear el secreto.
- PROJECT_ID: el ID de tu proyecto de Google Cloud .
- VERSION_NUMBER: el número de versión del ID del secreto.
Nota: Secret Manager genera un encabezado Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER para la autenticación de forma predeterminada. Si este formato coincide con el formato del token de portador de autorización del endpoint de tu modelo, no tienes que generar encabezados de autorización con la función de generación de encabezados.

Crea las funciones de transformación de entrada y salida a partir de la siguiente firma de la función de predicción de los endpoints del modelo de inserción de texto. Para obtener más información sobre cómo crear funciones de transformación, consulta el ejemplo de funciones de transformación.

A continuación, se muestran funciones de transformación de ejemplo específicas del endpoint del modelo de inserciones de texto 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 ;

Llama a la función de creación de modelos para registrar el endpoint del modelo de inserción personalizado:

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

Haz los cambios siguientes:

MODEL_ID: obligatorio. Un ID único para el punto de conexión del modelo que definas (por ejemplo, custom-embedding-model). Este ID de modelo se utiliza como referencia para los metadatos que necesita el punto de conexión del modelo para generar inserciones o invocar predicciones.
REQUEST_URL: obligatorio. El endpoint específico del modelo al añadir una inserción de texto personalizada y endpoints de modelos genéricos (por ejemplo, https://cymbal.com/models/text/embeddings/v1). Asegúrate de que se pueda acceder al endpoint del modelo a través de una dirección IP interna. La gestión de endpoints de modelos no admite direcciones IP externas.
MODEL_QUALIFIED_NAME: es obligatorio si el endpoint de tu modelo usa un nombre cualificado. El nombre completo en caso de que el endpoint del modelo tenga varias versiones.
SECRET_ID: el ID secreto que has usado anteriormente en el procedimiento mysql.ml_create_sm_secret_registration().

Modelos genéricos

En esta sección se muestra cómo registrar un endpoint de modelo genérico gemini-flashde Vertex AI Model Garden, que está pre-registrado en el catálogo de forma predeterminada. Puedes registrar cualquier endpoint de modelo genérico alojado en Google Cloud.

Cloud SQL solo admite los endpoints de modelos disponibles a través de Model Garden de Vertex AI y los endpoints de modelos alojados en redes de Google Cloud.

Modelo de Gemini

En el siguiente ejemplo se usa el endpoint del modelo gemini-2.5-flash de Vertex AI Model Garden.

Para registrar el endpoint del modelo gemini-2.5-flash, llama a la función 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);