本页面介绍了如何将 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.
-
Make sure that billing is enabled for your Google Cloud project.
- 启用必要的 Google Cloud API。
- 进入 API 和服务页面。
- 从项目列表中,选择一个项目。
- 如果 API 库未打开,请从导航菜单中选择库。
点击您要启用的 API。对于此过程,请启用 Cloud SQL Admin API 和 Vertex AI API。
- 选择每个 API 后,点击启用。
- 打开 Cloud Shell,以直接在浏览器中通过命令行访问 Google Cloud 资源。
- 如需启用所需的 API,请使用
gcloud services enable
命令:gcloud services enable sqladmin.googleapis.com \ enable aiplatform.googleapis.com
此命令会启用以下 API:
- Cloud SQL Admin API
- Vertex AI API
- 授予 Cloud SQL 服务账号访问 Vertex AI 的 Identity and Access Management (IAM) 权限。
如需为 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
参数旁边显示的值即电子邮件地址。
启用数据库与 Vertex AI 的集成
如需启用数据库与 Vertex AI 的集成,请完成以下步骤:
- 创建或更新 Cloud SQL 实例,使该实例可以与 Vertex AI 集成。
创建实例
如需创建 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如果此更新修改的值需要重启实例,系统会提示您继续进行更改或取消操作。
创建实例
使用此示例创建实例。如需查看此调用的完整参数列表,请参阅 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,以将针对实时预测和数据洞见的请求传递给 AIcloudsql.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)
将请求正文保存在名为
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)
将请求正文保存在名为
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)
将请求正文保存在名为
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)
将请求正文保存在名为
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 " }创建实例
使用此示例创建实例。如需查看此调用的完整参数列表,请参阅 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,以将针对实时预测和数据洞见的请求传递给 AIcloudsql.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)
将请求正文保存在名为
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)
将请求正文保存在名为
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)
将请求正文保存在名为
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)
将请求正文保存在名为
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
扩展程序。此数据库包含您要根据其运行预测的数据。- 按照使用 psql 客户端连接中所述,将
psql
客户端连接到主实例。 - 在
psql
命令提示符下,连接到数据库:\c
DB_NAME 将
DB_NAME
替换为您要在其中安装扩展程序的数据库的名称。 - 安装扩展程序:
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
- 按照使用 psql 客户端连接中所述,将
问题排查
本部分介绍了将 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 将 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 个请求的限制。 |