此页面由 Cloud Translation API 翻译。

使用模型端点管理注册和调用远程 AI 模型

MySQL | PostgreSQL | SQL Server

本页面介绍了如何使用模型调用预测或生成嵌入，然后向模型端点管理注册模型端点。

如需详细了解 mysql.ml_create_model_registration() 函数，请参阅模型端点管理参考文档。

准备工作

根据模型提供方设置身份验证。

使用 mysql 客户端或 Cloud SQL Studio 连接到主实例。
请确保您以具有必需的数据库用户权限中所述数据库权限的 MySQL 数据库用户身份连接到数据库。

设置身份验证

以下部分介绍了如何在添加托管在 Google Cloud中的一个或多个 Vertex AI 模型端点之前设置身份验证。

设置 Vertex AI 身份验证

如需使用 Google Vertex AI 模型端点，您必须向用于连接到数据库的基于 IAM 的 Cloud SQL 服务账号添加 Vertex AI 权限。如需详细了解如何与 Vertex AI 集成，请参阅将 Cloud SQL 与 Vertex AI 集成。

为自定义托管模型设置身份验证

本部分介绍了如何在使用 Secret Manager 时设置身份验证。对于除 Vertex AI 模型端点以外的所有模型，您都可以将 API 密钥或不记名令牌存储在 Secret Manager 中。

如果您的模型端点不通过 Secret Manager 处理身份验证，则此部分是可选的。例如，如果您的模型端点使用 HTTP 标头来传递身份验证信息，或者根本不使用身份验证，则无需完成本部分中的步骤。

如需创建和使用 API 密钥或不记名令牌，请完成以下步骤：

在 Secret Manager 中创建 Secret。如需了解详情，请参阅创建 Secret 并访问 Secret 版本。

Secret 名称和 Secret 路径会在 mysql.ml_create_sm_secret_registration() SQL 函数中使用。
向 Cloud SQL 实例授予访问 Secret 的权限。
```
  gcloud secrets add-iam-policy-binding SECRET_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role="roles/secretmanager.secretAccessor"
```
替换以下内容：
- SECRET_ID：Secret Manager 中的 Secret ID。
- SERVICE_ACCOUNT_EMAIL：基于 IAM 的 Cloud SQL 服务账号的电子邮件地址。如需查找此电子邮件地址，请使用 gcloud sql instances describe INSTANCE_NAME 命令，并将 INSTANCE_NAME 替换为实例的名称。 serviceAccountEmailAddress 参数旁边显示的值即电子邮件地址。

具有内置支持的文本嵌入模型

本部分介绍如何注册模型端点以进行模型端点管理。

Vertex AI 嵌入模型

模型端点管理针对 Vertex AI 的所有版本的 text-embedding-gecko、text-embedding 和 gemini-embedding 模型提供内置支持。使用限定名称将模型版本设为 textembedding-gecko@001 或 textembedding-gecko@002。

由于模型端点管理默认支持 Vertex AI 嵌入模型端点 ID，因此您可以直接将其中任一项用作模型 ID。对于这些模型，嵌入函数会自动执行输入和输出转换。

确保 Cloud SQL 实例和您所查询的 Vertex AI 模型位于同一区域。

如需注册 gemini-embedding-001 模型端点，请调用 ml_create_model_registration 函数：

  CALL
    mysql.ml_create_model_registration(
      'gemini-embedding-001',
      'publishers/google/models/gemini-embedding-001',
      'google','text_embedding', 'gemini-embedding-001',
      'AUTH_TYPE_CLOUDSQL_SERVICE_AGENT_IAM',
       NULL,
      'mysql.cloudsql_ml_text_embedding_input_transform',
      'mysql.cloudsql_ml_text_embedding_output_transform', NULL);

自定义托管文本嵌入模型

本部分介绍了如何注册在 Google Cloud的网络中托管的自定义模型端点。

添加自定义托管文本嵌入模型端点涉及创建转换函数以及视情况创建自定义 HTTP 标头。另一方面，添加自定义托管通用模型端点涉及视情况生成自定义 HTTP 标头和设置模型请求网址。

以下示例添加由 Cymbal 托管的 custom-embedding-model 文本嵌入模型端点，该端点托管在 Google Cloud中。cymbal_text_input_transform 和 cymbal_text_output_transform 转换函数用于将模型的输入和输出格式转换为预测函数的输入和输出格式。

如需注册自定义托管文本嵌入模型端点，请完成以下步骤：

调用存储在 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：您设置的 Secret ID，随后在注册模型端点时会用到，例如 key1。
- SECRET_MANAGER_SECRET_ID：您创建 Secret 时在 Secret Manager 中设置的 Secret ID。
- PROJECT_ID：您的 Google Cloud 项目的 ID。
- VERSION_NUMBER：Secret ID 的版本号。
注意：Secret Manager 默认会生成 Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER 标头来进行身份验证。如果此格式与您的模型端点的授权不记名令牌格式一致，则您无需使用标头生成函数生成授权标头。

根据以下签名为文本嵌入模型端点的预测函数创建输入和输出转换函数。如需详细了解如何创建转换函数，请参阅转换函数示例。

以下是特定于 custom-embedding-model 文本嵌入模型端点的转换函数示例：

-- Input Transform Function corresponding to the custom model endpoint
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 $$

-- Output Transform Function corresponding to the custom model endpoint
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 ;

调用 create model 函数以注册自定义嵌入模型端点：

   CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'REQUEST_URL',
        'custom',
        'text_embedding',
        'MODEL_QUALIFIED_NAME',
        'auth_type_secret_manager',
        'SECRET_ID'
        'database_name.cymbal_text_input_transform',
        'database_name.cymbal_text_output_transform', NULL);

替换以下内容：

MODEL_ID：必填。您定义的模型端点的唯一 ID（例如 custom-embedding-model）。系统会引用此模型 ID 以用于模型端点生成嵌入或调用预测所需的元数据。
REQUEST_URL：必填。添加自定义文本嵌入和通用模型端点时的特定于模型的端点，例如 https://cymbal.com/models/text/embeddings/v1。确保可以通过内部 IP 地址访问模型端点。模型端点管理不支持外部 IP 地址。
MODEL_QUALIFIED_NAME：如果您的模型端点使用限定名称，则需要此参数。如果模型端点具有多个版本，则为完全限定名称。
SECRET_ID：您之前在 mysql.ml_create_sm_secret_registration() 过程中使用的 Secret ID。

通用模型

本部分介绍如何注册来自 Vertex AI Model Garden 的通用 gemini-flash 模型端点，该端点默认已预注册到目录中。您可以注册托管在 Google Cloud中的任何通用模型端点。

Cloud SQL 仅支持通过 Vertex AI Model Garden 提供的模型端点，以及托管在 Google Cloud的网络中的模型端点。

Gemini 模型

以下示例会使用来自 Vertex AI Model Garden 的 gemini-2.5-flash 模型端点。

如需注册 gemini-2.5-flash 模型端点，请调用 mysql.ml_create_model_registration 函数：

    CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-flash:streamGenerateContent',
        'google',
        'auth_type_cloudsql_service_agent_iam',
        NULL, NULL, NULL, NULL);