alibabacloud-bailian-rag-knowledgebase

Bailian ナレッジベース検索

このスキルは、HTTPS API を通じて Alibaba Cloud Bailian ナレッジベースのクエリと検索機能を提供します。

API キーのセキュリティ管理

スクリプトは api_key.py を通じてキーを自動的に取得します。エージェントが API キーの値を手動で抽出、設定、または渡す必要はなく、そうしてはいけません。

• キーの取得は自動化されています：スクリプトは内部で api_key.py を呼び出し、設定ファイルや環境変数からキーを自動的に取得します。エージェントはスクリプトのコマンドを実行するだけで済みます。
• いかなる形式でもキーをハードコードしてはいけません：api_key = "sk-..."、export DASHSCOPE_API_KEY="sk-..."、シェルスクリプト内でのキーの割り当てなどが該当します。
• CLI の出力からキーを抽出してはいけません：エージェントは、キーの値をスクリプト、変数、またはファイルに書き込んではいけません。
• 出力にキーを含めてはいけません：生成されたスクリプト、シェルコマンド、ログファイル、および sk- で始まる文字列を含むターミナル出力が該当します。
• 設定ファイルからキーを読み取ったり、表示したりしてはいけません：API キーの値を読み取って出力するために、cat、jq、python -c、その他のコマンドを使用しないでください。
• タスク完了前の自己確認は必須です：grep -rn "sk-" <output_directory>/ を実行してすべての出力ファイルを確認してください。sk-xxx のプレースホルダーを除き、sk- で始まる文字列が見つかった場合は、該当するファイルを削除して再生成してください。

🚀 初期設定（初回利用時に必須）

1. API キーを設定する

API キーは統一された scripts/api_key.py モジュールで管理され、次の優先順位で取得されます。

1. Alibaba Cloud CLI の設定 ~/.aliyun/config.json にある、現在のプロファイルの dashscope.api_key
2. 環境変数 DASHSCOPE_API_KEY
3. Alibaba Cloud CLI が利用可能な場合は、自動で作成して保存（generate_api_key()）

# All scripts use this unified approach
from api_key import get_api_key
api_key = get_api_key()  # Returns str, raises ValueError if not found

環境変数を手動で設定する場合：

export DASHSCOPE_API_KEY=sk-xxx

項目	説明
キー形式	sk-xxx（標準の DashScope API キー）
サポート対象外	sk-sp-xxx（Coding Plan キー。ナレッジベースサービスには対応していません）
キーの取得先	https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key

Alibaba Cloud CLI の設定（API キーの自動作成／削除）

scripts/api_key.py モジュールは、aliyun modelstudio コマンドを使って API キーを作成・削除します。使用する前に、次の設定を完了してください。

1. プラグインを更新する

# Update plugins to latest version
aliyun plugin update

2. ModelStudio プラグインをインストールする（まだインストールされていない場合）

aliyun plugin install --names aliyun-cli-modelstudio --enable-pre

使用する CLI コマンド：

コマンド	目的	呼び出し元
aliyun modelstudio list-workspaces	Bailian ワークスペース ID の取得	api_key.py: _get_workspace_id()
aliyun modelstudio create-api-key	DashScope API キーの作成	api_key.py: generate_api_key()
aliyun modelstudio delete-api-key	クラウド API キーの削除	api_key.py: _delete_cloud_api_key()

2. 重要な前提条件：Bailian ナレッジベースサービスを有効化する

このスキルを使用する前に、Alibaba Cloud Bailian コンソールでナレッジベースサービスを有効化する必要があります！

1. Bailian ナレッジベースのページにアクセスします
2. **「今すぐ有効化」**ボタンをクリックします
3. 有効化を確認し、サービスが反映されるまで待ちます（通常 1～2 分）

可観測性（すべての aliyun コマンドで必ず遵守）

このスキルを読み込んだら、ランダムなセッション ID（32 文字の小文字の 16 進数文字列）を生成し、SKILL_SESSION_ID としてエクスポートしてください。この値は、スキルのセッション全体を通じて固定する必要があります。

すべての aliyun CLI コマンドと HTTPS API 呼び出しには、追跡可能にするための User-Agent 識別子を含める必要があります。

User-Agent の形式

AlibabaCloud-Agent-Skills/alibabacloud-bailian-rag-knowledgebase/{session-id}

• {session-id} = 環境変数 SKILL_SESSION_ID の値（32 文字の小文字の 16 進数文字列）
• スクリプトは os.environ.get("SKILL_SESSION_ID", "") で値を読み取ります。空の場合は、secrets.token_hex(16) を使用して生成します

コマンドごとの --user-agent（CLI）

すべての aliyun modelstudio ビジネスコマンドには、コマンドラインで --user-agent を指定する必要があります。

aliyun modelstudio list-workspaces --region cn-beijing \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-bailian-rag-knowledgebase/{session-id}"

禁止事項：グローバル設定コマンドで User-Agent を設定しないでください。コマンドごとの --user-agent のみ使用できます。

HTTPS User-Agent ヘッダー

すべての HTTPS API リクエストで、HTTP ヘッダー User-Agent を設定します。

