Alibabacloud Analyticdb Postgresql Knowledgebase Ops

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.

1. Obtain credentials from Alibaba Cloud Console

2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)

3. Return and re-run after aliyun configure list shows a valid profile

Verify CLI Credentials

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:

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.

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:

# 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).

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.

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

# 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

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

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)

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

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

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

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

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

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

Acceptance Criteria - ADBPG Knowledge Base Management

Scenario: ADBPG Knowledge Base Management Skill Purpose: Skill testing acceptance criteria

Table of Contents

• 1. CLI Command Pattern Verification
• 2. Python SDK Code Pattern Verification
• 3. Workflow Verification
• 4. Parameter Verification
• 5. Security Checks
• 6. Error Handling Checks
• Checklist

---

1. CLI Command Pattern Verification

1.1 Product Name Verification

✅ CORRECT

aliyun gpdb describe-regions
aliyun gpdb init-vector-database
aliyun gpdb create-document-collection

❌ INCORRECT

# Wrong: Product name should be gpdb, not adbpg
aliyun adbpg describe-regions

# Wrong: Product name should be lowercase
aliyun GPDB describe-regions

1.2 Command Format Verification (Plugin Mode)

✅ CORRECT - Plugin mode (lowercase with hyphens)

aliyun gpdb describe-regions
aliyun gpdb init-vector-database
aliyun gpdb create-namespace
aliyun gpdb create-document-collection
aliyun gpdb upload-document-async
aliyun gpdb query-content

❌ INCORRECT - Traditional API mode (CamelCase)

# Wrong: Should use plugin mode with lowercase hyphens
aliyun gpdb DescribeRegions
aliyun gpdb InitVectorDatabase
aliyun gpdb CreateNamespace
aliyun gpdb CreateDocumentCollection

1.3 Parameter Name Format Verification

✅ CORRECT - Lowercase with hyphens

aliyun gpdb create-document-collection \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --manager-account admin \
  --manager-account-password 'pass' \
  --collection my_kb \
  --embedding-model text-embedding-v4 \
  --dimension 1024

❌ INCORRECT - CamelCase parameter names

# Wrong: Parameter names should be lowercase with hyphens
aliyun gpdb create-document-collection \
  --RegionId cn-hangzhou \
  --DBInstanceId gp-xxxxx \
  --ManagerAccount admin

1.4 User-Agent Must Be Present

✅ CORRECT

aliyun gpdb describe-regions --user-agent AlibabaCloud-Agent-Skills
aliyun gpdb query-content --content "test" --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT

# Wrong: Missing --user-agent parameter
aliyun gpdb describe-regions
aliyun gpdb query-content --content "test"

---

2. Python SDK Code Pattern Verification

2.1 Import Paths

✅ CORRECT

from alibabacloud_gpdb20160503.client import Client
from alibabacloud_gpdb20160503 import models
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

❌ INCORRECT

# Wrong: Incorrect package name
from alibabacloud_gpdb.client import Client
from alibabacloud_adbpg.client import Client

# Wrong: Incorrect version number
from alibabacloud_gpdb20200101.client import Client

2.2 Credential Reading Method

✅ CORRECT - Default credential chain (SDK)

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

Do not parse ~/.aliyun/config.json or pass raw access_key_id / access_key_secret from files in skill code; rely on CredentialClient() default resolution.

❌ INCORRECT - Hardcoded credentials

# Wrong: Never hardcode AK/SK
client = Client(Config(
    access_key_id='LTAI5tXXXXXXXXXX',
    access_key_secret='8dXXXXXXXXXXXXXXXXXXXX',
))

2.3 Local File Upload

✅ CORRECT - Packaged script (recommended)

Use scripts/upload_document_local.py: default credential chain, user_agent='AlibabaCloud-Agent-Skills', and HTTP timeouts on Config.

✅ CORRECT - Use Advance method (inline pattern)

with open(file_path, 'rb') as f:
    request = models.UploadDocumentAsyncAdvanceRequest(
        region_id='cn-hangzhou',
        dbinstance_id='gp-xxxxx',
        namespace='ns_my_kb',
        namespace_password='<namespace-password>',
        collection='my_kb',
        file_name=os.path.basename(file_path),
        file_url_object=f,  # Pass file stream
        document_loader_name='ADBPGLoader',
    )
    response = client.upload_document_async_advance(request, RuntimeOptions())

❌ INCORRECT - Regular upload method doesn't support local files

