Registra y llama a modelos de IA remotos con la administración de extremos de modelos

MySQL   |  PostgreSQL   |  SQL Server

En esta página, se describe cómo invocar predicciones o generar embeddings con un modelo y, luego, registrar el extremo del modelo con la administración de extremos de modelos.

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

Antes de comenzar

• Según el proveedor del modelo, configura la autenticación.

• Conéctate a tu instancia principal con un cliente mysql o Cloud SQL Studio.

• Asegúrate de conectarte a la base de datos como un usuario de la base de datos de MySQL con los privilegios de la base de datos que se describen en Privilegios de usuario de la base de datos requeridos.

Configura la autenticación

En las siguientes secciones, se muestra cómo configurar la autenticación antes de agregar un extremo de modelo de Vertex AI o extremos de modelos alojados en ella Google Cloud.

Configura la autenticación para Vertex AI

Para usar los extremos de modelos de Google Vertex AI, debes agregar permisos de Vertex AI a la cuenta de servicio de Cloud SQL basada en IAM que usas para conectarte a la base de datos. Para obtener más información sobre la integración con Vertex AI, consulta Integra Cloud SQL con Vertex AI.

Configura 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. Para todos los modelos, excepto los extremos de modelos de Vertex AI, puedes almacenar tus claves de API o tokens de portador en Secret Manager.

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

Para crear y usar una clave de API o un token de portador, completa los siguientes pasos:

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

   El nombre y la ruta del secreto se usan en la mysql.ml_create_sm_secret_registration() función SQL.

2. Otorga 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"
   

   Reemplaza lo siguiente:

   • SECRET_ID: Es el ID del secreto en Secret Manager.
   • SERVICE_ACCOUNT_EMAIL: Es la dirección de correo electrónico de la cuenta de servicio de Cloud SQL basada en IAM. Para encontrar esta dirección de correo electrónico, usa el gcloud sql instances describe INSTANCE_NAME comando y reemplaza 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 embedding de texto con compatibilidad integrada

En esta sección, se muestra cómo registrar extremos de modelos para la administración de extremos de modelos.

Modelos de embedding de Vertex AI

La administración de extremos de modelos proporciona compatibilidad integrada para todas las versiones de los text-embedding-gecko, text-embedding, y gemini-embedding modelos de Vertex AI. Usa el nombre calificado para establecer la versión del modelo en textembedding-gecko@001 o textembedding-gecko@002.

Debido a que los IDs de extremos de modelos de embedding de Vertex AI son compatibles de forma predeterminada con la administración de extremos de modelos, puedes usar cualquiera de ellos directamente como el ID del modelo. Para estos modelos, la función de embedding realiza automáticamente la transformación de entrada y salida.

Asegúrate de que la instancia de Cloud SQL y el modelo de Vertex AI que consultas estén en la misma región.

Para registrar el extremo 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 embedding de texto alojados de forma personalizada

En esta sección, se muestra cómo registrar extremos de modelos personalizados alojados en redes dentro de ella Google Cloud.

Agregar extremos de modelos de embedding de texto alojados de forma personalizada implica crear funciones de transformación y, de manera opcional, encabezados HTTP personalizados. Por otro lado, agregar extremos de modelos genéricos alojados de forma personalizada implica, de manera opcional, generar encabezados HTTP personalizados y establecer la URL de solicitud del modelo.

En el siguiente ejemplo, se agrega el extremo del modelo de embedding de texto custom-embedding-model alojado por Cymbal, que está alojado en ella 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 al formato de entrada y salida de la función de predicción.

Para registrar extremos de modelos de embedding de texto alojados de forma personalizada, completa los siguientes pasos:

1. 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');
   

   Reemplaza lo siguiente:

   • SECRET_ID: Es el ID del secreto que estableciste y que se usa posteriormente cuando registras un extremo de modelo, por ejemplo, key1.
   • SECRET_MANAGER_SECRET_ID: Es el ID del secreto establecido en Secret Manager cuando creaste el secreto.
   • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
   • VERSION_NUMBER: Es 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 extremo de tu modelo, no tienes que generar encabezados de autenticación con la función de generación de encabezados.

2. Crea las funciones de transformación de entrada y salida según la siguiente firma para la función de predicción de los extremos de modelos de embedding de texto. Para obtener más información sobre cómo crear funciones de transformación, consulta Ejemplo de funciones de transformación.

   A continuación, se muestran funciones de transformación de ejemplo que son específicas del extremo del modelo de embedding de texto custom-embedding-model:

   Nota: Si analizas un vector desde un objeto JSON en tu transformación de salida en Cloud SQL para MySQL 9.7 o versiones posteriores, asegúrate de usar JSON_UNQUOTE o JSON_VALUE para extraer el valor como una cadena. string_to_vector en MySQL 9.7 y versiones posteriores no aceptará entradas JSON.

   -- 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(JSON_UNQUOTE(
                 content,
                 '$.predictions[0].embeddings.values'
               ))
        );
   
   END $$
   DELIMITER ;
   

3. Llama a la función de creación de modelos para registrar el extremo del modelo de embedding 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);

Reemplaza lo siguiente:

• MODEL_ID: Es obligatorio. Es un ID único para el extremo del modelo que defines (por ejemplo, custom-embedding-model). Se hace referencia a este ID de modelo para los metadatos que el extremo del modelo necesita para generar embeddings o invocar predicciones.
• REQUEST_URL: Es obligatorio. Es el extremo específico del modelo cuando se agregan extremos de modelos genéricos y de embedding de texto personalizados, por ejemplo, https://cymbal.com/models/text/embeddings/v1. Asegúrate de que se pueda acceder al extremo del modelo a través de una dirección IP interna. La administración de extremos de modelos no admite direcciones IP externas.
• MODEL_QUALIFIED_NAME: Es obligatorio si el extremo de tu modelo usa un nombre calificado. Es el nombre completamente calificado en caso de que el extremo del modelo tenga varias versiones.
• SECRET_ID: Es el ID del secreto que usaste antes en el procedimiento mysql.ml_create_sm_secret_registration().

Modelos genéricos

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

Cloud SQL solo admite extremos de modelos que están disponibles a través de Vertex AI Model Garden y extremos de modelos alojados en redes dentro de ella Google Cloud.

Modelo de Gemini

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

Para registrar el extremo 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);

Reemplaza lo siguiente:

• MODEL_ID: Es un ID único para el extremo del modelo que defines (por ejemplo,
  gemini-1). Se hace referencia a este ID de modelo para los metadatos que el extremo del modelo necesita para generar embeddings o invocar predicciones.
• PROJECT_ID: Es el ID de tu Google Cloud proyecto.

Para obtener más información, consulta cómo invocar predicciones para extremos de modelos genéricos.

¿Qué sigue?

• Obtén información sobre la referencia de administración de extremos de modelos.