alibabacloud-analyticdb-postgresql-ai-coaching-best-practice：在 AnalyticDB for PostgreSQL（ADBPG）上实施 AI 陪练最佳实践：结合 Supabase 项目（用于训练数据管理）与具备向量优化能力的 ADBPG 实例，构建基于检索增强生成（RAG）的陪练系统。

ADBPG AI 陪练最佳实践

使用 ADBPG Supabase（训练数据管理） + ADBPG 向量知识库（RAG 驱动智能陪练）构建 RAG 驱动的陪练系统。

核心能力：

• Supabase 项目：基于 PostgreSQL 的平台，用于管理陪练领域、学员和会话记录
• 向量知识库：具备向量优化能力的 ADBPG 实例，用于 RAG 驱动陪练
• 无缝集成：Supabase 存储结构化数据，ADBPG 驱动智能 AI 陪练对话

预检查：需要 Aliyun CLI >= 3.3.3

重要：运行 aliyun version 验证 >= 3.3.3。如果未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 更新，
或参阅 references/cli-installation-guide.md 获取安装说明。
然后 [必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
[必须] 运行 aliyun plugin update 确保本地现有插件始终为最新版本。

[必须] CLI User-Agent

每次调用 aliyun CLI 命令都必须包含：
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

[必须] CLI AI-Mode 配置

在核心工作流开始时（任何 CLI 调用之前）：

[必须] 启用 AI-Mode —— Agent Skill 执行需要 AI-mode。

在任何 CLI 调用之前运行以下命令：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice"

[必须] 在每一个退出点禁用 AI-Mode —— 在交付最终响应之前（无论何种原因），必须先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不再执行 CLI 命令的场景。

AI-mode 仅用于 Agent Skill 调用场景，Skill 停止运行后绝不能保持启用状态。

aliyun configure ai-mode disable

预检查：需要阿里云凭证

安全规则：
- 绝不读取、回显或打印 AK/SK 值
- 绝不要求用户直接输入 AK/SK
- 绝不在日志或 stdout 中以明文打印密码或 API Keys
- 只能使用 aliyun configure list 检查凭证状态
- 展示 API Keys 时，仅显示前 6 个字符 + *（例如 sk-abc1*）

aliyun configure list

如果不存在有效 profile，请在此停止。 通过 aliyun configure 或环境变量在本会话之外配置凭证。

场景描述

架构

用户（Web / 终端 / Agent）
           │
    ┌──────┴──────┐
    v             v
┌─────────────┐  ┌────────────────────────┐
│  Supabase   │  │  Agent 模式            │
│  (spb-xxx)  │  │  ChatWithKnowledgeBase │
│  - Domains  │  └───────────┬────────────┘
│  - Sessions │              │
└──────┬──────┘              │
       v                     v
┌────────────────────────────────────────┐
│  ADBPG 实例 (gp-xxx) + KB              │
│  领域知识 + RAG + LLM                  │
└────────────────────────────────────────┘

RAM 策略

所需权限

推荐系统策略： AliyunGPDBFullAccess、AliyunVPCFullAccess（或 NAT 已存在时用 AliyunVPCReadOnlyAccess）

完整列表见 references/ram-policies.md。

[必须] 权限失败处理： 当任何命令因权限错误失败时：
1. 阅读 references/ram-policies.md 获取所需权限
2. 使用 ram-permission-diagnose skill 引导用户
3. 暂停并等待用户确认权限已授予

核心工作流

当用户说“帮我搭建 AI 陪练系统”或类似内容时，执行以下步骤：

智能默认模式：用户只需最少输入（例如“北京i”）。Agent 自动解析地域、发现 VPC/VSwitch、生成密码，并呈现所有参数供一键确认。

步骤 1：创建 Supabase 项目

本步骤需确认的参数：
| 参数 | 默认 | 说明 |
|-----------|---------|-------|
| RegionId | 自动解析 | “北京i” → cn-beijing，“上海b” → cn-shanghai，“杭州” → cn-hangzhou，“深圳” → cn-shenzhen |
| ZoneId | 自动解析 | “北京i” → cn-beijing-i；仅提供城市时查询可用区 |
| VpcId | 自动发现 | 查询可用 VPC，选择可用 IP 最多的 |
| VSwitchId | 自动发现 | 查询目标可用区中的 VSwitch，选择可用 IP 最多的 |
| ProjectName | ai_coaching | Supabase 项目名称 |
| AccountPassword | 自动生成 | 密码规则： 8-32 字符，大写/小写/数字/特殊字符（@#$%^&*）至少 3 类，避免 ! |

#### 1.1 检查/创建 NAT 网关

重要： Supabase 公网连接需要 VPC 中带 SNAT 规则的 NAT 网关。

检查 VPC 中现有 NAT 网关

aliyun vpc describe-nat-gateways --profile adbpg \

--biz-region-id <RegionId> --vpc-id <VpcId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

- **如果 `TotalCount > 0`** 且 SNAT 条目覆盖 VSwitch CIDR → **跳到步骤 1.2**
- **如果无 NAT 网关** → 获得用户确认，然后：

1.1a：获取 VSwitch CIDR

aliyun vpc describe-vswitch-attributes --profile adbpg \

--biz-region-id <RegionId> --vswitch-id <VSwitchId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

记录：CidrBlock

1.1b：创建增强型 NAT 网关（需要用户确认）

💰 费用提示：NAT 网关按时计费

aliyun vpc create-nat-gateway --profile adbpg \

--biz-region-id <RegionId> --vpc-id <VpcId> --vswitch-id <VSwitchId> \

--nat-type Enhanced \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

记录：NatGatewayId 和 SnatTableIds.SnatTableId[0]

轮询直到 Status=Available

1.1c：查找或分配 EIP（需要用户确认）

💰 费用提示：EIP 产生费用；不再需要时通过 VPC 控制台释放

aliyun vpc describe-eip-addresses --profile adbpg \

--biz-region-id <RegionId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

如果没有可用 EIP：

aliyun vpc allocate-eip-address --profile adbpg \

--biz-region-id <RegionId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

记录：AllocationId 和 EipAddress

1.1d：绑定 EIP 到 NAT 网关（需要用户确认）

aliyun vpc associate-eip-address --profile adbpg \

--biz-region-id <RegionId> \

--allocation-id <EIP-AllocationId> --instance-id <NatGatewayId> \

--instance-type Nat \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

1.1e：创建 SNAT 条目（需要用户确认）

aliyun vpc create-snat-entry --profile adbpg \

--biz-region-id <RegionId> \

--snat-table-id <SnatTableId> \

--source-cidr "<VSwitch-CidrBlock>" --snat-ip "<EipAddress>" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

#### 1.2 创建 Supabase 项目

aliyun gpdb create-supabase-project --profile adbpg \

--biz-region-id <RegionId> --zone-id <ZoneId> \

--project-name <ProjectName> --account-password '<AccountPassword>' \

--security-ip-list "127.0.0.1" --vpc-id <VpcId> --vswitch-id <VSwitchId> \

--project-spec 2C4G --storage-size 20 --pay-type Postpaid \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

**记录：** `ProjectId`（sbp-xxx）、`PublicConnectUrl`、API Keys（安全存储；**不要**在日志中打印完整 API Keys）

> **超时：** Supabase 项目创建需要 **5-10 分钟**。轮询状态直到 `running`：
> ```bash
> aliyun gpdb get-supabase-project --profile adbpg \
>   --biz-region-id <RegionId> --project-id <ProjectId> \
>   --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
> ```
> 检查 `Status` 字段。每 30 秒重试直到 `Status=running`。

### 步骤 2：初始化陪练平台数据库

> **注意：** 步骤 2-3 在 **Supabase 项目**上执行，步骤 4-8 在 **ADBPG 实例**上执行。它们相互独立。

修改白名单，然后通过 psql 连接并执行 [references/database-schema.md](references/database-schema.md) 中的 schema。

向用户询问白名单 IP（不要用 curl 访问外部服务）

示例：“请提供要加入白名单的 IP 地址”

设置白名单

aliyun gpdb modify-supabase-project-security-ips --profile adbpg \

--biz-region-id <RegionId> --project-id <ProjectId> \

--security-ip-list "<WhitelistIP>" \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

### 步骤 3：插入预设陪练领域

通过 psql 执行 [references/database-schema.md](references/database-schema.md) 中的 SQL 以插入陪练领域和陪练人设。

### 步骤 4：发现 / 选择 / 创建 ADBPG 实例

#### 4.1 发现现有实例

aliyun gpdb describe-db-instances --profile adbpg \

--biz-region-id <RegionId> --page-size 100 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

筛选结果：`DBInstanceStatus=Running` 且 `VectorConfigurationStatus=enabled`。

#### 4.2 用户选择实例

向用户展示符合条件的实例：

> **可用实例（Running + 向量已启用）：**
> | # | 实例 ID | 规格 | 地域 | 状态 | 说明 |
> |---|-------------|------|--------|--------|-------------|
> | 1 | `gp-xxxxx` | 4C32G | cn-hangzhou | Running | 生产 |
> | 2 | `gp-yyyyy` | 8C64G | cn-hangzhou | Running | 测试 |
>
> 选择一个实例，或输入“创建新实例”。

- **用户选择现有** → 进入步骤 4.3
- **用户选择“创建新实例”** → 进入步骤 4.4
- **无符合条件的实例** → 告知用户，进入步骤 4.4

#### 4.3 验证所选实例（使用现有实例时）

aliyun gpdb describe-db-instance-attribute --profile adbpg \

--db-instance-id <DBInstanceId> --region <RegionId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

确认：`DBInstanceStatus=Running` + `VectorConfigurationStatus=enabled`。然后进入步骤 5。

#### 4.4 创建新实例（无现有实例或用户选择新建时）

> **执行前必须展示配置并获得用户确认：**
>
> 💰 **费用提示：** 创建实例会产生费用。不使用时通过 [ADBPG 控制台](https://gpdbnext.console.aliyun.com/) 释放或暂停。

| 配置 | 默认 | 说明 |
|--------|---------|-------|
| RegionId | `cn-hangzhou` | 用户指定 |
| ZoneId | `cn-hangzhou-j` | 选择后自动查询 VPC/VSwitch |
| EngineVersion | `7.0` | |
| DBInstanceMode | `StorageElastic` | 存储弹性模式 |
| DBInstanceCategory | `Basic` | 默认 Basic；可选 HighAvailability |
| InstanceSpec | `4C16G` | Basic：4C16G/8C32G/16C64G；HA：4C32G/8C64G/16C128G |
| SegNodeNum | `2` | Basic 默认 2（2 的倍数）；HA 默认 4（4 的倍数） |
| StorageSize | `50` GB | 范围：50-8000 GB |
| SegStorageType | `cloud_essd` | ESSD 云盘 |
| VPC/VSwitch | 自动发现 | 选择可用 IP 最多的 VSwitch |
| VectorConfigurationStatus | `enabled` | AI 陪练必须启用 |
| PayType | `Postpaid` | 按量付费；可选 Prepaid |

**查询该可用区的 VSwitch 列表：**

aliyun vpc describe-vswitches --profile adbpg \

--biz-region-id <RegionId> --zone-id <ZoneId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

向用户展示 VSwitch 选项，推荐可用 IP 最多的。

用户确认后：

aliyun gpdb create-db-instance --profile adbpg \

--biz-region-id <RegionId> --zone-id <ZoneId> \

--engine gpdb --engine-version "7.0" \

--db-instance-mode StorageElastic --db-instance-category Basic \

--instance-spec 4C16G --seg-node-num 2 \

--storage-size 50 --seg-storage-type cloud_essd \

--vpc-id <VpcId> --vswitch-id <VSwitchId> \

--vector-configuration-status enabled --pay-type Postpaid \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

> **超时：** 实例创建需要 **10-15 分钟**（最长 30 分钟）。每 30-60 秒轮询：
> ```bash
> aliyun gpdb describe-db-instance-attribute --profile adbpg \
>   --db-instance-id <DBInstanceId> --region <RegionId> \
>   --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
> ```
> 等待直到 `DBInstanceStatus=Running`。

### 步骤 5：配置数据库账号

检查 ADBPG 实例是否已有数据库账号：

aliyun gpdb describe-accounts --profile adbpg \

--db-instance-id <DBInstanceId> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

**情况 A：无现有账号** → 创建新账号：

> **建议创建账号，执行前与用户确认：**
> - 账号名：自动生成 `ai_coaching_XX`（XX = 随机 2 位数字），或用户指定
> - 密码：自动生成合规密码（8-32 字符，至少 3 种字符类型，避免 `!`），或用户指定
> - 示例：`Account: ai_coaching_01, Password: Coach3Acc#2x9K` —— 请确认或提供您自己的。
>
> ⚠️ **重要：**
> - **账号名创建后无法更改** —— 请仔细确认！
> - 密码可通过控制台重置，但现在请安全保存。
> - 此账号将作为步骤 6 中的 `ManagerAccount`。

aliyun gpdb create-account --profile adbpg \

--db-instance-id <DBInstanceId> --region <RegionId> \

--account-name <ManagerAccount> --account-password '<ManagerAccountPassword>' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

**情况 B：账号已存在** → 告知用户。如果账号不是 Agent 创建的，在进入步骤 6 之前**向用户询问现有账号密码**。

> **记录：** `ManagerAccount` 和 `ManagerAccountPassword` —— 步骤 6 知识库初始化时会用到。

### 步骤 6：创建知识库

> **本步骤需确认的参数：** 自动生成以下内容，呈现给用户确认（用户可修改），然后执行。
>
> | 参数 | 默认 | 说明 |
> |-----------|---------|-------|
> | `Namespace` | `ns_coaching` | 命名空间名称，创建后无法更改 |
> | `NamespacePassword` | 自动生成 | 命名空间密码（相同密码规则）；上传和陪练会话需要 |
> | `Collection` | `coaching_knowledge` | 知识库名称 |
> | `EmbeddingModel` | `text-embedding-v4` | 嵌入模型 |

使用步骤 5 的 `ManagerAccount` 和 `ManagerAccountPassword`，用户确认上述参数后执行：

初始化向量数据库

aliyun gpdb init-vector-database --profile adbpg \

--biz-region-id <RegionId> --db-instance-id <DBInstanceId> \

--manager-account <ManagerAccount> --manager-account-password '<ManagerAccountPassword>' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

创建命名空间

aliyun gpdb create-namespace --profile adbpg \

--biz-region-id <RegionId> --db-instance-id <DBInstanceId> \

--manager-account <ManagerAccount> --manager-account-password '<ManagerAccountPassword>' \

--namespace <Namespace> --namespace-password '<NamespacePassword>' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

创建文档集合

aliyun gpdb create-document-collection --profile adbpg \

--biz-region-id <RegionId> --db-instance-id <DBInstanceId> \

--manager-account <ManagerAccount> --manager-account-password '<ManagerAccountPassword>' \

--namespace <Namespace> --collection <Collection> \

--embedding-model <EmbeddingModel> --dimension 1024 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

### 步骤 7（可选）：上传领域知识文档

> 如果用户有领域知识文档（PDF/TXT/Markdown 等），上传到知识库以增强陪练质量。此步骤可跳过——直接进入步骤 8 开始陪练。

aliyun gpdb upload-document-async --profile adbpg \

--biz-region-id <RegionId> --db-instance-id <DBInstanceId> \

--namespace <Namespace> --namespace-password '<NamespacePassword>' \

--collection <Collection> --file-name "domain_knowledge.pdf" \

--file-url "https://example.com/knowledge.pdf" \

--document-loader-name ADBPGLoader --chunk-size 500 --chunk-overlap 50 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

**按场景推荐的文档：** 销售方法论、流程指南（工作流陪练）；架构模式、设计文档（决策支持）；沟通框架、最佳实践（技能发展）；技术栈文档、入职指南（入职）。

### 步骤 8：开始陪练会话

> **本步骤可选参数：**
>
> | 参数 | 默认 | 说明 |
> |-----------|---------|-------|
> | `Model` | `qwen-max` | LLM 模型；日常练习用 `qwen-turbo`（成本更低） |
> | `TopK` | `5` | RAG 检索数量 |

> **注意：** `SourceCollection` 元素**必须包含 `Namespace` 字段**。

aliyun gpdb chat-with-knowledge-base --profile adbpg \

--biz-region-id <RegionId> --db-instance-id <DBInstanceId> \

--model-params '{"Model": "<Model>", "Messages": [

{"Role": "system", "Content": "<system_prompt from coaching_personas>"},

{"Role": "user", "Content": "<learner message>"}

]}' \

