alibabacloud-analyticdb-postgresql-ai-coaching-best-practice

ADBPG AI 教练最佳实践

使用 ADBPG Supabase（培训数据管理）+ ADBPG Vector Knowledge Base（由 RAG 驱动的智能教练）构建 RAG 驱动的教练系统。

核心能力：

• Supabase 项目：基于 PostgreSQL 的平台，用于管理教练领域、学员和会话记录
• Vector Knowledge Base：经过向量优化的 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

---

预检查：必须具备 Alibaba Cloud 凭证

安全规则：

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

aliyun configure list

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

---

场景说明

场景	用例	目标用户
工作流教练	引导专业人士完成结构化业务流程（销售周期、项目管理）	销售团队、项目经理
决策支持	帮助工程师评估权衡并做出明智的技术决策	工程师、架构师
技能培养	通过引导式练习培养沟通、谈判或技术技能	专业人士、新员工
入职培训	系统地引导新团队成员完成技术和流程入职培训	新员工、导师

架构

User (Web / Terminal / Agent)
           │
    ┌──────┴──────┐
    v             v
┌─────────────┐  ┌────────────────────────┐
│  Supabase   │  │  Agent Mode            │
│  (spb-xxx)  │  │  ChatWithKnowledgeBase │
│  - Domains  │  └───────────┬────────────┘
│  - Sessions │              │
└──────┬──────┘              │
       v                     v
┌────────────────────────────────────────┐
│  ADBPG Instance (gp-xxx) + KB          │
│  Domain Knowledge + RAG + LLM          │
└────────────────────────────────────────┘

---

RAM 策略

所需权限

操作	RAM 权限
Supabase 项目管理	gpdb:CreateSupabaseProject、gpdb:GetSupabaseProject、gpdb:ModifySupabaseProjectSecurityIps
ADBPG 实例管理	gpdb:CreateDBInstance、gpdb:DescribeDBInstances、gpdb:ModifySecurityIps
账号管理	gpdb:DescribeAccounts、gpdb:CreateAccount
知识库操作	gpdb:InitVectorDatabase、gpdb:CreateNamespace、gpdb:CreateDocumentCollection、gpdb:UploadDocumentAsync、gpdb:ChatWithKnowledgeBase
VPC 网络	vpc:DescribeVpcs、vpc:DescribeVSwitches、vpc:DescribeVSwitchAttributes
NAT 网关和 EIP	vpc:DescribeNatGateways、vpc:CreateNatGateway、vpc:DescribeEipAddresses、vpc:AllocateEipAddress、vpc:AssociateEipAddress、vpc:CreateSnatEntry

推荐系统策略： AliyunGPDBFullAccess、AliyunVPCFullAccess（如果 NAT 已存在，也可使用 AliyunVPCReadOnlyAccess）

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

[MUST] 权限失败处理： 当任何命令因权限错误而失败时：

1. 阅读 references/ram-policies.md，了解所需权限
2. 使用 ram-permission-diagnose 技能指导用户
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 网关。

# Check existing NAT Gateways in VPC
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: Get 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
# Record: CidrBlock

# 1.1b: Create Enhanced NAT Gateway (requires user confirmation)
# 💰 Cost note: NAT Gateway incurs hourly charges
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
# Record: NatGatewayId and SnatTableIds.SnatTableId[0]
# Poll until Status=Available

# 1.1c: Find or allocate EIP (requires user confirmation)
# 💰 Cost note: EIP incurs charges; release via VPC console when no longer needed
aliyun vpc describe-eip-addresses --profile adbpg \
  --biz-region-id <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
# If no available EIP:
aliyun vpc allocate-eip-address --profile adbpg \
  --biz-region-id <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-ai-coaching-best-practice
# Record: AllocationId and EipAddress

# 1.1d: Bindind EIP to NAT Gateway (requires user confirmation)
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: Create SNAT entry (requires user confirmation)
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：

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 中的架构定义。

# Ask user for whitelist IP (do NOT use curl to external services)
# Example: "Please provide the IP address to add to the whitelist"

# Set whitelist
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 中的 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 用户选择实例

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

可用实例（运行中 + 已启用向量功能）：

#	实例 ID	规格	地域	状态	描述
1	gp-xxxxx	4C32G	cn-hangzhou	Running	生产环境
2	gp-yyyyy	8C64G	cn-hangzhou	Running	测试环境

选择一个实例，或输入 "Create New"。

• 用户选择现有实例 → 转到步骤 4.3
• 用户选择 "Create New" → 转到步骤 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 控制台释放或暂停实例。

配置	默认值	备注
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 秒轮询一次：

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，在用户确认上述参数后，执行：

# Initialize vector database
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

# Create namespace
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

# Create document collection
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	大模型；日常练习可使用 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

---

场景速查

场景	流程
工作流辅导	查询 sales_workflow_coach → 注入辅导角色设定和流程知识库 → 引导学习者完成销售各阶段 → 记录会话
决策支持	查询 architecture_advisor → 注入辅导角色设定和技术知识库 → 引导权衡分析 → 记录决策
技能培养	查询 communication_coach → 注入辅导角色设定和最佳实践知识库 → 练习场景 → 提供反馈
入职引导	查询 onboarding_mentor → 注入辅导角色设定和技术文档知识库 → 渐进式学习 → 验证理解情况

---

成功验证

详细验证步骤请参阅 references/verification-method.md。

快速验证：

1. Supabase 项目已创建且状态为 Running
2. ADBPG 实例的 VectorConfigurationStatus=enabled
3. 数据库表已创建（coaching_domains、coaching_personas、learners、coaching_sessions）
4. 可以查询预设的辅导领域
5. ChatWithKnowledgeBase 返回有意义的辅导回复

---

最佳实践

1. Supabase 用于数据，知识库用于 AI — 会话记录通过 Supabase 存储，辅导对话通过 RAG 处理
2. 辅导角色设定是关键 — system_prompt 的质量决定辅导效果
3. 始终存储会话记录 — 写入每一轮辅导内容，以便复盘和改进
4. 所有操作均使用 --profile adbpg — 统一凭证管理
5. 使用命名空间隔离团队 — 不同团队使用不同的 Namespace
6. TopK 建议设为 5 — 减少令牌消耗
7. 日常练习使用 qwen-turbo（成本较低），评估使用 qwen-max（质量较高）
8. 写入操作应保持幂等 — 创建任何资源（CreateSupabaseProject、CreateDBInstance、CreateAccount、CreateNamespace 等）之前，始终先查询（Describe/List），检查资源是否已存在。仅在资源不存在时创建。这可以避免重试时创建重复资源

---

参考资料

文档	描述
references/cli-installation-guide.md	Aliyun CLI 安装
references/related-apis.md	使用的所有 CLI 命令和 API
references/ram-policies.md	所需的 RAM 权限
references/database-schema.md	SQL 架构和预设辅导领域
references/acceptance-criteria.md	正确/错误模式
references/verification-method.md	成功验证步骤