将 Cloud SQL 与 Vertex AI 集成

本页面介绍了如何将 Cloud SQL 与 Vertex AI 集成。

借助此集成，您可以将托管在 Vertex AI 中的大语言模型 (LLM) 应用于 Cloud SQL for SQL Server 2025 数据库。

通过将 Cloud SQL 与 Vertex AI 集成，您可以将机器学习 (ML) 模型的语义和预测能力应用于您的数据。此集成通过用于查询模型的生成嵌入函数扩展 SQL 语法。

您可以使用生成嵌入函数，以便嵌入模型将文本提示转换为数值向量。然后，您可以将这些向量嵌入作为输入应用于向量数据类型。如需了解详情，请参阅 Microsoft 文档中的 SQL 数据库引擎中的向量搜索和向量索引。

如需详细了解 Vertex AI，请参阅 Vertex AI 简介。

支持的版本和数据库版本

Cloud SQL 企业 Plus 版和 Cloud SQL 企业版以及所有 SQL Server 2025 数据库版本均支持 Vertex AI 集成。

支持的模型类型

Vertex AI 与 Cloud SQL 的集成支持来自以下来源的模型端点：

  • Vertex AI
  • Hugging Face
  • OpenAI

准备工作

  1. 登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 启用必要的 Google Cloud API。

    控制台

    1. 进入 API 和服务页面。
    2. 从项目列表中，选择一个项目。
    3. 如果 API 库未打开，请从导航菜单中选择库。

    4. 点击您要启用的 API。在此过程中，请启用以下功能：

      • Cloud SQL Admin API
      • Vertex AI API
      • Compute Engine API
      • 可选：如果使用第三方模型，则需要 Secret Manager API。
    5. 选择每个 API 后，点击启用。

    gcloud

    1. 打开 Cloud Shell，以直接在浏览器中通过命令行访问您的 Google Cloud 资源。
    2. 如需启用所需的 API，请使用 gcloud services enable 命令： 
      gcloud services enable sqladmin.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com \
  secretmanager.googleapis.com
      3. 此命令会启用以下 API：
      • Cloud SQL Admin API
      • Vertex AI API
      • Compute Engine API
      • 可选：如果使用第三方模型，则需要 Secret Manager API。

  7. 授予 Cloud SQL 服务账号访问 Vertex AI 的 Identity and Access Management (IAM) 权限。

    8. gcloud

    如需为 Cloud SQL 服务账号添加 Cloud SQL 实例所在的项目的 Vertex AI 权限，请使用 gcloud projects add-iam-policy-binding 命令： 

    gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
--role="roles/aiplatform.user"

    进行以下替换：
    • PROJECT_ID：具有 Vertex AI 端点的项目的 ID。Cloud SQL 使用此端点来访问 Vertex AI 中托管的 LLM。

    • SERVICE_ACCOUNT_EMAIL：Cloud SQL 服务账号的电子邮件地址。

      如需查找此电子邮件地址，请使用 gcloud sql instances describe 命令： 

      gcloud sql instances describe INSTANCE_NAME | grep EmailAddress

      将 INSTANCE_NAME 替换为 Cloud SQL 实例的名称。

  8. 确保使用嵌入模型的 Cloud SQL 用户已获得以下数据库权限：
    • 如需允许数据库用户创建或修改模型，您需要向 Cloud SQL 用户授予对以下存储过程的 EXECUTE 权限：
      • [msdb].gcloudsql_ml_create_external_model：创建包含 AI 模型推理端点的位置、身份验证方法和用途的外部模型对象。
      • [msdb].gcloudsql_ml_alter_external_model：允许您修改外部模型对象。
      • [msdb].gcloudsql_ml_drop_external_model：从数据库中移除外部模型对象。
    • 如需调用前面列出的存储过程，您需要在目标数据库中拥有以下权限：
      • CREATE EXTERNAL MODEL
      • ALTER EXTERNAL MODEL

      • 如需了解如何授予这些权限，请参阅 Microsoft 文档，了解 Create external model 命令和命名规范。

      如需了解 Cloud SQL 超级用户权限，请参阅关于 SQL Server 用户和存储过程。

  9. 如果您想使用第三方外部模型，则必须在 Cloud SQL 实例可访问的 Secret Manager 位置存储该模型的有效 API 密钥。
  10. 如果使用第三方外部模型，则 Cloud SQL 实例必须使用公共 IP 地址。专用 IP 实例无法访问第三方外部模型。专用服务访问通道和 Private Service Connect 仅支持与 Vertex AI 集成。

