alibabacloud-analyticdb-postgresql-knowledgebase-ops

ADBPG ナレッジベース管理

3 つのステップでエンタープライズ向けナレッジベースを構築します：ナレッジベースの作成 → ドキュメントのアップロード → 検索と Q&A

システムがドキュメントの解析、チャンク分割、ベクトル化、インデックス構築を自動的に処理します。ユーザーはビジネスロジックに集中できます。

アーキテクチャ：ADBPG Instance + Namespace + DocumentCollection + Vector Index + LLM Service

基本概念

• ナレッジベース：ドキュメントを格納するコンテナーで、ベクトルインデックスを自動的に管理します（API の DocumentCollection に相当）。
• ドキュメント：ナレッジベースにアップロードするファイルです。PDF／Word／Markdown／HTML／JSON／CSV／画像などに対応しています。
• Q&A：ナレッジベースと大規模言語モデルに基づくインテリジェントな会話です。

---

環境設定

[必須] CLI の User-Agent — aliyun CLI コマンドを実行するたびに、次のオプションを含める必要があります： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops

[必須] AI-Mode を有効化 — Agent Skill の実行には AI-mode が必要です。 CLI を実行する前に、次のコマンドを実行してください：

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 の呼び出し時にのみ使用し、スキルの実行終了後も有効なままにしてはいけません。

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 を実行してください。

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• 認証情報（環境変数に基づくシークレットを含む）を読み取ったり、エコーしたり、表示したりしてはいけません。
• 長期間有効なシークレットを会話やコマンドラインに直接貼り付けるよう、ユーザーに求めてはいけません。
• aliyun configure set にリテラルの認証情報を指定してはいけません。
• 認証情報の状態確認には aliyun configure list のみを使用してください。

aliyun configure list

出力を確認し、有効なプロファイル（AK、STS、または OAuth ID）があることを確認してください。

有効なプロファイルがない場合は、ここで中止してください。

1. Alibaba Cloud Console から認証情報を取得します。
2. このセッションの外で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルのプロファイルに環境変数を設定します）。
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 は Alibaba Cloud Python SDK を使用します。依存関係は requirements.txt で宣言します。スクリプトを実行する前にインストールしてください：

pip install -r requirements.txt

Python 3.7 以上が必要です（Alibaba Cloud SDK for Python と同じ最小要件です）。

---

RAM 権限

[必須] RAM 権限の事前確認： 操作を実行する前に、現在のユーザーに必要な権限があることを確認してください。 ram-permission-diagnose スキルを使用して権限を確認し、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

注：ナレッジベースをカスタム名前空間に作成した場合、その後のすべての操作で同じ namespace パラメーターを指定する必要があります。

操作ガイドライン、スマートなデフォルト値、ベストプラクティスについては、references/interaction-guidelines.mdを参照してください。

ドキュメント内のプレースホルダー： CLI の例では、<manager-account-password> や <namespace-password> のような文字列を使用しています。ユーザーから取得した実際の値に置き換えてください。実際のパスワードをドキュメント、チケット、チャットに記録またはコミットしてはいけません。

---

タイムアウトの設定

タイムアウトルール： すべての操作を妥当な時間内に完了させる必要があります。

• 標準操作：10 秒以内（作成／一覧表示／クエリ）
• ドキュメントの非同期アップロード：タイムアウト制限なし（非同期ジョブ。5～10 秒ごとにポーリング）

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 と同じソース）で認証情報を解決するようにします。スキルコードで認証情報ファイルを解析したり、生のキーを渡したりしないでください。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

重要：CreateDocumentCollection の前に、CreateNamespace を必ず実行してください。

ナレッジベースを作成する：

# 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 コードを貼り付けないでください。パッケージ化されたスクリプトのみを使用します（デフォルトの認証情報チェーン、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

---

3. 検索と Q&A

ナレッジベースを検索

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

ナレッジベースの 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

---

参考リンク

ドキュメント	内容
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 依存関係