Referência de gerenciamento de endpoints de modelo

MySQL   |  PostgreSQL   |  SQL Server

Esta página lista os parâmetros de 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.

Observação: para mais informações sobre o gerenciamento de endpoints de modelo, consulte Visão geral do gerenciamento de endpoints de modelo.

Modelos

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

mysql.ml_create_model_registration()

Confira a seguir como usar a função mysql.ml_create_model_registration() para registrar metadados de endpoints de 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');

Parâmetro	Obrigatório	Descrição
MODEL_ID	Obrigatório para todos os endpoints de modelo	Um ID exclusivo para o endpoint de modelo definido.
REQUEST_URL	Pode ser NULL para modelos da Vertex AI	O endpoint específico do modelo ao adicionar outros embeddings de texto e endpoints de modelo genéricos. O URL da solicitação que a função gera para endpoints de modelo integrados se refere ao projeto e à região ou local do cluster. Se você quiser se referir a outro projeto, especifique model_request_url explicitamente. Para endpoints de modelo hospedados de maneira personalizada, verifique se o endpoint do modelo está acessível pela Internet.
PROVIDER_ID	Obrigatório para endpoints de modelo de embedding de texto com suporte integrado	O provedor do endpoint de modelo. O valor padrão é custom. Para o Cloud SQL, defina o provedor como google para endpoints de modelo da Vertex AI, open_ai para endpoints de modelo da OpenAI, anthropic para endpoints de modelo da Anthropic, hugging_face para endpoints de modelo da Hugging Face ou custom para endpoints de modelo hospedados de maneira personalizada.
MODEL_TYPE	Pode ser NULL para endpoints de modelo genéricos	O tipo de modelo. É possível definir esse valor como text_embedding para endpoints de modelo de embedding de texto ou generic para todos os outros endpoints de modelo.
MODEL_QUALIFIED_NAME	Obrigatório para endpoints de modelo da OpenAI; pode ser NULL para outros endpoints de modelo	O nome totalmente qualificado caso o endpoint de modelo tenha várias versões ou se o endpoint de modelo o definir. Por exemplo, textembedding-gecko@001 ou textembedding-gecko@002. Como o modelo textembedding-gecko@001 está pré-registrado no gerenciamento de endpoints de modelo, é possível gerar embeddings usando textembedding-gecko@001 como o ID do modelo.
AUTH_TYPE	Pode ser NULL, a menos que o endpoint de modelo tenha um requisito de autenticação específico	O tipo de autenticação usado pelo endpoint de modelo. É possível defini-lo como auth_type_cloudsql_service_agent_iam para modelos da Vertex AI ou auth_type_secret_manager para outros provedores.
AUTH_ID	Transmita como NULL para endpoints da Vertex AI; obrigatório para todos os outros endpoints de modelo que armazenam secrets no Secret Manager	O ID do secret definido e usado posteriormente ao registrar um endpoint de modelo.
GENERATE_HEADER_FUNCTION	Pode ser NULL	O nome da função definida para gerar cabeçalhos personalizados. A assinatura dessa função depende da função mysql.ml_predict_row(). Consulte Função de geração de cabeçalho HTTP.
INPUT_TRANSFORM_FUNCTION	Opcional para endpoints de modelo de embedding de texto com suporte integrado; não defina para endpoints de modelo genéricos	A função para transformar a entrada da função de previsão correspondente na entrada específica do modelo. Consulte Funções de transformação.
OUTPUT_TRANSFORM_FUNCTION	Opcional para endpoints de modelo de embedding de texto com suporte integrado; não defina para endpoints de modelo genéricos	A função para transformar a saída específica do modelo na saída da função de previsão. Consulte Funções de transformação.

mysql.ml_alter_model_registration()

Confira a seguir como chamar a função SQL mysql.ml_alter_model_registration() usada para atualizar metadados de endpoints de 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 remover um endpoint de modelo:

  CALL mysql.ml_drop_model_registration('MODEL_ID');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o endpoint de modelo definido.

mysql.ml_list_registered_model()

Confira a seguir como chamar a função SQL mysql.ml_list_registered_model() usada para listar informações de endpoints de modelo:

  SELECT mysql.ml_list_registered_model('MODEL_ID');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o endpoint de modelo definido.

mysql.cloudsql_ml_models

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

  SELECT * FROM mysql.cloudsql_ml_models;

Secrets

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

mysql.ml_create_sm_secret_registration()

Confira a seguir 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');

Parâmetro	Descrição
SECRET_ID	O ID do secret definido e usado posteriormente ao registrar um endpoint de modelo.
PROJECT_ID	O ID do Google Cloud projeto que contém o secret. Esse projeto pode ser diferente do projeto que contém a instância do Cloud SQL.
SECRET_MANAGER_SECRET_ID	O ID do secret definido no Secret Manager quando você criou o secret.
VERSION_NUMBER	O número da versão do ID do secret.

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 de secrets:

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

Parâmetro	Descrição
SECRET_ID	O ID do secret definido e usado posteriormente ao registrar um endpoint de modelo.
PROJECT_ID	O ID do Google Cloud projeto que contém o secret. Esse projeto pode ser diferente do projeto que contém a instância do Cloud SQL.
SECRET_MANAGER_SECRET_ID	O ID do secret definido no Secret Manager quando você criou o secret.
VERSION_NUMBER	O número da versão do ID do secret.

mysql.ml_drop_sm_secret_registration()

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

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

Parâmetro	Descrição
SECRET_ID	O ID do secret definido e usado posteriormente ao registrar um endpoint de modelo.

Funções de Prediction

Use esta referência para entender os parâmetros de 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');

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o endpoint de modelo definido.
CONTENT	O texto a ser traduzido em um embedding de vetor.

Para exemplos de consultas SQL para gerar embeddings de texto, consulte Exemplos.

mysql.ml_predict_row()

Confira a seguir como invocar previsões:

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

Parâmetro	Descrição
MODEL_ID	Um ID exclusivo para o endpoint de modelo definido.
REQUEST_BODY	Os parâmetros para a chamada de previsão, no formato JSON.

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

Confira a seguir a assinatura da função de previsão para endpoints de modelo de embedding de texto:

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

Parâmetro	Descrição
INPUT_TRANSFORM_FUNCTION	A função para transformar a entrada da função de previsão correspondente na entrada específica do endpoint de modelo.

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

Confira a seguir a assinatura da função de previsão para endpoints de modelo de embedding de texto:

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

Parâmetro	Descrição
OUTPUT_TRANSFORM_FUNCTION	A função para transformar a saída específica do endpoint de modelo na saída da função de previsão.

Exemplo de funções de transformação

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

O exemplo de solicitação curl a seguir cria embeddings com base no prompt e no endpoint de 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, uma para cada entrada de prompt no modelo. Como a função mysql.ml_embedding() é uma função de nível de linha, ela retorna uma única entrada por vez. Portanto, é necessário criar uma função de transformação de saída que possa ser usada para extrair o embedding da matriz.

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:

função de transformação 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 $$

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

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 ;