Referência de gerenciamento de endpoints de modelo

Esta página lista parâmetros para diferentes funções fornecidas pelo Cloud SQL para registrar e gerenciar endpoints de modelo. A página também lista os secrets que podem ser gerenciados usando o gerenciamento de endpoints de modelo.

Modelos

Use esta referência para entender os parâmetros das funções que permitem gerenciar endpoints de modelo.

mysql.ml_create_model_registration()

A seguir, mostramos como usar a função mysql.ml_create_model_registration() para registrar metadados de endpoint do modelo:

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

mysql.ml_alter_model_registration()

Confira a seguir como chamar a função SQL mysql.ml_alter_model_registration() usada para atualizar os metadados do endpoint do 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()

Confira a seguir como chamar a função SQL mysql.ml_drop_model_registration() usada para excluir um endpoint de modelo:

  CALL mysql.ml_drop_model_registration('MODEL_ID');

mysql.ml_list_registered_model()

A seguir, mostramos como chamar a função SQL mysql.ml_list_registered_model() usada para listar informações do endpoint do modelo:

  SELECT mysql.ml_list_registered_model('MODEL_ID');

mysql.cloudsql_ml_models

A seguir, mostramos como consultar a tabela mysql.cloudsql_ml_models usada para listar informações de endpoint de modelo para todos os endpoints de modelo:

  SELECT * FROM mysql.cloudsql_ml_models;

Secrets

Use esta referência para entender os parâmetros das funções que permitem gerenciar secrets.

mysql.ml_create_sm_secret_registration()

A seguir, mostramos como chamar a função SQL mysql.ml_create_sm_secret_registration() usada para adicionar o secret criado no Secret Manager:

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

mysql.ml_alter_sm_secret_registration()

Confira a seguir como chamar a função SQL mysql.ml_alter_sm_secret_registration() usada para atualizar informações secretas:

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

mysql.ml_drop_sm_secret_registration()

Veja a seguir como chamar a função SQL mysql.ml_drop_sm_secret_registration() usada para excluir um secret:

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

Funções de previsão

Use esta referência para entender os parâmetros das funções que permitem gerar embeddings ou invocar previsões.

mysql.ml_embedding()

Confira a seguir como gerar embeddings:

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

Para exemplos de consultas SQL que geram embeddings de texto, consulte Exemplos.

mysql.ml_predict_row()

Confira abaixo como invocar previsões:

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

Para exemplos de consultas SQL para invocar previsões, consulte Exemplos.

Funções de transformação

Use esta referência para entender os parâmetros das funções de transformação de entrada e saída.

Função de transformação de entrada

A seguir, mostramos a assinatura da função de previsão para endpoints de modelo de incorporação de texto:

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

Função de transformação de saída

A seguir, mostramos a assinatura da função de previsão para endpoints de modelo de incorporação de texto:

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

Exemplo de funções de transformação

Para entender melhor como criar funções de transformação para o endpoint do modelo, considere um endpoint de modelo de embedding de texto hospedado personalizado que exige entrada e saída JSON.

O exemplo de solicitação curl a seguir cria embeddings com base no comando e no endpoint do modelo:

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

A seguinte resposta de exemplo é retornada:

[[ 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]]

Com base nessa entrada e resposta, é possível inferir o seguinte:

• O modelo espera entrada JSON pelo campo prompt. Esse campo aceita uma matriz de entradas. Como a função mysql.ml_embedding() é uma função de nível de linha, ela espera uma entrada de texto por vez. Portanto, é necessário criar uma função de transformação de entrada que crie uma matriz com um único elemento.

• A resposta do modelo é uma matriz de embeddings, um para cada entrada de comando para o modelo. Como a função mysql.ml_embedding() é uma função de nível de linha, ela retorna uma entrada por vez. Portanto, é necessário criar uma função de transformação de saída que possa ser usada para extrair o encadeamento do array.

O exemplo a seguir mostra as funções de transformação de entrada e saída usadas para esse endpoint de modelo quando ele é registrado no gerenciamento de endpoints de modelo:

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

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;

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 ;