模型端点管理参考文档

预览版

此产品需遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版产品“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

MySQL   |  PostgreSQL   |  SQL Server

本页列出了 Cloud SQL 提供的用于注册和管理模型端点的不同函数的参数。该页面还会列出您可以使用模型端点管理功能管理的 Secret。

注意： 如需详细了解模型端点管理，请参阅在 Cloud SQL 中注册和调用远程 AI 模型。

模型

请参阅此参考文档，了解可让您管理模型端点的函数的参数。

mysql.ml_create_model_registration()

以下示例展示了如何使用 mysql.ml_create_model_registration() 函数注册模型端点元数据：

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

参数	必需	说明
MODEL_ID	所有模型端点都必须包含此字段	您定义的模型端点的唯一 ID。
REQUEST_URL	对于 Vertex AI 模型，可以为 NULL	添加其他文本嵌入和通用模型端点时，相应模型的端点。 该函数为内置模型端点生成的请求网址，默认引用集群所属项目和区域。如果您要引用其他项目，请务必明确指定 model_request_url。 对于自定义托管的模型端点，请确保模型端点能通过互联网访问。
PROVIDER_ID	内置支持的文本嵌入模型端点需要使用此值	模型端点的提供方。默认值为 custom。对于 Cloud SQL，如果是 Vertex AI 模型端点，请将提供程序设置为 google；如果是 OpenAI 模型端点，请将提供程序设置为 open_ai；如果是 Anthropic 模型端点，请将提供程序设置为 anthropic；如果是 Hugging Face 模型端点，请将提供程序设置为 hugging_face；如果是自定义托管模型端点，请将提供程序设置为 custom。
MODEL_TYPE	对于通用模型端点，可以为 NULL	模型类型。对于文本嵌入模型端点，您可以将此值设置为 text_embedding；对于所有其他模型端点，您可以将此值设置为 generic。
MODEL_QUALIFIED_NAME	对于 OpenAI 模型端点，此字段是必需的；对于其他模型端点，此字段可以为 NULL	如果模型端点有多个版本，或者模型端点定义了该名称，则为完全限定名称，例如 textembedding-gecko@001 或 textembedding-gecko@002。由于 textembedding-gecko@001 模型已在模型端点管理中预先注册，因此您可以使用 textembedding-gecko@001 作为模型 ID 来生成嵌入。
AUTH_TYPE	可以为 NULL，除非模型端点有特定的身份验证要求	模型端点使用的身份验证类型。对于 Vertex AI 模型，您可以将其设置为 auth_type_cloudsql_service_agent_iam；对于其他提供方，您可以将其设置为 auth_type_secret_manager。
AUTH_ID	对于 Vertex AI 端点，请传递为 NULL；但对于所有将 Secret 存储在 Secret Manager 中的其他模型端点，必须设置此属性。	您设置的秘密 ID，随后在注册模型端点时会使用该 ID。
GENERATE_HEADER_FUNCTION	可以为 NULL	您设置用于生成自定义标头的函数的名称。此函数的签名取决于 mysql.ml_predict_row() 函数。请参阅 HTTP 标头生成函数。
INPUT_TRANSFORM_FUNCTION	对于具有内置支持的文本嵌入模型端点是可选的；但对于通用模型端点，请勿设置	用于将相应预测函数的输入转换为特定于模型的输入的函数。请参阅转换函数。
OUTPUT_TRANSFORM_FUNCTION	对于具有内置支持的文本嵌入模型端点是可选的；但对于通用模型端点，请勿设置	用于将模型专用输出转换为预测函数输出的函数。请参阅转换函数。

mysql.ml_alter_model_registration()

以下示例展示了如何调用用于更新模型端点元数据的 mysql.ml_alter_model_registration() SQL 函数：

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

以下示例展示了如何调用用于删除模型端点的 mysql.ml_drop_model_registration() SQL 函数：

  CALL mysql.ml_drop_model_registration('MODEL_ID');

参数	说明
MODEL_ID	您定义的模型端点的唯一 ID。

mysql.ml_list_registered_model()

以下代码展示了如何调用用于列出模型端点信息的 mysql.ml_list_registered_model() SQL 函数：

  SELECT mysql.ml_list_registered_model('MODEL_ID');