# Wrong: Regular upload_document_async doesn't support local file streams
request = models.UploadDocumentAsyncRequest(
    file_url_object=f,  # This parameter doesn't exist in regular request
)

---

3. Workflow Verification

3.1 Knowledge Base Creation Order

✅ CORRECT - Correct order

1. InitVectorDatabase (re-run may error if already initialized; handle per SKILL pre-checks)
2. CreateNamespace (MUST be before CreateDocumentCollection)
3. CreateDocumentCollection

❌ INCORRECT - Wrong order

# Wrong: Creating Collection before Namespace will fail
1. CreateDocumentCollection
2. CreateNamespace
# Error: role "knowledgebasepub" does not exist

3.2 Namespace Rules

✅ CORRECT

# Namespace name: ns_{collection}
--namespace ns_my_knowledge_base
--namespace ns_product_docs

❌ INCORRECT

# Wrong: public namespace is forbidden
--namespace public

# Wrong: Namespace should have ns_ prefix
--namespace my_knowledge_base

---

4. Parameter Verification

4.1 Required Parameter Check

Create Knowledge Base Required Parameters

Upload Document Required Parameters

4.2 Parameter Value Formats

✅ CORRECT

# Instance ID format
--db-instance-id gp-bp1234567890

# Vector dimension (number)
--dimension 1024

# JSON format parameters
--entity-types '["Person","Organization"]'
--model-params '{"Model":"qwen-max","Messages":[...]}'

❌ INCORRECT

# Wrong: Instance ID format error
--db-instance-id bp1234567890

# Wrong: Dimension is not a number
--dimension "1024"

# Wrong: JSON format error
--entity-types [Person,Organization]

---

5. Security Checks

5.1 Credential Security

✅ CORRECT

# Only check credential status, don't output sensitive values
aliyun configure list

❌ INCORRECT

# Wrong: Never output AK/SK values
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
cat ~/.aliyun/config.json | grep access_key

# Wrong: Never pass AK directly in command line
aliyun configure set --access-key-id LTAI5tXXX --access-key-secret 8dXXX

5.2 Sensitive Information Prompts

✅ CORRECT

• Prompt user "Password will be used for subsequent operations, please keep it safe"
• Don't display password in plaintext in logs or output

❌ INCORRECT

• Display password in plaintext in output
• Write password to files or logs

---

6. Error Handling Checks

6.1 Common Error Responses

6.2 Retry Strategy

✅ CORRECT

• Auto-poll upload progress after uploading document, query every 5-10 seconds
• Maximum 30 polls (about 5 minutes)

❌ INCORRECT

• Don't poll upload progress, user can't know if upload completed
• Poll interval too short (< 3 seconds), may trigger rate limiting

---

Checklist

• [ ] CLI commands use plugin mode (lowercase with hyphens)
• [ ] All CLI commands include --user-agent AlibabaCloud-Agent-Skills
• [ ] Python SDK uses correct import paths
• [ ] Python SDK uses CredentialClient() default chain (no ~/.aliyun/config.json parsing in skill code)
• [ ] Python SDK Config sets user_agent='AlibabaCloud-Agent-Skills' and reasonable connect_timeout / read_timeout
• [ ] Local file upload uses scripts/upload_document_local.py or equivalent pattern
• [ ] No hardcoded AK/SK
• [ ] Knowledge base creation follows correct order
• [ ] Namespace name uses ns_ prefix
• [ ] public namespace is forbidden
• [ ] Sensitive information not output in plaintext

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Table of Contents

• Installation
• Configuration
• Verification
• Security Best Practices
• Troubleshooting
• Advanced Configuration
• Next Steps
• References

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

Interaction Guidelines - ADBPG Knowledge Base Management

Table of Contents

• AskUserQuestion Usage Principles
• Information Collection Strategy
• Smart Defaults
• Best Practices

---

AskUserQuestion Usage Principles

AskUserQuestion should only be used for limited option selections, not for free-form input:

Anti-pattern: Don't put "Let me input" as an AskUserQuestion option. Users cannot enter free-form text in options. For free-form input, simply ask in your reply text.

---

Information Collection Strategy

When Creating a Knowledge Base

Collect via text conversation:

Please provide the following information:
1. Instance ID (format: gp-bp1234567890)
2. Manager account name
3. Manager account password
4. Namespace password (needed for upload/search/Q&A, recommend different from manager password)
5. Knowledge base name (lowercase letters and underscores)

When Uploading Documents

Collect via text conversation:

