将 Cloud SQL 与 Vertex AI 集成

MySQL | PostgreSQL | SQL Server

本页面介绍了如何将 Cloud SQL 与 Vertex AI 集成。借助此集成，您可以将托管在 Vertex AI 中的大语言模型 (LLM) 应用于 Cloud SQL for PostgreSQL 数据库版本 12 及更高版本。

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

调用预测以在事务中使用 SQL 调用模型。
生成嵌入以使嵌入模型将文本提示转换为数值向量。然后，您可以将这些向量嵌入作为输入应用于 pgvector 函数。这包括根据文本样本的相对语义距离对其进行比较和排序的方法。

因此，您可以直接在数据库中进行实时预测并获得有价值的数据洞见，从而简化工作流并增强决策制定能力。

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

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

启用必要的 Google Cloud API。
控制台
1. 进入 API 和服务页面。
2. 从项目列表中，选择一个项目。
3. 如果 API 库未打开，请从导航菜单中选择库。
4. 点击您要启用的 API。对于此过程，请启用 Cloud SQL Admin API 和 Vertex AI API。
  
  注意：如果您在查找这些 API 时需要帮助，请使用搜索字段。
5. 选择每个 API 后，点击启用。
gcloud
1. 打开 Cloud Shell，以直接在浏览器中通过命令行访问 Google Cloud 资源。
2. 如需启用所需的 API，请使用 gcloud services enable 命令：
```
gcloud services enable sqladmin.googleapis.com \
enable aiplatform.googleapis.com
```
授予 Cloud SQL 服务账号访问 Vertex AI 的 Identity and Access Management (IAM) 权限。
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 INSTANCE_NAME 命令，并将 INSTANCE_NAME 替换为 Cloud SQL 实例的名称。serviceAccountEmailAddress 参数旁边显示的值即电子邮件地址。
注意：政策更改通常会在 2 分钟内生效。但是，在某些情况下，此类更改可能需要长达 7 分钟才能在整个系统中完全传播。如需了解详情，请参阅访问权限更改传播。

启用数据库与 Vertex AI 的集成

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

创建或更新 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 \
--database-flags cloudsql.enable_google_ml_integration=on
```
进行以下替换：
- INSTANCE_NAME：实例的名称
- DATABASE_VERSION：实例的数据库版本（例如 POSTGRES_13）
- MACHINE_TYPE：实例的机器类型
- REGION_NAME：实例的区域名称
注意：如需详细了解这些参数，请参阅创建实例。

更新实例

如需更新实例，请使用 gcloud sql instances patch 命令。
```
gcloud sql instances patch INSTANCE_NAME \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on
```
如果此更新修改的值需要重启实例，系统会提示您继续进行更改或取消操作。

注意：如需详细了解如何更新实例，请参阅修改实例。
REST v1

创建实例

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

在使用任何请求数据之前，请先进行以下替换：
- PROJECT_ID：包含实例的 Google Cloud 项目的 ID 或项目编号
- INSTANCE_NAME：实例的名称
- REGION_NAME：实例的区域名称
- DATABASE_VERSION：数据库版本的枚举字符串（例如：POSTGRES_13）
- PASSWORD：root 用户的密码
- MACHINE_TYPE：机器（层级）类型的枚举字符串，例如：db-custom-[CPUS]-[MEMORY_MBS]
- EDITION_TYPE：您的 Cloud SQL 版本
注意：如需详细了解这些参数，请参阅创建实例。

您还必须在请求中添加 enableGoogleMlIntegration 对象。根据需要设置以下参数：
- enableGoogleMlIntegration：当此参数设置为 true 时，Cloud SQL 实例可以连接到 Vertex AI，以将针对实时预测和数据洞见的请求传递给 AI
- cloudsql.enable_google_ml_integration：当此参数设置为 on 时，Cloud SQL 可以与 Vertex 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"
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on" | "off"
      }
  }
}
```
如需发送您的请求，请展开以下选项之一：
curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances"
PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | Select-Object -Expand Content
您应该收到类似以下内容的 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,
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on"
      }
   }
}
```
如需发送您的请求，请展开以下选项之一：
curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"
PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content
您应该收到类似以下内容的 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：数据库版本的枚举字符串（例如：POSTGRES_13）
- PASSWORD：root 用户的密码
- MACHINE_TYPE：机器（层级）类型的枚举字符串，例如：db-custom-[CPUS]-[MEMORY_MBS]
- EDITION_TYPE：您的 Cloud SQL 版本
注意：如需详细了解这些参数，请参阅创建实例。

您还必须在请求中添加 enableGoogleMlIntegration 对象。根据需要设置以下参数：
- enableGoogleMlIntegration：当此参数设置为 true 时，Cloud SQL 实例可以连接到 Vertex AI，以将针对实时预测和数据洞见的请求传递给 AI
- cloudsql.enable_google_ml_integration：当此参数设置为 on 时，Cloud SQL 可以与 Vertex 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"
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on" | "off"
      }
  }
}
```
如需发送您的请求，请展开以下选项之一：
curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances"
PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances" | Select-Object -Expand Content
您应该收到类似以下内容的 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,
    "databaseFlags":
      {
        "name": "cloudsql.enable_google_ml_integration",
        "value": "on"
      }
   }
}
```
如需发送您的请求，请展开以下选项之一：
curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"
PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://sqladmin.googleapis.com/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content
您应该收到类似以下内容的 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"
}
```
注意：如需详细了解如何更新实例，请参阅修改实例。
在 Cloud SQL 主实例的数据库中安装 google_ml_integration 扩展程序。此数据库包含您要根据其运行预测的数据。
注意：即使您打算在已连接到主实例的读取副本时运行预测，仍必须连接到主实例。
1. 按照使用 psql 客户端连接中所述，将 psql 客户端连接到主实例。
2. 在 psql 命令提示符下，连接到数据库：
```
\c DB_NAME
```
  将 DB_NAME 替换为您要在其中安装扩展程序的数据库的名称。