启用数据库与 Vertex AI 的集成

如需启用数据库与 Vertex AI 的集成，请完成以下步骤：

  1. 创建或更新 Cloud SQL 实例，使该实例可以与 Vertex AI 集成。

    gcloud

    创建实例

    如需创建 Cloud SQL 实例，请使用 gcloud sql instances create 命令。

    gcloud sql instances create INSTANCE_NAME \
--database-version=DATABASE_VERSION \
--tier=MACHINE_TYPE \
--region=REGION_NAME \
--enable-google-ml-integration

    进行以下替换：

    • INSTANCE_NAME：实例的名称。
    • DATABASE_VERSION：实例的数据库版本，例如 SQLSERVER_2025_ENTERPRISE。
    • MACHINE_TYPE：实例的机器类型，例如 db-perf-optimized-N-8.。
    • REGION_NAME：实例的区域，例如 us-central1。

    更新实例

    如需更新实例，请使用 gcloud sql instances patch 命令。

    gcloud sql instances patch INSTANCE_NAME \
--enable-google-ml-integration

    REST v1

    创建实例

    使用此示例创建实例。如需查看此调用的完整参数列表，请参阅 instances:insert 页面。如需了解实例设置，包括有效区域值，请参阅实例设置。

    在使用任何请求数据之前，请先进行以下替换：

    • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号。
    • INSTANCE_NAME：实例的名称。
    • REGION_NAME：实例的区域名称。
    • DATABASE_VERSION：数据库版本的枚举字符串，例如 SQLSERVER_2025_ENTERPRISE。
    • PASSWORD：数据库 root 用户的密码。
    • MACHINE_TYPE：机器（层级）类型的枚举字符串，例如 db-custom-[CPUS]-[MEMORY_MBS]。如需了解详情，请参阅机器层级。
    • EDITION_TYPE：您的 Cloud SQL 版本，例如 ENTERPRISE。

    您还必须在请求中添加 enableGoogleMlIntegration 对象。根据需要设置以下参数：

    • enableGoogleMlIntegration：当此参数设置为 true 时，Cloud SQL 实例可以连接到 Vertex AI，以将针对实时预测和数据洞见的请求传递给 AI。

    HTTP 方法和网址：

    POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

    请求 JSON 正文：

    {
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableGoogleMlIntegration": "true" | "false"
    
  }
}

    如需发送您的请求，请展开以下选项之一：

    您应该收到类似以下内容的 JSON 响应：

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    更新实例

    使用此示例更新实例。如需查看此调用的完整参数列表，请参阅 instances.patch 页面。

    如果此更新修改的值需要重启实例，系统会提示您继续进行更改或取消操作。

    在使用任何请求数据之前，请先进行以下替换：

    • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
    • INSTANCE_NAME：实例的名称

    HTTP 方法和网址：

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    请求 JSON 正文：

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    
   }
}

    如需发送您的请求，请展开以下选项之一：

    您应该收到类似以下内容的 JSON 响应：

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    REST v1beta4

    创建实例

    使用此示例创建实例。如需查看此调用的完整参数列表，请参阅 instances:insert 页面。如需了解实例设置，包括有效区域值，请参阅实例设置。

    在使用任何请求数据之前，请先进行以下替换：

    • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号。
    • INSTANCE_NAME：实例的名称。
    • REGION_NAME：实例的区域名称。
    • DATABASE_VERSION：数据库版本的枚举字符串，例如 SQLSERVER_2025_ENTERPRISE。
    • PASSWORD：数据库 root 用户的密码。
    • MACHINE_TYPE：机器（层级）类型的枚举字符串，例如 db-custom-[CPUS]-[MEMORY_MBS]。如需了解详情，请参阅机器层级。
    • EDITION_TYPE：您的 Cloud SQL 版本，例如 ENTERPRISE。

    您还必须在请求中添加 enableGoogleMlIntegration 对象。根据需要设置以下参数：

    • enableGoogleMlIntegration：当此参数设置为 true 时，Cloud SQL 实例可以连接到 Vertex AI，以将针对实时预测和数据洞见的请求传递给 AI。

    HTTP 方法和网址：

    POST https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances

    请求 JSON 正文：

    {
  "name": "INSTANCE_NAME",
  "region": "REGION_NAME",
  "databaseVersion": "DATABASE_VERSION",
  "rootPassword": "PASSWORD",
  "settings": {
    "tier": "MACHINE_TYPE",
    "edition": "EDITION_TYPE",
    "enableGoogleMlIntegration": "true" | "false"
    
  }
}

    如需发送您的请求，请展开以下选项之一：

    您应该收到类似以下内容的 JSON 响应：

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2019-09-25T22:19:33.735Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

    更新实例

    使用此示例更新实例。如需查看此调用的完整参数列表，请参阅 instances.patch 页面。

    如果此更新修改的值需要重启实例，系统会提示您继续进行更改或取消操作。

    在使用任何请求数据之前，请先进行以下替换：

    • PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
    • INSTANCE_NAME：实例的名称

    HTTP 方法和网址：

    PATCH https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    请求 JSON 正文：

    {
  "settings": {
    "enableGoogleMlIntegration": true,
    
   }
}

    如需发送您的请求，请展开以下选项之一：

    您应该收到类似以下内容的 JSON 响应：

    {
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

添加 Secret Manager 权限

如果您想使用来自外部来源（例如 OpenAI 或 Hugging Face）的模型，则必须将模型来源的 API 密钥存储在 Secret Manager 中。

然后，您需要向 Cloud SQL 实例授予对 Secret Manager 中模型来源的 API 密钥的访问权限。如需获取访问权限，请运行以下命令：


SA_NAME=$(gcloud sql instances describe INSTANCE_NAME --format="value(serviceAccountEmailAddress)");

gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:${SA_NAME}" \
    --role="roles/secretmanager.secretAccessor"

替换以下内容：

  • INSTANCE_NAME：Cloud SQL 实例的名称。
  • SECRET_NAME：Secret 在 Secret Manager 中的名称。

外部模型对象

如需访问外部来源的模型，您需要创建一个供 SQL Server 使用的模型对象。Cloud SQL 提供了三个存储过程，可用于创建、更改和删除外部模型对象：

  • gcloudsql_ml_create_external_model
  • gcloudsql_ml_alter_external_model
  • gcloudsql_ml_drop_external_model

创建外部模型

如需创建模型，请运行 msdb 数据库中的 gcloudsql_ml_create_external_model 存储过程：

EXECUTE [msdb].[dbo].[gcloudsql_ml_create_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME,
@model_provider = 'MODEL_PROVIDER',
@model = 'MODEL',
@model_url = MODEL_URL,
@secret_url = SECRET_URL

替换以下内容：

  • DB_NAME：您希望在其中创建外部模型的目标数据库。
  • MODEL_NAME：新外部模型的名称。
  • MODEL_PROVIDER：模型提供方的名称，例如以下名称之一：
    • Vertex AI
    • OpenAI
    • Hugging Face
  • MODEL_URL：模型端点的网址。
  • MODEL：要调用的 AI 模型。例如：gemini-embedding-002。
  • SECRET_URL：如果 Vertex AI 是模型提供方，则此参数必须为空。如果使用外部模型，此值必须引用 API 密钥的 Secret Manager 位置。示例网址采用以下格式： 
        https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION

    替换以下内容：

    • PROJECT_ID：Secret 所在项目的 ID。
    • SECRET_NAME：Secret 在 Secret Manager 中的名称。
    • VERSION：相应密文的版本号。

更改外部模型

如需更改外部模型对象，请运行 msdb 数据库中的 gcloudsql_ml_alter_external_model 存储过程：

EXECUTE [msdb].[dbo].[gcloudsql_ml_alter_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME,
@model_provider = 'MODEL_PROVIDER',
@model = 'MODEL',
@model_url = MODEL_URL,
@secret_url = SECRET_URL

替换以下内容：

  • DB_NAME：要修改的模型所在的目标数据库。
  • MODEL_NAME：现有模型的名称。
  • MODEL_PROVIDER：模型提供方的名称，例如以下名称之一：
    • Vertex AI
    • OpenAI
    • Hugging Face
  • MODEL_URL：模型端点的网址。
  • MODEL：要调用的 AI 模型。例如 gemini-embedding-001。
  • SECRET_URL：如果 Vertex AI 是模型提供方，则此参数必须为空。如果使用外部模型，此值必须引用 API 密钥的 Secret Manager 位置。网址示例采用以下格式： 
        https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION

    替换以下内容：

    • PROJECT_ID：Secret 所在项目的 ID。
    • SECRET_NAME：Secret 在 Secret Manager 中的名称。
    • VERSION：相应密文的版本号。

停用 Vertex AI 集成

如需在 Cloud SQL 实例上停用 Vertex AI 集成，请运行以下命令：

gcloud sql instances patch [instance-name] --no-enable-google-ml-integration

将 INSTANCE_NAME 替换为 Cloud SQL 实例的名称。

在 SQL Server 中舍弃外部模型

如需从 SQL Server 中舍弃外部模型，请运行 msdb 数据库中的 gcloudsql_ml_drop_external_model 存储过程：

EXECUTE [msdb].[dbo].[gcloudsql_ml_drop_external_model]
@db = [DB_NAME],
@model_name = MODEL_NAME

替换以下内容：

  • DB_NAME：要舍弃的外部模型所在的目标数据库。
  • MODEL_NAME：要删除的外部模型的名称。

调用外部模型

在 Cloud SQL 实例上启用 Vertex AI 集成并创建供 SQL Server 使用的模型对象后，您可以调用 SQL Server AI_GENERATE_EMBEDDINGS 函数来为数据创建向量嵌入。

如需使用外部模型创建向量嵌入，请运行以下命令：

SELECT AI_GENERATE_EMBEDDINGS(N'Test Text' USE MODEL MODEL_NAME)

将 MODEL_NAME 替换为您要使用的模型的名称。

执行正文用户必须已通过适当的角色或授权被授予 EXECUTE ON EXTERNAL MODEL 权限。

如需了解详情，请参阅 Microsoft 关于外部模型授权的文档。

模型大小限制

某些模型（例如 gemini-embedding-01）的默认输出维度高于 SQL Server 对 float32 向量的支持，后者最多支持 1,998 个维度。如有必要，您必须使用向量基本类型的 float16（Microsoft 预览版功能），该功能最多可提供 3,996 个向量维度；或者必须在 AI_GENERATE_EMBEDDINGS 请求中提供维度参数以降低维度。

如需了解详情，请参阅矢量数据类型中的半精度浮点支持。

如需查看示例，请参阅以下内容：

DECLARE @params JSON = N'{"dimensions": "DIMENSIONS"}';
SELECT AI_GENERATE_EMBEDDINGS('This article introduces AI concepts.' USE MODEL MODEL_NAME PARAMETERS @params)

替换以下内容：

  • DIMENSIONS：您要用于模型的维度，例如 1536。此值以字符串形式接受。
  • MODEL_NAME：您要使用的模型的名称。

问题排查

以下是您可能会收到的潜在错误消息：

上下文 收到的错误或消息 可能的原因
CREATE/ALTER 流程 指定的模型提供商无效。 指定了不受支持的模型提供商。
CREATE/ALTER 流程 “指定的密令网址对相应模型提供方无效。” 对于 Vertex AI，密钥网址必须为空。对于其他模型提供商，不公开网址不得为空。
CREATE/ALTER/DROP 流程 “指定的模型名称无效。” 模型名称为必填字段。
CREATE/ALTER 流程 “指定的模型网址无效。” 模型网址为必填字段。
CREATE/ALTER/DROP 流程 “指定的数据库名称无效。” 有效的数据库名称为必填字段。
AI_GENERATE_EMBEDDINGS 个来电 各种错误代码，包括 400、403、404、405、500。 如果在尝试运行 AI_GENERATE_EMBEDDINGS 函数时遇到问题，系统只会返回错误代码。这是 Microsoft 的已知限制。
AI_GENERATE_EMBEDDINGS 个来电 “HTTP 响应不包含有效的 JSON。” 机器学习代理返回了一个要求您重试的错误代码，例如 429 或 500。不过，客户收到的却是这条短信。这是 Microsoft 的已知限制。

错误代码

AI_GENERATE_EMBEDDINGS 函数仅提供错误代码，不提供错误消息。下表列出了一些错误代码的可能原因：

错误代码 可能的原因
400 Bad Request
  • 模型类型不受支持。
  • JSON 载荷格式不正确。
  • 模型类型的网址无效。
401 Unauthorized 第三方模型缺少有效的 API 密钥。
403 Forbidden
  • Cloud SQL 实例缺少访问 Vertex AI 的相应权限。
  • Cloud SQL 实例缺少访问 Secret Manager 的相应权限。
  • API 密钥未向指定的第三方模型授予权限。
  • 项目中未启用 Vertex AI。
404 Not Found
  • 指定的 secret_url 不存在。
  • 指定的 model_url 不存在。
405 Method Not Allowed 提供了 POST 以外的方法。
413 Request Body Too Large 请求大小超过 1MB 的上限。
429 Too Many Requests 模型提供方返回的资源耗尽错误。
500 Internal Server Error
  • 模型提供方返回的未指明错误。
  • 模型提供商的回答出乎意料。

后续步骤