"User-Agent": f"AlibabaCloud-Agent-Skills/alibabacloud-bailian-rag-knowledgebase/{session_id}"

適用箇所

場所	方式
scripts/list_indices.py	_get_user_agent() を介した HTTPS User-Agent ヘッダー
scripts/retrieve.py	_get_user_agent() を介した HTTPS User-Agent ヘッダー
scripts/api_key.py → _get_workspace_id()	aliyun modelstudio list-workspaces --user-agent ...
scripts/api_key.py → generate_api_key()	aliyun modelstudio create-api-key --user-agent ...
scripts/api_key.py → _delete_cloud_api_key()	aliyun modelstudio delete-api-key --user-agent ...

利用可能なスクリプト

すべてのスクリプトは scripts/ ディレクトリにあります。

スクリプト	用途	パラメーター
api_key.py	API Key の管理（取得、作成、削除）	-
list_indices.py	ナレッジベースの一覧を照会	[page_number] [page_size]
retrieve.py	指定したナレッジベースから検索	index_id query [top_n]

ワークフロー

ステップ 1：ナレッジベースの一覧を照会

scripts/list_indices.py を実行して、利用可能なすべてのナレッジベースを取得します。

python3 scripts/list_indices.py

戻り値の形式：

[
  {
    "id": "qf91w6402d",
    "name": "Product Documentation",
    "description": "Contains product user manuals, API documentation, etc."
  },
  {
    "id": "ip93d2pyvz",
    "name": "Customer Service Q&A",
    "description": "FAQ, customer service scripts"
  }
]

ページネーション： page_number は 1 から始まり（デフォルト）、page_size のデフォルトは 10 です。現在のページをすべて取得できていない場合は、次のページも取得します。

python3 scripts/list_indices.py 2 10

ステップ 2：ナレッジベースをインテリジェントに選択

ユーザーの質問とナレッジベースの説明に基づいて、検索に最も関連性の高いナレッジベースを 1～3 件選択します。

選択戦略：

• キーワードを照合します（質問内のキーワードとナレッジベース名／説明を比較）
• 説明に関連フィールドが明記されているナレッジベースを優先します
• 判断が難しい場合は、すべて選択するか、ユーザーに選択してもらいます

ステップ 3：検索を実行

選択したナレッジベースごとに、scripts/retrieve.py index_id query [top_n] を実行します。

python3 scripts/retrieve.py lj3hgbq60t "java" 5

パラメーター：

• index_id（必須）：ナレッジベース ID
• query（必須）：検索クエリのテキスト
• top_n（任意）：返す上位結果の数。デフォルトは 5、最大 20

検索 API では、次の設定を使用します。

• dense_similarity_top_k：100
• sparse_similarity_top_k：100
• enable_reranking：true
• rerank：similar モードの qwen3-rerank-hybrid

戻り値の形式では、各チャンク内の content がチャンクの内容、doc_name がソースドキュメント、score が一致度スコア、title がチャンクのセクションタイトルを表します。

{
  "indexId": "lj3hgbq60t",
  "chunks": [
    {
      "content": "Document chunk content...",
      "score": 0.6040189862251282,
      "doc_name": "example-doc.pdf",
      "title": "Section Title"
    }
  ]
}

ステップ 4：回答をまとめる

検索結果に基づいて、次の手順を実行します。

1. 関連度の高い順（score の降順）に並べ替えます
2. 重要な情報を抽出します
3. 自然な文章で回答をまとめます
4. 生成した回答の末尾に情報源（ナレッジベース名、ドキュメント名、セクション名）を明記してください。複数のドキュメントやセクションを参照できます。

よくあるエラー

401 Unauthorized

{"code": "InvalidApiKey", "message": "Invalid API-KEY"}

API Key が間違っているか、設定されていません。API Key の設定を確認するようユーザーに案内してください。

403 Forbidden

{"code": "Forbidden", "message": "Service not activated"}

ユーザーは Bailian Knowledge Base サービスを有効化していません。有効化するようユーザーに案内してください。

使用例

ユーザー：「当社の製品はどのような認証方式に対応していますか？」

フロー：

1. ナレッジベースを照会 → 3 件のナレッジベースが返されます
2. ナレッジベースを選択 → 「製品ドキュメント」（最も関連性が高いもの）
3. 検索 → 認証に関連するドキュメントのチャンクを取得します
4. 回答 →「製品ドキュメントによると、OAuth2.0、SAML、API Key による認証方式に対応しています……」

注意事項

• API キーはスクリプトによって自動的に取得されます。エージェントがキーの値を直接扱うことは決してありません。
• 複数のナレッジベースから取得する場合は、結果を統合して重複を除去します。
• 取得結果をスコア順に並べ、関連性の高いコンテンツを優先します。

API キーの自動取得フロー：

1. ~/.aliyun/config.json の現在のプロファイルから dashscope.api_key を読み取ります → 見つかった場合は返します
2. 環境変数 DASHSCOPE_API_KEY を読み取ります → 見つかった場合は返します
3. Alibaba Cloud CLI が利用可能な場合 → generate_api_key() を自動的に実行して作成し、設定ファイルに保存します
4. 上記すべてに失敗した場合 → セットアップ手順を含むエラーを返します