3. 安装扩展程序：
```
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
```

问题排查

本部分介绍了将 Cloud SQL 与 Vertex AI 集成相关的问题以及问题排查步骤。

问题	问题排查
错误消息：`Google ML integration API is supported only on Postgres version 12 or above.`	如需在 Cloud SQL 中启用 Vertex AI 集成，您必须拥有 Cloud SQL for PostgreSQL 数据库版本 12 或更高版本。如需将数据库升级到此版本，请参阅就地升级数据库主要版本。
错误消息：`Google ML Integration API is not supported on shared core instance. Please upsize your machine type.`	如果您为实例的机器类型选择了共享核心，则无法在 Cloud SQL 中启用 Vertex AI 集成。将机器类型升级到专用核心。如需了解详情，请参阅机器类型。
错误消息：`Google ML Integration is unsupported for this maintenance version. Please follow https://cloud.google.com/sql/docs/postgres/self-service-maintenance to update the maintenance version of the instance.`	如需在 Cloud SQL 中启用 Vertex AI 集成，实例的维护版本必须为 `R20240130` 或更高版本。如需将实例升级到此版本，请参阅自助维护。
错误消息：`Cannot invoke ml_predict_row if 'cloudsql.enable_google_ml_integration' is off.`	`cloudsql.enable_google_ml_integration` 数据库标志已关闭。Cloud SQL 无法与 Vertex AI 集成。如需启用此标志，请使用 `gcloud sql instances patch` 命令： `gcloud sql instances patch INSTANCE_NAME --database-flags cloudsql.enable_google_ml_integration=on` 将 `INSTANCE_NAME` 替换为 Cloud SQL 主实例的名称。
错误消息：`Failed to connect to remote host: Connection refused.`	Cloud SQL 与 Vertex AI 之间的集成未启用。如需启用此集成，请使用 `gcloud sql instances patch` 命令： `gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration` 将 `INSTANCE_NAME` 替换为 Cloud SQL 主实例的名称。
错误消息：`Vertex AI API has not been used in project PROJECT_ID before or it is disabled. Enable it by visiting /apis/api/aiplatform.googleapis.com/overview?project=PROJECT_ID then retry.`	未启用 Vertex AI API。如需详细了解如何启用此 API，请参阅启用数据库与 Vertex AI 的集成。
错误消息：`Permission 'aiplatform.endpoints.predict' denied on resource.`	系统未向 Cloud SQL 实例所在项目的 Cloud SQL 服务账号添加 Vertex AI 权限。如需详细了解如何向该服务账号添加这些权限，请参阅启用数据库与 Vertex AI 的集成。
错误消息：Publisher Model `projects/PROJECT_ID/locations/REGION_NAME/publishers/google/models/MODEL_NAME` not found.	Vertex AI 中不存在机器学习模型或 LLM。
错误消息：`Resource exhausted: grpc: received message larger than max.`	Cloud SQL 传递给 Vertex AI 的请求大小超过 gRPC 限制（每个请求 4 MB）。
错误消息：`Cloud SQL attempts to send a request to Vertex AI. However, the instance is in the %s region, but the Vertex AI endpoint is in the %s region. Make sure the instance and endpoint are in the same region.`	Cloud SQL 尝试向 Vertex AI 发送请求。但是，实例位于一个区域，而 Vertex AI 端点位于其他区域。如需解决此问题，实例和端点必须位于同一区域。
错误消息：`The Vertex AI endpoint isn't formatted properly.`	Vertex AI 端点的格式不正确。如需了解详情，请参阅使用专用端点进行在线预测。
错误消息：`Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model with base model: textembedding-gecko.`	Cloud SQL 传递给 Vertex AI 的请求数超过了每个项目每个模型每个区域每分钟 1,500 个请求的限制。

将 Cloud SQL 与 Vertex AI 集成

准备工作

控制台

gcloud

gcloud

启用数据库与 Vertex AI 的集成

gcloud

创建实例

更新实例

REST v1

创建实例

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

更新实例

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

REST v1beta4

创建实例

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

更新实例

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

问题排查

后续步骤