Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance da S3NS. Consulte Diferenças do Google Cloud para saber mais.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Referência de gerenciamento de endpoints de modelo

MySQL | PostgreSQL

Nesta página, listamos 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.

Modelos

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

`mysql.ml_create_model_registration()`

Veja a seguir como usar a função mysql.ml_create_model_registration() para registrar metadados de endpoint 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 do modelo que você define.
`REQUEST_URL`	Pode ser nulo para modelos de IA do Vertex AI	O endpoint específico do modelo ao adicionar outros endpoints de embedding de texto e de modelo genérico. O URL de solicitação que a função gera para endpoints de modelo integrado se refere ao projeto e à região ou ao local do cluster. Se você quiser se referir a outro projeto, especifique o `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 do modelo. O valor padrão é `custom`. Para o Cloud SQL, defina o provedor como `google` para endpoints de modelo de IA da Vertex AI, `open_ai` para endpoints de modelo de IA da OpenAI, `anthropic` para endpoints de modelo de IA da Anthropic, `hugging_face` para endpoints de modelo de IA da Hugging Face ou `custom` para endpoints de modelo de IA hospedados pelo cliente.
`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 do modelo tenha várias versões ou se o endpoint do modelo o definir, por exemplo, `textembedding-gecko@001` ou `textembedding-gecko@002`. Como o modelo `textembedding-gecko@001` é pré-registrado com o 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 do modelo tenha um requisito de autenticação específico	O tipo de autenticação usado pelo endpoint do modelo. É possível definir como `auth_type_cloudsql_service_agent_iam` para modelos de IA da Vertex AI ou `auth_type_secret_manager` para outros provedores.
`AUTH_ID`	Passe 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 que você definiu e que é usado ao registrar um endpoint de modelo.
`GENERATE_HEADER_FUNCTION`	Pode ser NULL	O nome da função que você definiu 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()`

Veja 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()`

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

  CALL mysql.ml_drop_model_registration('MODEL_ID');

Parâmetro	Descrição
`MODEL_ID`	Um ID exclusivo para o endpoint do modelo que você define.

`mysql.ml_list_registered_model()`

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

  SELECT mysql.ml_list_registered_model('MODEL_ID');

Parâmetro	Descrição
`MODEL_ID`	Um ID exclusivo para o endpoint do modelo que você define.

`mysql.cloudsql_ml_models`

Veja a seguir 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 de funções que permitem gerenciar secrets.

`mysql.ml_create_sm_secret_registration()`

Veja 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 que você definiu e que é usado ao registrar um endpoint de modelo.
`PROJECT_ID`	O ID do projeto do Cloud de Confiance by S3NS que contém o secret. Esse projeto pode ser diferente daquele 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()`

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

Parâmetro	Descrição
`SECRET_ID`	O ID do secret que você definiu e que é usado ao registrar um endpoint de modelo.
`PROJECT_ID`	O ID do projeto do Cloud de Confiance by S3NS que contém o secret. Esse projeto pode ser diferente daquele 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()`

Veja 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 que você definiu e que é usado ao registrar um endpoint de modelo.

Funções de previsão

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

`mysql.ml_embedding()`

Veja a seguir como gerar embeddings:

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

Parâmetro	Descrição
`MODEL_ID`	Um ID exclusivo para o endpoint do modelo que você define.
`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()`

Veja 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 do modelo que você define.
`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 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 do modelo.

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

Confira 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 do 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 do modelo, considere um endpoint de modelo de embedding de texto hospedado pelo cliente que requer 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 uma 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 comando inserido 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 com o 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 ;