ADBPG Knowledge Base Management

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

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

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

Verify CLI Credentials

bash

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

Script dependencies (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).

RAM Permissions

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

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.

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

# 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 (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',
))

Core Workflow

1. Knowledge Base Management

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

# 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 MUST be executed before CreateDocumentCollection

Create knowledge base:

bash

# 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

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

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

2. Document Management

Upload Document (Public 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

Upload Document (Local File - 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.

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

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

3. Search & Q&A

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

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

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

alibabacloud-analyticdb-postgresql-knowledgebase-ops

NPX Install

Tags

SKILL.md Content

ADBPG Knowledge Base Management

Core Concepts

Environment Setup

Verify CLI Credentials

Script dependencies (Python)

RAM Permissions

Parameter Confirmation

Timeout Configuration

Core Workflow

1. Knowledge Base Management

Create Knowledge Base

List Knowledge Bases

List Namespaces

2. Document Management

Upload Document (Public URL)

Upload Document (Local File - SDK)

Poll Upload Progress

List Documents

3. Search & Q&A

Search Knowledge Base

Knowledge Base Q&A

Reference Links