alibabacloud-analyticdb-postgresql-knowledgebase-ops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADBPG Knowledge Base Management

ADBPG知识库管理

Build enterprise knowledge bases in three steps: Create Knowledge Base → Upload Documents → Search & Q&A

The system automatically handles document parsing, chunking, vectorization, and index building. Users only need to focus on business logic.

Architecture:

ADBPG Instance + Namespace + DocumentCollection + Vector Index + LLM Service

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

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

架构：

ADBPG Instance + Namespace + DocumentCollection + Vector Index + LLM Service

Core Concepts

核心概念

Knowledge Base: Container for documents, automatically manages vector indexes (corresponds to DocumentCollection in API)
Document: Files uploaded to the knowledge base, supports PDF/Word/Markdown/HTML/JSON/CSV/images, etc.
Q&A: Intelligent conversation based on knowledge base + large language model

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

Environment Setup

环境配置

[MUST] CLI User-Agent — Every

aliyun

CLI command invocation must include:

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

[MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:
bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops"

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
bash
aliyun configure ai-mode disable

Pre-check: Aliyun CLI >= 3.3.3 required Run
aliyun version
to verify >= 3.3.3. If not installed or version too low, run
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
to install/update, or see references/cli-installation-guide.md for installation instructions. Then [MUST] run
aliyun configure set --auto-plugin-install true
to enable automatic plugin installation. Then [MUST] run
aliyun plugin update
to ensure that any existing plugins on your local machine are always up-to-date.

Pre-check: Alibaba Cloud Credentials Required

Security Rules:
NEVER read, echo, or print credential material (including environment-based secrets)

NEVER ask the user to paste long-lived secrets directly in the conversation or command line
NEVER use
aliyun configure set
with literal credential values
ONLY use
aliyun configure list
to check credential status
bash
aliyun configure list
Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.
Obtain credentials from Alibaba Cloud Console
Configure credentials outside of this session (via
aliyun configure
in terminal or environment variables in shell profile)
Return and re-run after
aliyun configure list
shows a valid profile

[必须配置] CLI User-Agent — 每次调用

aliyun

CLI命令都必须包含：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

[必须启用] AI模式 — 执行Agent Skill需要启用AI模式。在调用任何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模式 — 无论出于何种原因返回最终响应前，务必先禁用AI模式。这适用于所有退出场景：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不再执行CLI命令的场景。 AI模式仅用于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
检查输出是否包含有效配置文件（AK、STS或OAuth身份）。

若无有效配置文件，请在此停止操作。
从阿里云控制台获取凭证
在本次会话外配置凭证（通过终端的
aliyun configure
或Shell配置文件中的环境变量）
待
aliyun configure list
显示有效配置文件后，再返回继续操作

Verify CLI Credentials

验证CLI凭证

bash

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

bash

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

Script dependencies (Python)

脚本依赖（Python）

scripts/upload_document_local.py

uses the Alibaba Cloud Python SDK. Declare dependencies in

requirements.txt

. Install before running the script:

bash

pip install -r requirements.txt

Requires Python 3.7+ (same baseline as Alibaba Cloud SDK for Python).

scripts/upload_document_local.py

使用阿里云Python SDK。依赖声明在

requirements.txt

中。运行脚本前请先安装：

bash

pip install -r requirements.txt

需要Python 3.7+（与阿里云Python SDK基线版本一致）。

RAM Permissions

RAM权限

[MUST] RAM Permission Pre-check: Before executing operations, verify current user has required permissions. Use
ram-permission-diagnose
skill to check permissions, then compare against references/ram-policies.md. If any permission is missing, abort and prompt user.

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

Parameter Confirmation

参数确认

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Parameter	Required/Optional	Description	Default Value
biz-region-id	Required	Region ID	cn-hangzhou
db-instance-id	Required	Instance ID (format: gp-xxxxx)	-
manager-account	Required	Manager account name	-
manager-account-password	Required	Manager account password	-
namespace	Optional	Namespace name	public
namespace-password	Required	Namespace password	-
collection	Required	Knowledge base name	-
embedding-model	Optional	Embedding model	text-embedding-v4
dimension	Optional	Vector dimension	1024

Note: If the knowledge base is created in a custom namespace, all subsequent operations must specify the same namespace parameter.

For interaction guidelines, smart defaults, and best practices, see references/interaction-guidelines.md.

Documentation placeholders: CLI examples use strings like
<manager-account-password>
and
<namespace-password>
. Replace them with real values from the user; never commit or log real passwords in docs, tickets, or chat.

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

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

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

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

Timeout Configuration

超时配置

Timeout Rules: All operations must complete within reasonable time limits.

Standard operations: ≤10 seconds (create/list/query)

Upload document async: No timeout limit (async job, poll every 5-10s)

CLI Timeout Settings:

bash

undefined

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

标准操作：≤10秒（创建/列出/查询）

异步上传文档：无超时限制（异步任务，每5-10秒轮询一次）

CLI超时设置：

bash

undefined

Add --ConnectTimeout and --ReadTimeout to all commands

为所有命令添加--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 (default credential chain + timeouts + User-Agent):**

Use `CredentialClient()` with no arguments so the SDK resolves credentials via the **default chain** (same sources as the CLI). Do not parse credential files or pass raw keys in skill code. Set `user_agent` and HTTP timeouts on `Config` (milliseconds).

```python
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',
))


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

使用无参数的`CredentialClient()`，让SDK通过**默认链**解析凭证（与CLI的来源相同）。请勿在Skill代码中解析凭证文件或传入原始密钥。在`Config`中设置`user_agent`和HTTP超时（毫秒）。

```python
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',
))

