Referencia de gestión de endpoints de modelos

Vista previa

Este producto está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

MySQL   |  PostgreSQL   |  SQL Server

En esta página se enumeran los parámetros de las diferentes funciones proporcionadas por Cloud SQL para registrar y gestionar los endpoints de modelos. En la página también se indican los secretos que puedes gestionar mediante la gestión de endpoints de modelos.

Nota: Para obtener más información sobre la gestión de endpoints de modelos, consulta Registrar y llamar a modelos de IA remotos en Cloud SQL.

Modelos

Usa esta referencia para conocer los parámetros de las funciones que te permiten gestionar los endpoints de los modelos.

mysql.ml_create_model_registration()

A continuación, se muestra cómo usar la función mysql.ml_create_model_registration() para registrar metadatos de endpoints de modelos:

  CALL
    mysql.ml_create_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

Parámetro	Obligatorio	Descripción
MODEL_ID	Obligatorio para todos los endpoints de modelos	Un ID único que definas para el endpoint del modelo.
REQUEST_URL	Puede ser NULL para los modelos de Vertex AI.	El endpoint específico del modelo al añadir otros endpoints de modelos genéricos y de inserciones de texto. La URL de solicitud que genera la función para los endpoints de modelos integrados hace referencia al proyecto y a la región o ubicación de tu clúster. Si quieres hacer referencia a otro proyecto, asegúrate de especificar el model_request_url explícitamente. En el caso de los endpoints de modelos alojados personalizados, asegúrate de que se pueda acceder a ellos a través de Internet.
PROVIDER_ID	Obligatorio para los endpoints de modelos de incrustaciones de texto con compatibilidad integrada	El proveedor del endpoint del modelo. El valor predeterminado es custom. En Cloud SQL, define el proveedor como google para los endpoints de modelos de Vertex AI, open_ai para los endpoints de modelos de OpenAI, anthropic para los endpoints de modelos de Anthropic, hugging_face para los endpoints de modelos de Hugging Face o custom para los endpoints de modelos alojados personalizados.
MODEL_TYPE	Puede ser NULL para los endpoints de modelos genéricos.	El tipo de modelo. Puedes definir este valor como text_embedding para los endpoints del modelo de inserción de texto o generic para todos los demás endpoints del modelo.
MODEL_QUALIFIED_NAME	Obligatorio para los endpoints de modelos de OpenAI. Puede ser NULL para otros endpoints de modelos.	El nombre completo en caso de que el endpoint del modelo tenga varias versiones o si el endpoint del modelo lo define (por ejemplo, textembedding-gecko@001 o textembedding-gecko@002). Como el modelo textembedding-gecko@001 está pre-registrado en la gestión de endpoints de modelos, puedes generar embeddings usando textembedding-gecko@001 como ID de modelo.
AUTH_TYPE	Puede ser NULL a menos que el endpoint del modelo tenga un requisito de autenticación específico.	El tipo de autenticación que usa el endpoint del modelo. Puedes definirlo como auth_type_cloudsql_service_agent_iam para los modelos de Vertex AI o como auth_type_secret_manager para otros proveedores.
AUTH_ID	Se pasa como NULL para los endpoints de Vertex AI. Es obligatorio para todos los demás endpoints de modelos que almacenan secretos en Secret Manager.	El ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.
GENERATE_HEADER_FUNCTION	Puede ser NULL	El nombre de la función que has definido para generar encabezados personalizados. La firma de esta función depende de la función mysql.ml_predict_row(). Consulta la función de generación de encabezados HTTP.
INPUT_TRANSFORM_FUNCTION	Opcional para los endpoints de modelos de inserciones de texto con compatibilidad integrada. No se debe definir para los endpoints de modelos genéricos.	Función para transformar la entrada de la función de predicción correspondiente en la entrada específica del modelo. Consulta Funciones de transformación.
OUTPUT_TRANSFORM_FUNCTION	Opcional para los endpoints de modelos de inserciones de texto con compatibilidad integrada. No se debe definir para los endpoints de modelos genéricos.	Función para transformar la salida específica del modelo en la salida de la función de predicción. Consulta Funciones de transformación.

mysql.ml_alter_model_registration()

A continuación, se muestra cómo llamar a la función SQL mysql.ml_alter_model_registration() que se usa para actualizar los metadatos del endpoint del modelo:

    CALL
    mysql.ml_alter_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

mysql.ml_drop_model_registration()

A continuación, se muestra cómo llamar a la función SQL mysql.ml_drop_model_registration() que se usa para eliminar un endpoint de modelo:

  CALL mysql.ml_drop_model_registration('MODEL_ID');

Parámetro	Descripción
MODEL_ID	Un ID único que definas para el endpoint del modelo.

mysql.ml_list_registered_model()

A continuación, se muestra cómo llamar a la función SQL mysql.ml_list_registered_model() que se usa para enumerar la información del endpoint del modelo:

  SELECT mysql.ml_list_registered_model('MODEL_ID');

Parámetro	Descripción
MODEL_ID	Un ID único que definas para el endpoint del modelo.

mysql.cloudsql_ml_models

A continuación, se muestra cómo consultar la tabla mysql.cloudsql_ml_models que se usa para enumerar la información de los endpoints de modelos de todos los endpoints de modelos:

  SELECT * FROM mysql.cloudsql_ml_models;

Secretos

Usa esta referencia para conocer los parámetros de las funciones que te permiten gestionar secretos.

mysql.ml_create_sm_secret_registration()

