Referencia de administración de extremos del modelo

MySQL | PostgreSQL | SQL Server

En esta página, se enumeran los parámetros de las diferentes funciones que proporciona Cloud SQL para registrar y administrar extremos de modelos. En la página, también se enumeran los secretos que puedes administrar con la administración de extremos de modelos.

Modelos

Usa esta referencia para comprender los parámetros de las funciones que te permiten administrar extremos de 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 extremos 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 extremos de modelos	Es un ID único para el extremo del modelo que defines.
`REQUEST_URL`	Puede ser NULL para los modelos de Agent Platform	Es el extremo específico del modelo cuando se agregan otros extremos de modelos genéricos y de incorporación de texto. La URL de solicitud que genera la función para los extremos de modelos integrados hace referencia al proyecto y la región o ubicación de tu clúster. Si deseas hacer referencia a otro proyecto, asegúrate de especificar `model_request_url` de forma explícita. En el caso de los extremos de modelos alojados personalizados, asegúrate de que se pueda acceder a ellos a través de Internet.
`PROVIDER_ID`	Obligatorio para los extremos de modelos de incorporación de texto con compatibilidad integrada	Es el proveedor del extremo del modelo. El valor predeterminado es `custom`. Para Cloud SQL, establece el proveedor en `google` para los extremos de modelos de Agent Platform, `open_ai` para los extremos de modelos de OpenAI, `anthropic` para los extremos de modelos de Anthropic, `hugging_face` para los extremos de modelos de Hugging Face o `custom` para los extremos de modelos alojados personalizados.
`MODEL_TYPE`	Puede ser NULL para los extremos de modelos genéricos	Es el tipo de modelo. Puedes establecer este valor en `text_embedding` para los extremos de modelos de incorporación de texto o en `generic` para todos los demás extremos de modelos.
`MODEL_QUALIFIED_NAME`	Obligatorio para los extremos de modelos de OpenAI; puede ser NULL para otros extremos de modelos	Es el nombre completamente calificado en caso de que el extremo del modelo tenga varias versiones o si el extremo del modelo lo define, por ejemplo, `textembedding-gecko@001` o `textembedding-gecko@002`. Dado que el modelo `textembedding-gecko@001` está registrado previamente con la administración de extremos de modelos, puedes generar incorporaciones con `textembedding-gecko@001` como el ID del modelo.
`AUTH_TYPE`	Puede ser NULL, a menos que el extremo del modelo tenga un requisito de autenticación específico	Es el tipo de autenticación que usa el extremo del modelo. Puedes establecerlo en `auth_type_cloudsql_service_agent_iam` para los modelos de Agent Platform o en `auth_type_secret_manager` para otros proveedores.
`AUTH_ID`	Pasa como NULL para los extremos de Agent Platform; obligatorio para todos los demás extremos de modelos que almacenan secretos en Secret Manager	Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo.
`GENERATE_HEADER_FUNCTION`	Puede ser NULL	Es el nombre de la función que estableces para generar encabezados personalizados. La firma de esta función depende de la función `mysql.ml_predict_row()`. Consulta Función de generación de encabezados HTTP.
`INPUT_TRANSFORM_FUNCTION`	Opcional para los extremos de modelos de incorporación de texto con compatibilidad integrada; no se establece para los extremos de modelos genéricos	Es la 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 extremos de modelos de incorporación de texto con compatibilidad integrada; no se establece para los extremos de modelos genéricos	Es la función para transformar el resultado específico del modelo en el resultado 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 de extremos de modelos:

    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 quitar un extremo de modelo:

  CALL mysql.ml_drop_model_registration('MODEL_ID');

Parámetro	Descripción
`MODEL_ID`	Es un ID único para el extremo del modelo que defines.

