返回技能市场
通用工具 安全

AnalyticDB PostgreSQL版知识库管理

@aliyun/alibabacloud-analyticdb-postgresql-knowledgebase-ops

云原生数据仓库AnalyticDB PostgreSQL版知识库管理

云Skills门户 热度 95v0.0.2

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 之前，请运行以下命令：
```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
```
预检查：阿里云 CLI 必须为 3.3.3 或更高版本
运行 aliyun version，验证版本是否为 3.3.3 或更高版本。如果尚未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装/更新，
或参阅 [references/cli-installation-guide.md](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
```
检查输出中是否有有效的凭证配置（AK、STS 或 OAuth 身份）。
如果不存在有效的凭证配置，请在此处停止。
1. 从阿里云控制台获取凭证
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](scripts/upload_document_local.py) 使用阿里云 Python SDK。请在 [requirements.txt](requirements.txt) 中声明依赖项。运行该脚本前请先安装：

pip install -r requirements.txt

要求使用 Python 3.7+（与阿里云 Python SDK 的基线版本相同）。

---

RAM 权限

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

---

参数确认

重要：参数确认——执行任何命令或调用 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 |

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

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

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

---

超时配置

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

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 相同）。不得在 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. 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
重要提示：必须先执行 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 代码粘贴到 skill 中；只能使用随此 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 "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](references/cli-installation-guide.md) | CLI 安装指南 | | [references/ram-policies.md](references/ram-policies.md) | RAM 权限列表 | | [references/related-apis.md](references/related-apis.md) | 相关 APIs | | [references/interaction-guidelines.md](references/interaction-guidelines.md) | 交互指南与最佳实践 | | [references/verification-method.md](references/verification-method.md) | 验证方法 | | [references/acceptance-criteria.md](references/acceptance-criteria.md) | 验收标准 | | [references/SKILL.zh-CN.md](references/SKILL.zh-CN.md) | 中文版 | | [requirements.txt](requirements.txt) | scripts/ 的 Python 依赖项 |

qianwen skills install @aliyun/alibabacloud-analyticdb-postgresql-knowledgebase-ops