Core Workflow

核心工作流

1. Knowledge Base Management

1. 知识库管理

Create Knowledge Base

创建知识库

Pre-checks (run in order; not silent idempotency):

Duplicate names: If a create step is run again when the resource already exists, the API returns a clear error (e.g. conflict / already exists). Do not create duplicate resources; interpret already-exists-style errors as “this step is satisfied” only when the response clearly indicates the resource is present, then continue the workflow.
Retries / ClientToken: For network-level retries (e.g. timeout), use ClientToken when the API or
```
aliyun gpdb
```
exposes it for that subcommand—check
```
aliyun gpdb <subcommand> --help
```
. The examples below omit it when the plugin does not list it globally.

bash

undefined

预检查（按顺序执行；不支持静默幂等）：

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

bash

undefined

1. Initialize vector database

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. Create namespace (naming rule: ns_{collection}, public is forbidden)

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


> **Important**: CreateNamespace MUST be executed before CreateDocumentCollection

**Create knowledge base**:

```bash


> **重要提示**：必须先执行CreateNamespace，再执行CreateDocumentCollection

**创建知识库**：

```bash

3. Create knowledge base (in the previously created namespace)

3. 在已创建的命名空间中创建知识库

undefined

undefined

List Knowledge Bases

列出知识库

bash

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

bash

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

List Namespaces

列出命名空间

bash

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

bash

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. Document Management

2. 文档管理

Upload Document (Public URL)

上传文档（公共URL）

bash

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

bash

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

Upload Document (Local File - SDK)

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

Local files use Python SDK

upload_document_async_advance

. Do not paste multi-line Python into the skill; use the packaged script only (default credential chain,

user_agent

Config

timeouts, and

RuntimeOptions

timeouts — see

scripts/upload_document_local.py

bash

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

See scripts/upload_document_local.py.

本地文件需使用Python SDK的

upload_document_async_advance

。请勿将多行Python代码粘贴至Skill中；仅使用打包好的脚本（默认凭证链、

user_agent

、

Config

超时和

RuntimeOptions

超时——详见

scripts/upload_document_local.py

）。

bash

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。

Poll Upload Progress

轮询上传进度

bash

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

bash

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

List Documents

列出文档

bash

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

bash

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. Search & Q&A

3. 搜索与问答

Search Knowledge Base

搜索知识库

bash

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

bash

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

Knowledge Base Q&A

知识库问答

bash

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

bash

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

Reference Links

参考链接

Document	Content
references/cli-installation-guide.md	CLI Installation Guide
references/ram-policies.md	RAM Permissions List
references/related-apis.md	Related APIs
references/interaction-guidelines.md	Interaction Guidelines & Best Practices
references/verification-method.md	Verification Method
references/acceptance-criteria.md	Acceptance Criteria
references/SKILL.zh-CN.md	Chinese Version
requirements.txt	Python deps for `scripts/`

文档	内容
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脚本的依赖