模型端点管理概览

本页面介绍如何使用 Cloud SQL 中的模型端点管理来注册 AI 模型端点和调用预测。 如需在生产环境中使用 AI 模型，请参阅生成和管理向量嵌入。

概览

借助模型端点管理，您可以注册模型端点、在 Cloud SQL 实例中管理模型端点元数据，然后使用 SQL 查询与模型进行交互。 您可以使用这些模型生成向量嵌入或调用预测。

您可以使用模型端点管理功能注册以下模型类型：

  • Vertex AI 文本嵌入模型。
  • 托管在 Google Cloud内的网络中的自定义托管文本嵌入模型。

  • 使用基于 JSON 的 API 的通用模型。这些模型的示例包括：

    • Vertex AI Model Garden 中的 gemini-flash 模型
    • OpenAI 模型的 open_ai 模型
    • 在 Google Cloud内的网络中托管的模型

工作原理

您可以使用模型端点管理功能注册符合以下条件的模型端点：

  • 模型输入和输出支持 JSON 格式。
  • 您可以使用 REST 协议来调用模型。

当您使用模型端点管理注册模型端点时，模型端点管理会使用唯一的模型 ID 注册每个端点，以作为对模型的引用。您可以使用此模型 ID 来查询模型，如下所示：

  • 生成嵌入以将文本提示转换为数值向量。 在实例上启用向量嵌入支持后，您可以将生成的嵌入存储为向量数据。如需了解详情，请参阅在实例中启用和停用向量嵌入。

  • 调用预测以在事务中使用 SQL 调用模型。

如需使用 Cloud SQL 实例注册和调用远程 AI 模型，您的实例必须安装维护版本 MYSQL_VERSION.R20250531.01_14 或更高版本。如果您的实例运行的维护版本低于 MYSQL_VERSION.R20250531.01_14，则只能使用以下函数（如集成 Cloud SQL 和 Vertex AI 中所述）。

如需将实例升级到维护版本 MYSQL_VERSION.R20250531.01_14 或更高版本，请参阅自助维护。 升级实例后，您可以使用以下功能：

此外，您还可以将以下函数与已注册的模型提供方搭配使用：

必需的数据库用户权限

如需注册和调用远程 AI 模型，您必须以 MySQL 数据库用户的身份登录，并且该用户已被授予 SELECT 和 EXECUTE 权限以及 mysql.* 权限。

默认情况下，任何具有 cloudsqlsuperuser 角色的用户都拥有这些权限，或者可以创建用户并授予所需的权限。

如需详细了解 Cloud SQL 中的 cloudsqlsuperuser 角色，请参阅 MySQL 8.0 用户权限和 MySQL 8.4 用户权限。

主要概念

在开始使用模型端点管理之前，请了解连接到模型和使用模型所需的概念。

模型提供商

模型提供商是指支持的模型托管服务提供商。下表显示了您必须根据所使用的模型提供商设置的模型提供商值：

模型提供商 在函数中设置为…
Vertex AI（包括 Gemini） google
Anthropic anthropic
Hugging Face hugging_face
OpenAI open_ai
在 Vertex AI 之外托管的其他模型，例如
Anthropic、Hugging Face 和 OpenAI		 custom

默认的模型提供商为 custom。

模型类型

模型类型是指 AI 模型的类型。注册模型端点时，您可以为端点设置 text_embedding 或 generic 模型类型。

如果您使用 Vertex AI 作为模型提供方，则无需注册模型端点，因为系统会自动支持这些端点。 默认情况下，使用 Vertex AI 时，您会使用 text-embedding-005 模型。

其他文本嵌入模型
对于其他文本嵌入模型，您需要创建转换函数来处理模型支持的输入和输出格式。（可选）您可以使用 HTTP 标头生成函数，它可以生成模型所需的自定义标头。

这些模型的类型为 text_embedding。

通用模型
除了文本嵌入模型之外，模型端点管理还支持注册所有其他类型的模型。如需为通用模型调用预测，请使用 mysql.ml_predict_row() 函数。您可以设置模型端点元数据，例如模型特有的请求端点和 HTTP 标头。
注册通用模型端点时，您无法传递转换函数。请确保在调用预测时，函数的输入采用 JSON 格式，并确保解析 JSON 输出以获得最终输出。
这些模型的类型为 generic。由于 generic 是默认模型类型，因此如果您要注册此类型的模型端点，那么设置模型类型是可选操作。
借助 Vertex AI，模型端点管理包含对 gemini-2.5-flash 模型的预注册支持。

身份验证方法

您可以在 Cloud SQL for MySQL 实例中启用对向量嵌入的支持，然后指定不同的身份验证方法来访问模型。设置这些方法是可选操作，只有在您需要通过身份验证才能访问模型时才需要设置这些方法。

对于 Vertex AI 模型，Cloud SQL 服务账号用于进行身份验证。对于其他模型，在 Secret Manager 中作为 Secret 存储的 API 密钥或不记名令牌可与 mysql.ml_create_sm_secret_registration() SQL 函数搭配使用。

下表列出了您可以设置的身份验证方法：

身份验证方法 在函数中设置为… 模型提供商
Cloud SQL 服务代理 auth_type_cloudsql_service_agent_iam Vertex AI 提供商
Secret Manager auth_type_secret_manager 在 Vertex AI 外部托管的模型

预测函数

mysql.ml_embedding()
调用已注册的文本嵌入模型端点以生成嵌入。它包含对 Vertex AI 的所有嵌入模型的内置支持。
对于不提供内置支持的文本嵌入模型，输入和输出参数是模型所特有的，需要进行转换，才能让函数调用模型。创建一个转换输入函数，以将预测函数的输入转换为模型特有的输入，并创建一个转换输出函数，以将模型特有的输出转换为预测函数输出。
mysql.ml_predict_row()
：如果端点支持使用基于 JSON 的 API 来调用预测，则调用已注册的通用模型端点。

转换函数

转换函数会将输入内容修改为模型可理解的格式，并将模型响应转换为预测函数所需的格式。在注册没有内置支持的 text-embedding 模型端点时，会使用转换函数。转换函数的签名取决于模型类型的预测函数。

注册 generic 模型端点时，您无法使用转换函数。

以下示例展示了文本嵌入模型的预测函数签名：

// define custom model specific input/output transform functions.
CREATE FUNCTION IF NOT EXISTS input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

// the returned BLOB should be of type VECTOR
CREATE FUNCTION IF NOT EXISTS output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

如需详细了解如何创建转换函数，请参阅转换函数示例。

HTTP 标头生成函数

HTTP 标头生成函数会以 JSON 键值对的形式生成输出，这些键值对会用作 HTTP 标头。预测函数的签名定义了标头生成函数的签名。

以下示例展示了 mysql.ml_embedding() 预测函数的签名：

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

对于 mysql.ml_predict_row() 预测函数，签名如下所示：

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON DETERMINISTIC;

如需详细了解如何创建标头生成函数，请参阅标头生成函数示例。

限制

  • 当您运行任何模型注册或密钥管理函数时，系统会隐式提交会话中的所有未完成的事务。预测函数不会隐式提交事务。

  • 如果您使用 mysqldump 导出或导入数据库，则不会导出模型端点目录。

  • 包含转换函数的用户数据库的名称中不能包含句点字符 ('.')。例如，不支持名为 my.sql 的数据库。

  • 模型端点管理仅适用于 Cloud SQL for MySQL 8.0.36 及更高版本。

后续步骤