alibabacloud-analyticdb-postgresql-knowledgebase-ops

ADBPG 知识库管理

分三步构建企业知识库：创建知识库 → 上传文档 → 搜索与问答

系统会自动处理文档解析、分块、向量化和索引构建。用户只需专注于业务逻辑。

架构：ADBPG Instance + Namespace + DocumentCollection + Vector Index + LLM Service

核心概念

• 知识库：文档的容器，自动管理向量索引（对应 API 中的 DocumentCollection）
• 文档：上传到知识库的文件，支持 PDF/Word/Markdown/HTML/JSON/CSV/图片等。
• 问答：基于知识库和大模型的智能对话

---

环境配置

[必须] CLI User-Agent — 每次调用 aliyun CLI 命令时都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

[必须] 启用 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-knowledgebase-ops"

[必须] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在提供最终响应之前，务必先禁用 AI-mode。这适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何其他不再执行 CLI 命令的情况。 AI-mode 仅用于调用 Agent Skill 的场景，Skill 停止运行后必须禁用。

aliyun configure ai-mode disable

预检查：需要 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，确保本地已有的插件始终保持最新。

预检查：需要 Alibaba Cloud 凭证

安全规则：

• 绝不读取、回显或打印凭证信息（包括基于环境变量的密钥）
• 绝不要求用户直接在对话或命令行中粘贴长期有效的密钥
• 绝不使用 aliyun configure set 和明文凭证值
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效配置文件，请在此处停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在本次会话之外配置凭证（通过终端中的 aliyun configure 命令或 Shell 配置文件中的环境变量）
3. 返回并在 aliyun configure list 显示有效配置文件后重新运行

验证 CLI 凭证

aliyun gpdb describe-regions --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

脚本依赖项（Python）

scripts/upload_document_local.py 使用 Alibaba Cloud Python SDK。请在 requirements.txt 中声明依赖项。运行脚本前请先安装：

pip install -r requirements.txt

需要 Python 3.7+（与 Alibaba Cloud SDK for Python 的最低版本要求相同）。

---

RAM 权限

**[必须] RAM 权限预检查：**执行操作前，确认当前用户拥有所需权限。 使用 ram-permission-diagnose skill 检查权限，然后与 references/ram-policies.md 进行核对。 如果缺少任何权限，请中止操作并提示用户。

---

参数确认

IMPORTANT：参数确认 — 在执行任何命令或 API 调用之前， 必须与用户确认所有可由用户自定义的参数（例如 RegionId、实例名称、CIDR 网段、 密码、域名、资源规格等）。不得在未获得用户明确批准的情况下擅自假设或使用默认值。

参数	必填/可选	描述	默认值
biz-region-id	必填	地域 ID	cn-hangzhou
db-instance-id	必填	实例 ID（格式：gp-xxxxx）	-
manager-account	必填	管理员账号名称	-
manager-account-password	必填	管理员账号密码	-
namespace	可选	命名空间名称	public
namespace-password	必填	命名空间密码	-
collection	必填	知识库名称	-
embedding-model	可选	嵌入模型	text-embedding-v4
dimension	可选	向量维度	1024

Note：如果知识库是在自定义命名空间中创建的，后续所有操作都必须指定相同的命名空间参数。

有关交互指南、智能默认值和最佳实践，请参阅 references/interaction-guidelines.md。

文档占位符： CLI 示例使用 <manager-account-password> 和 <namespace-password> 等字符串。请将其替换为用户提供的实际值；切勿在文档、工单或聊天中提交或记录真实密码。

---

超时配置

超时规则： 所有操作都必须在合理的时间限制内完成。

• 标准操作：≤10 秒（创建/列出/查询）
• 异步上传文档：无超时限制（异步任务，每隔 5-10 秒轮询一次）

CLI 超时设置：

# Add --ConnectTimeout and --ReadTimeout to all commands
aliyun gpdb create-document-collection \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --manager-account admin_user \
  --manager-account-password '<manager-account-password>' \
  --namespace ns_my_knowledge_base \
  --collection my_knowledge_base \
  --embedding-model text-embedding-v4 \
  --dimension 1024 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops \
  --ConnectTimeout 10 \
  --ReadTimeout 10

Python SDK（默认凭证链 + 超时 + User-Agent）：

不带参数使用 CredentialClient()，让 SDK 通过默认凭证链解析凭证（与 CLI 使用相同的来源）。技能代码中不要解析凭证文件或传递原始密钥。在 Config 中设置 user_agent 和 HTTP 超时（毫秒）。

from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_gpdb20160503.client import Client
from alibabacloud_tea_openapi.models import Config