A continuación, se muestra cómo llamar a la función SQL mysql.ml_create_sm_secret_registration() para añadir el secreto creado en Secret Manager:

    CALL
    mysql.ml_create_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Parámetro	Descripción
SECRET_ID	El ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.
PROJECT_ID	El ID del proyecto Google Cloud que contiene el secreto. Este proyecto puede ser diferente del que contiene tu instancia de Cloud SQL.
SECRET_MANAGER_SECRET_ID	El ID del secreto definido en Secret Manager al crear el secreto.
VERSION_NUMBER	Número de versión del ID del secreto.

mysql.ml_alter_sm_secret_registration()

A continuación, se muestra cómo llamar a la función SQL mysql.ml_alter_sm_secret_registration(), que se usa para actualizar la información de secretos:

  CALL
    mysql.ml_alter_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Parámetro	Descripción
SECRET_ID	El ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.
PROJECT_ID	El ID del proyecto Google Cloud que contiene el secreto. Este proyecto puede ser diferente del que contiene tu instancia de Cloud SQL.
SECRET_MANAGER_SECRET_ID	El ID del secreto definido en Secret Manager al crear el secreto.
VERSION_NUMBER	Número de versión del ID del secreto.

mysql.ml_drop_sm_secret_registration()

A continuación, se muestra cómo llamar a la función SQL mysql.ml_drop_sm_secret_registration() para eliminar un secreto:

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

Parámetro	Descripción
SECRET_ID	El ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.

Funciones de predicción

Usa esta referencia para conocer los parámetros de las funciones que te permiten generar inserciones o invocar predicciones.

mysql.ml_embedding()

A continuación, se muestra cómo generar las inserciones:

SELECT
  mysql.ml_embedding(
    'MODEL_ID',
    'CONTENT');

Parámetro	Descripción
MODEL_ID	Un ID único que definas para el endpoint del modelo.
CONTENT	el texto que se va a traducir a una incrustación de vector.

Para ver ejemplos de consultas de SQL para generar incrustaciones de texto, consulta la sección Ejemplos.

mysql.ml_predict_row()

A continuación, se muestra cómo invocar predicciones:

SELECT
  mysql.ml_predict_row(
    'MODEL_ID',
    'REQUEST_BODY');

Parámetro	Descripción
MODEL_ID	Un ID único que definas para el endpoint del modelo.
REQUEST_BODY	Los parámetros de la función de predicción, en formato JSON.

Para ver ejemplos de consultas SQL para invocar predicciones, consulta la sección Ejemplos.

Transformar funciones

Usa esta referencia para entender los parámetros de las funciones de transformación de entrada y salida.

Función de transformación de entrada

A continuación, se muestra la firma de la función de predicción de los endpoints del modelo de inserción de texto:

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

Parámetro	Descripción
INPUT_TRANSFORM_FUNCTION	Función para transformar la entrada de la función de predicción correspondiente en la entrada específica del endpoint del modelo.

Función de transformación de salida

A continuación, se muestra la firma de la función de predicción de los endpoints del modelo de inserción de texto:

  CREATE FUNCTION IF NOT EXISTS
  OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

Parámetro	Descripción
OUTPUT_TRANSFORM_FUNCTION	Función para transformar la salida específica del endpoint del modelo en la salida de la función de predicción.

Ejemplo de funciones de transformación

Para entender mejor cómo crear funciones de transformación para el endpoint de tu modelo, considera un endpoint de modelo de inserciones de texto alojado de forma personalizada que requiera entradas y salidas JSON.

La siguiente solicitud curl de ejemplo crea inserciones basadas en la petición y el endpoint del modelo:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["Cloud SQL Embeddings"]}'

Se devuelve la siguiente respuesta de ejemplo:

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

A partir de esta entrada y respuesta, puedes deducir lo siguiente:

• El modelo espera una entrada JSON a través del campo prompt. Este campo acepta una matriz de entradas. Como la función mysql.ml_embedding() es una función a nivel de fila, espera una entrada de texto cada vez. Por lo tanto, debe crear una función de transformación de entrada que genere una matriz con un solo elemento.

• La respuesta del modelo es una matriz de inserciones, una por cada petición introducida en el modelo. Como la función mysql.ml_embedding() es una función de nivel de fila, devuelve una sola entrada a la vez. Por lo tanto, debes crear una función de transformación de salida que se pueda usar para extraer la inserción de la matriz.

En el siguiente ejemplo se muestran las funciones de transformación de entrada y salida que se usan en este endpoint de modelo cuando se registra en la gestión de endpoints de modelos:

función de transformación de entrada

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 $$

función de transformación de salida

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 ;

HTTP header generation function

The following shows signature for the header generation function that can be used with the `mysql.ml_embedding()` prediction function when registering other text embedding model endpoints.

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

For the mysql.ml_predict_row() prediction function, the signature is as follows:

CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON DETERMINISTIC;

Parameter	Description
GENERATE_HEADERS	The function to generate custom headers. You can also pass the authorization header generated by the header generation function while registering the model endpoint.

Header generation function example

To better understand how to create a function that generates output in JSON key value pairs that are used as HTTP headers, consider a custom-hosted text embedding model endpoint.

The following example curl request passes the version HTTP header, which is used by the model endpoint:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["Cloud SQL Embeddings"]}'

The model expects text input through the version field and returns the version value in JSON format. The following example shows the header generation function that is used for this text embedding model endpoint when it is registered with model endpoint management:

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC
BEGIN
  RETURN JSON_OBJECT('version', '2024-01-01');
END;
$$
DELIMITER ;