alibabacloud-analyticdb-postgresql-knowledgebase-ops：云原生数据仓库 AnalyticDB PostgreSQL 版知识库管理。

ADBPG 知识库管理

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

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

架构：ADBPG 实例 + 命名空间 + DocumentCollection + 向量索引 + LLM 服务

核心概念

• 知识库：文档的容器，自动管理向量索引（对应 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 —— AI-mode 是 Agent Skill 执行所必需的。
在任何 CLI 调用之前运行以下命令：
```bash
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 停止运行后不得保持启用。
```bash
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 确保本地已有插件始终为最新版本。

前置检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印凭证材料（包括基于环境的密钥）
- 绝不要求用户在对话或命令行中直接粘贴长期密钥
- 绝不使用字面凭证值运行 aliyun configure set
- 只使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否有有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，就此停止。
1. 从阿里云控制台获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 待 aliyun configure list 显示有效 profile 后再返回并重试

验证 CLI 凭证

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

脚本依赖（Python）

scripts/upload_document_local.py 使用阿里云 Python SDK。在 requirements.txt 中声明依赖。运行脚本前安装：

pip install -r requirements.txt

需要 Python 3.7+（与阿里云 Python SDK 相同的基线）。

RAM 权限

[必须] RAM 权限预检： 执行操作前，验证当前用户具有所需权限。
使用 ram-permission-diagnose skill 检查权限，然后与 references/ram-policies.md 对比。
如果任何权限缺失，中止并提示用户。

参数确认

重要：参数确认 —— 执行任何命令或 API 调用前，
所有用户可自定义的参数（例如 RegionId、实例名、CIDR 块、
密码、域名、资源规格等）都必须与用户确认。
未经用户明确批准，不要假设或使用默认值。

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

交互指引、智能默认值和最佳实践见 references/interaction-guidelines.md。

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

超时配置

超时规则： 所有操作必须在合理时间限制内完成。
- 标准操作：≤10 秒（创建 / 列出 / 查询）
- 上传文档异步：无超时限制（异步作业，每 5-10 秒轮询）

CLI 超时设置：

给所有命令加 --ConnectTimeout 和 --ReadTimeout

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 相同的来源）。不要在 skill 代码中解析凭证文件或传原始密钥。在 `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。当插件未全局列出时，下方示例省略它。

1. 初始化向量数据库

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. 创建命名空间（命名规则：ns_{collection}，禁止 public）

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

> **重要**：CreateNamespace 必须在 CreateDocumentCollection 之前执行

**创建知识库**：

3. 创建知识库（在之前创建的命名空间中）

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 粘贴到 skill 中；只使用打包脚本（默认凭证链、`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](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 "如何配置数据库参数？" \

--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":"用户问题"}]}' \

--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

---

参考链接