client = Client(Config(
    credential=CredentialClient(),
    region_id='cn-hangzhou',
    endpoint='gpdb.aliyuncs.com',
    connect_timeout=10000,
    read_timeout=10000,
    user_agent='AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops',
))

---

核心工作流

1. 知识库管理

创建知识库

前置检查（按顺序执行；不得静默处理幂等性）：

• 名称重复： 如果资源已存在时再次执行创建步骤，API 会返回明确错误（例如冲突/已存在）。不要创建重复资源；只有在响应明确表明资源已存在时，才将“已存在”类错误视为“此步骤已完成”，然后继续工作流。
• 重试 / ClientToken： 对于网络级重试（例如超时），如果 API 或 aliyun gpdb 为该子命令提供了 ClientToken，则应使用它——请检查 aliyun gpdb <subcommand> --help。如果插件未全局列出 ClientToken，以下示例将省略它。

# 1. Initialize vector database
aliyun gpdb init-vector-database \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --manager-account admin_user \
  --manager-account-password '<manager-account-password>' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

# 2. Create namespace (naming rule: ns_{collection}, public is forbidden)
aliyun gpdb create-namespace \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --manager-account admin_user \
  --manager-account-password '<manager-account-password>' \
  --namespace ns_my_knowledge_base \
  --namespace-password '<namespace-password>' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

Important：必须先执行 CreateNamespace，再执行 CreateDocumentCollection

创建知识库：

# 3. Create knowledge base (in the previously created namespace)
aliyun gpdb create-document-collection \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --manager-account admin_user \
  --manager-account-password '<manager-account-password>' \
  --namespace ns_my_knowledge_base \
  --collection my_knowledge_base \
  --embedding-model text-embedding-v4 \
  --dimension 1024 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

列出知识库

aliyun gpdb list-document-collections \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --namespace ns_my_knowledge_base \
  --namespace-password '<namespace-password>' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

列出命名空间

aliyun gpdb list-namespaces \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --manager-account admin_user \
  --manager-account-password '<manager-account-password>' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

---

2. 文档管理

上传文档（公开 URL）

aliyun gpdb upload-document-async \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --namespace ns_my_knowledge_base \
  --namespace-password '<namespace-password>' \
  --collection my_knowledge_base \
  --file-name "user_manual.pdf" \
  --file-url "https://example.com/user_manual.pdf" \
  --document-loader-name ADBPGLoader \
  --chunk-size 500 \
  --chunk-overlap 50 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

上传文档（本地文件 - SDK）

本地文件使用 Python SDK upload_document_async_advance。技能中不要粘贴多行 Python 代码；仅使用打包脚本（默认凭证链、user_agent、Config 超时和 RuntimeOptions 超时——请参阅 scripts/upload_document_local.py）。

python3 scripts/upload_document_local.py \
  --region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --namespace ns_my_knowledge_base \
  --namespace-password '<namespace-password>' \
  --collection my_knowledge_base \
  --file /path/to/local/file.pdf

请参阅 scripts/upload_document_local.py。

轮询上传进度

aliyun gpdb get-upload-document-job \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --namespace ns_my_knowledge_base \
  --namespace-password '<namespace-password>' \
  --collection my_knowledge_base \
  --job-id "job-xxxxx" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

列出文档

aliyun gpdb list-documents \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --namespace ns_my_knowledge_base \
  --namespace-password '<namespace-password>' \
  --collection my_knowledge_base \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

---

3. 搜索与问答

搜索知识库

aliyun gpdb query-content \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --namespace ns_my_knowledge_base \
  --namespace-password '<namespace-password>' \
  --collection my_knowledge_base \
  --content "How to configure database parameters?" \
  --topk 10 \
  --rerank-factor 5 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

知识库问答

aliyun gpdb chat-with-knowledge-base \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --model-params '{"Model":"qwen-max","Messages":[{"Role":"user","Content":"User question"}]}' \
  --knowledge-params '{"SourceCollection":[{"Collection":"my_knowledge_base","Namespace":"ns_my_knowledge_base","NamespacePassword":"<namespace-password>","QueryParams":{"TopK":10}}]}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

---

参考链接

文档	内容
references/cli-installation-guide.md	CLI 安装指南
references/ram-policies.md	RAM 权限列表
references/related-apis.md	相关 API
references/interaction-guidelines.md	交互指南与最佳实践
references/verification-method.md	验证方法
references/acceptance-criteria.md	验收标准
references/SKILL.zh-CN.md	中文版
requirements.txt	scripts/ 的 Python 依赖