参数	说明
MODEL_ID	您定义的模型端点的唯一 ID。

mysql.cloudsql_ml_models

以下示例展示了如何查询 mysql.cloudsql_ml_models 表，该表用于列出所有模型端点的模型端点信息：

  SELECT * FROM mysql.cloudsql_ml_models;

Secret

请参阅此参考文档，了解可让您管理 Secret 的函数的参数。

mysql.ml_create_sm_secret_registration()

以下示例展示了如何调用 mysql.ml_create_sm_secret_registration() SQL 函数，该函数用于添加在 Secret Manager 中创建的 Secret：

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

参数	说明
SECRET_ID	您设置的秘密 ID，随后在注册模型端点时会使用该 ID。
PROJECT_ID	包含 Secret 的 Google Cloud 项目的 ID。此项目可以与包含 Cloud SQL 实例的项目不同。
SECRET_MANAGER_SECRET_ID	您创建 Secret 时在 Secret Manager 中设置的 Secret ID。
VERSION_NUMBER	Secret ID 的版本号。

mysql.ml_alter_sm_secret_registration()

以下示例展示了如何调用用于更新 Secret 信息的 mysql.ml_alter_sm_secret_registration() SQL 函数：

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

参数	说明
SECRET_ID	您设置的秘密 ID，随后在注册模型端点时会使用该 ID。
PROJECT_ID	包含 Secret 的 Google Cloud 项目的 ID。此项目可以与包含 Cloud SQL 实例的项目不同。
SECRET_MANAGER_SECRET_ID	您创建 Secret 时在 Secret Manager 中设置的 Secret ID。
VERSION_NUMBER	Secret ID 的版本号。

mysql.ml_drop_sm_secret_registration()

以下示例展示了如何调用用于删除 Secret 的 mysql.ml_drop_sm_secret_registration() SQL 函数：

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

参数	说明
SECRET_ID	您设置的秘密 ID，随后在注册模型端点时会使用该 ID。

预测函数

使用此参考文档了解可让您生成嵌入或调用预测的函数的参数。

mysql.ml_embedding()

以下示例展示了如何生成嵌入：

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

参数	说明
MODEL_ID	您定义的模型端点的唯一 ID。
CONTENT	要转换为向量嵌入的文本。

如需查看用于生成文本嵌入的 SQL 查询示例，请参阅示例。

mysql.ml_predict_row()

以下示例展示了如何调用预测：

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

参数	说明
MODEL_ID	您定义的模型端点的唯一 ID。
REQUEST_BODY	以 JSON 格式表示的预测函数参数。

如需查看用于调用预测的 SQL 查询示例，请参阅示例。

转换函数

请参阅此参考文档，了解输入和输出转换函数的参数。

输入转换函数

下方显示了文本嵌入模型端点的预测函数签名：

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

参数	说明
INPUT_TRANSFORM_FUNCTION	用于将相应预测函数的输入转换为模型端点专用输入的函数。

输出转换函数

下方显示了文本嵌入模型端点的预测函数签名：

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

参数	说明
OUTPUT_TRANSFORM_FUNCTION	用于将模型端点专用输出转换为预测函数输出的函数。

转换函数示例

如需更好地了解如何为模型端点创建转换函数，请考虑需要 JSON 输入和输出的自定义托管文本嵌入模型端点。

以下示例 curl 请求会根据提示和模型端点创建嵌入：

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

系统会返回以下示例响应：

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

根据此输入和响应，您可以推断出以下内容：

• 该模型需要通过 prompt 字段输入 JSON。此字段接受输入数组。由于 mysql.ml_embedding() 函数是行级函数，因此它需要一次输入一个文本。因此，您需要创建一个输入转换函数，以构建包含单个元素的数组。

• 模型的响应是嵌入数组，每个提示输入到模型中都有一个嵌入。由于 mysql.ml_embedding() 函数是行级函数，因此它一次只返回一个输入。因此，您需要创建一个输出转换函数，该函数可用于从数组中提取嵌入。

以下示例展示了在模型端点注册到模型端点管理时，此模型端点使用的输入和输出转换函数：

输入转换函数

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;

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 ;