Please provide the file source:
- Public URL: Give me the link directly
- Local file: Give me the file path, e.g., /Users/xxx/docs/manual.pdf
- Local directory: Give me the directory path, e.g., /Users/xxx/docs/, I'll scan supported files

---

Smart Defaults

Text Knowledge Base

Image Knowledge Base

Note: Image and text knowledge bases cannot share the same Collection due to different EmbeddingModel and Dimension. Create them separately.

Chunking Strategies

---

Best Practices

1. Focus on user goals, don't expose underlying concepts (namespaces, vector dimensions, HNSW params, etc.) unless user asks 2. Execute query operations directly without confirmation 3. Show key parameters for modification operations and confirm before execution, don't show all parameters 5. Execute in sequence when creating knowledge base: InitVectorDatabase → CreateNamespace → CreateDocumentCollection; duplicate creates return explicit errors—handle per SKILL.md Create Knowledge Base pre-checks (not silent idempotency); keep transparent to the user where possible 6. Collect namespace password when creating knowledge base, needed for upload/search/Q&A later, don't wait to ask 7. Auto-poll upload progress after uploading, query every 5-10 seconds, notify user when complete 8. Use SDK for local file uploads, auto-handles OSS transfer, transparent to user 9. Remember parameters within session: DBInstanceId, ManagerAccount, NamespacePassword etc., provide once, reuse throughout 10. Auto-assemble JSON for Q&A: User only provides question text, agent constructs ModelParams/KnowledgeParams 11. Free-form input via text conversation, limited choices via AskUserQuestion: paths, URLs, passwords should not use AskUserQuestion 12. Password parameters involve sensitive info, remind user about security 13. All CLI commands MUST include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

---

Quick Guide

---

Auto-Create Instance When None Available

When user has no available ADBPG instance (or instance reports Instance.NotSupportVector):

1. Look for a skill that can create instances (keywords: ADBPG or AnalyticDB PostgreSQL) 2. If found, invoke that skill to create instance with recommended config:

• Version: 7.0
• Spec: 4C16G
• Type: HighAvailability
• Enable vector optimization

3. Wait for instance to be available, then continue knowledge base operations

RAM Policies - ADBPG Knowledge Base Management

This document lists the RAM permissions required for ADBPG Knowledge Base Management.

Minimum Permission Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "gpdb:DescribeRegions",
        "gpdb:DescribeDBInstances",
        "gpdb:InitVectorDatabase",
        "gpdb:CreateNamespace",
        "gpdb:CreateDocumentCollection",
        "gpdb:UploadDocumentAsync",
        "gpdb:GetUploadDocumentJob",
        "gpdb:CancelUploadDocumentJob",
        "gpdb:ListDocuments",
        "gpdb:DescribeDocument",
        "gpdb:UpsertChunks",
        "gpdb:QueryContent",
        "gpdb:QueryKnowledgeBasesContent",
        "gpdb:ChatWithKnowledgeBase"
      ],
      "Resource": "*"
    }
  ]
}

Permission Descriptions

Permissions by Function

Basic Query (Read-only)

{
  "Effect": "Allow",
  "Action": [
    "gpdb:DescribeRegions",
    "gpdb:DescribeDBInstances",
    "gpdb:ListDocumentCollections",
    "gpdb:ListDocuments",
    "gpdb:DescribeDocument",
    "gpdb:QueryContent",
    "gpdb:QueryKnowledgeBasesContent",
    "gpdb:ChatWithKnowledgeBase",
    "gpdb:GetUploadDocumentJob"
  ],
  "Resource": "*"
}

Knowledge Base Management (Read-Write)

{
  "Effect": "Allow",
  "Action": [
    "gpdb:InitVectorDatabase",
    "gpdb:CreateNamespace",
    "gpdb:ListNamespaces",
    "gpdb:CreateDocumentCollection"
  ],
  "Resource": "*"
}

Document Management (Read-Write)

{
  "Effect": "Allow",
  "Action": [
    "gpdb:UploadDocumentAsync",
    "gpdb:CancelUploadDocumentJob",
    "gpdb:UpsertChunks"
  ],
  "Resource": "*"
}

Additional Permissions for SDK Local File Upload

If you need to upload local files via SDK (SDK internally uses OSS for transfer), you also need the following OSS permissions:

{
  "Effect": "Allow",
  "Action": [
    "oss:PutObject",
    "oss:GetObject"
  ],
  "Resource": "acs:oss:*:*:gpdb-*"
}

Permission Verification

Use the following commands to verify current user has required permissions:

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

# Test instance query permission
aliyun gpdb describe-dbinstances --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