--knowledge-params '{"SourceCollection": [{

"Collection": "<Collection>", "Namespace": "<Namespace>",

"NamespacePassword": "<NamespacePassword>", "QueryParams": {"TopK": <TopK>}

}]}' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

---

场景速查

成功验证

详细验证步骤见 references/verification-method.md。

快速验证：

1. Supabase 项目存在且为 Running
2. ADBPG 实例 VectorConfigurationStatus=enabled
3. 数据库表存在（coaching_domains、coaching_personas、learners、coaching_sessions）
4. 预设陪练领域可查询
5. ChatWithKnowledgeBase 返回有意义的陪练响应

最佳实践

1. Supabase 管数据，KB 管 AI —— 会话记录通过 Supabase，陪练对话通过 RAG
2. 陪练人设是关键 —— system_prompt 的质量决定陪练效果
3. 始终存储会话记录 —— 每轮陪练都写入，便于复盘和改进
4. 所有操作使用 --profile adbpg —— 一致的凭证管理
5. 命名空间隔离团队 —— 不同团队使用不同 Namespace
6. TopK 推荐：5 —— 减少 token 消耗
7. 日常练习：qwen-turbo（低成本），评估：qwen-max（高质量）
8. 幂等写操作 —— 任何资源创建前（CreateSupabaseProject、CreateDBInstance、CreateAccount、CreateNamespace 等），始终先查询（Describe/List）检查资源是否已存在。仅在资源不存在时创建。这防止重试时产生重复资源

参考

文档 5 / 6：alibabacloud-dsc-audit