`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 de extremos de modelos:

  SELECT mysql.ml_list_registered_model('MODEL_ID');

Parámetro	Descripción
`MODEL_ID`	Es un ID único para el extremo del modelo que defines.

`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 extremos de modelos para todos los extremos de modelos:

  SELECT * FROM mysql.cloudsql_ml_models;

Secrets

Usa esta referencia para comprender los parámetros de las funciones que te permiten administrar 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() que se usa para agregar 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`	Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo.
`PROJECT_ID`	Es el ID de tu Google Cloud proyecto que contiene el secreto. Este proyecto puede ser diferente del proyecto que contiene tu instancia de Cloud SQL.
`SECRET_MANAGER_SECRET_ID`	Es el ID secreto establecido en Secret Manager cuando creaste el secreto.
`VERSION_NUMBER`	Es el número de versión del ID 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 secreta:

  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`	Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo.
`PROJECT_ID`	Es el ID de tu Google Cloud proyecto que contiene el secreto. Este proyecto puede ser diferente del proyecto que contiene tu instancia de Cloud SQL.
`SECRET_MANAGER_SECRET_ID`	Es el ID secreto establecido en Secret Manager cuando creaste el secreto.
`VERSION_NUMBER`	Es el número de versión del ID 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() que se usa para quitar un secreto:

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

Parámetro	Descripción
`SECRET_ID`	Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo.

Funciones de predicción

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

`mysql.ml_embedding()`

A continuación, se muestra cómo generar incorporaciones:

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

Parámetro	Descripción
`MODEL_ID`	Es un ID único para el extremo del modelo que defines.
`CONTENT`	Es el texto que se traducirá a una incorporación de vector.

Para obtener ejemplos de consultas SQL para generar incorporaciones de texto, consulta 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`	Es un ID único para el extremo del modelo que defines.
`REQUEST_BODY`	Son los parámetros de la función de predicción, en formato JSON.

Para obtener ejemplos de consultas SQL para invocar predicciones, consulta Ejemplos.

Funciones de transformación

Usa esta referencia para comprender 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 para los extremos de modelos de incorporació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`	Es la función para transformar la entrada de la función de predicción correspondiente en la entrada específica del extremo del modelo.

Función de transformación de salida

A continuación, se muestra la firma de la función de predicción para los extremos de modelos de incorporació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`	Es la función para transformar el resultado específico del extremo del modelo en el resultado de la función de predicción.

Ejemplo de funciones de transformación

Para comprender mejor cómo crear funciones de transformación para tu extremo de modelo, considera un extremo de modelo de incorporación de texto alojado personalizado que requiera entrada y salida JSON.

En la siguiente solicitud de curl de ejemplo, se crean incorporaciones basadas en la instrucción y el extremo 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 muestra 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]]

Con base en esta entrada y respuesta, puedes inferir lo siguiente:

El modelo espera una entrada JSON a través del campo prompt. Este campo acepta un array de entradas. Como la mysql.ml_embedding() función es una función de nivel de fila, espera una entrada de texto a la vez. Por lo tanto, debes crear una función de transformación de entrada que cree un array con un solo elemento.
La respuesta del modelo es un array de incorporaciones, una para cada entrada de instrucción al modelo. Como la función mysql.ml_embedding() es una función de nivel de fila, muestra 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 incorporación del array.

En el siguiente ejemplo, se muestran las funciones de transformación de entrada y salida que se usan para este extremo de modelo cuando se registra con la administración de extremos 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 ;

Default included transform functions

Model Endpoint Management provides in-built support for two common text embedding model families, Google's Gemini embedding models and OpenAI's text embedding models. The input and output transforms are preloaded when these models are registered, for convenience. They can be overwritten by specifying your own transform functions during registration, or by calling mysql.ml_alter_model_registration().

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 ;

Referencia de administración de extremos del modelo Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Modelos

mysql.ml_create_model_registration()

mysql.ml_alter_model_registration()

mysql.ml_drop_model_registration()

mysql.ml_list_registered_model()

mysql.cloudsql_ml_models