/alibabacloud-analyticdb-postgresql-knowledgebase-ops

name: alibabacloud-analyticdb-postgresql-knowledgebase-ops
description: |
  ADBPG Knowledge Base Management: Create knowledge bases, upload documents, search, Q&A.
  Triggers: "knowledge base", "document library", "document upload", "knowledge search", "RAG", "Q&A", "embedding", "ADBPG", "AnalyticDB PostgreSQL"

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](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](https://ram.console.aliyun.com/manage/ak) > 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`](scripts/upload_document_local.py) uses the Alibaba Cloud Python SDK. Declare dependencies in [`requirements.txt`](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](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](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.