Reference Documentation

• ADBPG API Documentation
• RAM Permission Management

Related APIs - ADBPG Knowledge Base Management

This document lists all APIs and CLI commands involved in ADBPG Knowledge Base Management.

API List

Grouped by Function

Instance Management

Namespace Management

Knowledge Base Management

Document Management

Search & Q&A

Common Parameters

General Parameters

Authentication Parameters

Knowledge Base Parameters

Document Parameters

Search Parameters

CLI Help Commands

# View product help
aliyun gpdb --help

# View specific command help
aliyun gpdb create-document-collection --help
aliyun gpdb upload-document-async --help
aliyun gpdb query-content --help

Reference Documentation

• ADBPG OpenAPI Documentation
• ADBPG Knowledge Base API Reference

ADBPG 知识库管理

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

系统自动处理文档解析、切片、向量化、索引构建，用户只需关注业务。

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

英文版见 SKILL.md。

核心概念

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

---

环境准备

[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 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（含基于环境变量的密钥）

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

1. Obtain credentials from Alibaba Cloud Console

2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)

3. Return and re-run after aliyun configure list shows a valid 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 权限

[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 ram-policies.md.

If any permission is missing, abort and prompt user.

---

参数确认

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.

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

交互规范、智能默认值和最佳实践详见 interaction-guidelines.md。

文档占位符： 命令示例中的 <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 一致）；不要在技能代码中解析凭证文件或传入明文密钥。在 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',
))

---

核心工作流

一、知识库管理

创建知识库

前置检查（按顺序执行；并非静默幂等）：

• 重名： 若资源已存在再次执行创建，接口通常返回明确错误（冲突、已存在等）。不得重复创建同名资源；仅当响应明确表明资源已存在时，可将该错误视为本步已满足并继续后续流程，否则须排查。
• 重试与 ClientToken： 针对网络超时等重试，若 API 或 aliyun gpdb 该子命令支持 ClientToken，应使用（见 aliyun gpdb <子命令> --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

---

二、文档管理

上传文档（公网 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

---

三、检索与问答

检索知识库

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

---

参考链接

Verification Method - ADBPG Knowledge Base Management

This document describes how to verify that ADBPG Knowledge Base operations executed successfully.

Table of Contents

• 1. Environment Verification
• 2. Knowledge Base Management Verification
• 3. Document Management Verification
• 4. Search & Q&A Verification
• Common Error Troubleshooting

---

1. Environment Verification

1.1 CLI Version Verification

aliyun version

Success Criteria: Version >= 3.3.3

1.2 Credential Verification

aliyun configure list

Success Criteria: Shows valid profile configuration

1.3 API Connectivity Verification

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

Success Criteria: Returns region list JSON

---

2. Knowledge Base Management Verification

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

Success Criteria:

• Returns RequestId
• No error messages

Verification Command: If the call succeeds, no extra verification; if the operation was already applied, expect an explicit API error—handle duplicate / already-exists per SKILL.md create pre-checks.

2.2 Create Namespace

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_test_kb \
  --namespace-password '<namespace-password>' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

Success Criteria:

• Returns RequestId
• No error messages

Verification Command: No direct namespace query API, verify through subsequent operations

2.3 Create Knowledge Base

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>' \
  --collection test_knowledge_base \
  --embedding-model text-embedding-v4 \
  --dimension 1024 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

Success Criteria:

• Returns RequestId
• No error messages

Verification Command:

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

Verification Criteria: Result contains test_knowledge_base

---

3. Document Management Verification

3.1 Upload Document

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

Success Criteria:

• Returns JobId
• Status is running or completed

Verification Command (poll progress):

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

Verification Criteria:

• Status is completed
• Progress is 100

3.2 List Documents

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

Success Criteria:

• Returns document list
• Contains uploaded document name

---

4. Search & Q&A Verification

4.1 Search Knowledge Base

aliyun gpdb query-content \
  --biz-region-id cn-hangzhou \
  --db-instance-id gp-xxxxx \
  --namespace-password '<namespace-password>' \
  --collection test_knowledge_base \
  --content "test query" \
  --topk 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

Success Criteria:

• Returns Matches array
• Each result contains Content and Score

4.2 Knowledge Base Q&A

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":"test question"}]}' \
  --knowledge-params '{"SourceCollection":[{"Collection":"test_knowledge_base","NamespacePassword":"<namespace-password>","TopK":10}]}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

Success Criteria:

• Returns Response field
• Contains LLM-generated answer

---

Common Error Troubleshooting