alibabacloud-bailian-rag-knowledgebase

百炼知识库检索

此 Skill 通过 HTTPS API 提供阿里云百炼知识库的查询和检索能力。

API Key 安全管理

脚本会通过 api_key.py 自动处理密钥的获取。Agent 无需手动提取、设置或传入 API Key 值，也不应这样做。

• 密钥获取会自动完成：脚本会在内部调用 api_key.py，从配置文件／环境变量中自动获取密钥。Agent 只需运行脚本命令。
• 绝不以任何形式硬编码密钥：包括 api_key = "sk-..."、export DASHSCOPE_API_KEY="sk-..."，以及在 Shell 脚本中赋值密钥。
• 绝不从 CLI 输出中提取密钥：Agent 不得将密钥值写入任何脚本、变量或文件。
• 绝不在任何输出中暴露密钥：包括生成的脚本、Shell 命令、日志文件和包含以 sk- 开头字符串的终端输出。
• 绝不读取或打印配置文件中的密钥：不得使用 cat、jq、python -c 或其他命令读取并输出 API Key 值。
• 任务完成前必须进行自检：运行 grep -rn "sk-" <output_directory>/ 检查所有输出文件；如果发现任何以 sk- 开头的字符串（sk-xxx 占位符除外），请删除受影响的文件并重新生成。

🚀 初始设置（首次使用时必须完成）

1. 配置 API Key

API Key 由统一的 scripts/api_key.py 模块管理，获取优先级如下：

1. 阿里云 CLI 配置 ~/.aliyun/config.json 当前配置中的 dashscope.api_key
2. 环境变量 DASHSCOPE_API_KEY
3. 阿里云 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 Key）
不支持	sk-sp-xxx（Coding Plan Key，不支持知识库服务）
获取密钥	https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key

阿里云 CLI 配置（自动创建／删除 API Key）

scripts/api_key.py 模块通过 aliyun modelstudio 命令创建和删除 API Key。使用前请完成以下设置：

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	获取百炼工作空间 ID	api_key.py: _get_workspace_id()
aliyun modelstudio create-api-key	创建 DashScope API Key	api_key.py: generate_api_key()
aliyun modelstudio delete-api-key	删除云端 API Key	api_key.py: _delete_cloud_api_key()

2. 重要前提条件：激活百炼知识库服务

使用此 Skill 前，必须先在阿里云百炼控制台中激活知识库服务！

1. 访问 百炼知识库页面
2. 点击 “立即开通” 按钮
3. 确认开通并等待服务生效（通常需要 1-2 分钟）

可观测性（每次运行 aliyun 命令时都必须遵守）

加载此 Skill 时，生成一个随机会话 ID（32 位小写十六进制字符串），并将其导出为 SKILL_SESSION_ID。整个 Skill 会话期间，此值必须保持不变。

每个 aliyun CLI 命令和 HTTPS API 调用都必须包含用于追踪的 User-Agent 标识。

User-Agent 格式

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

• {session-id} = SKILL_SESSION_ID 环境变量的值（32 位小写十六进制字符串）
• 脚本通过 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 请求都会设置 User-Agent HTTP 标头：

"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：qwen3-rerank-hybrid，使用 similar 模式

返回格式中，每个 chunk 内的 content 表示 chunk 内容，doc_name 表示源文档，score 表示匹配分数，title 表示 chunk 的章节标题：

{
  "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 未授权

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

API Key 错误或尚未配置。请引导用户检查 API Key 配置。

403 禁止访问

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

用户尚未开通百炼知识库服务。请引导用户开通该服务。

使用示例

用户：“我们的产品支持哪些身份验证方式？”

流程：

1. 查询知识库 → 返回 3 个知识库
2. 选择知识库 → “产品文档”（最相关）
3. 检索 → 获取与身份验证相关的文档片段
4. 回答 → “根据产品文档，支持 OAuth2.0、SAML 和 API Key 身份验证方式……”

备注

• 脚本会自动获取 API Key，Agent 不应直接处理密钥值
• 从多个知识库检索时，合并结果并去重
• 按分数对检索结果排序，优先展示相关性高的内容

API Key 自动获取流程：

1. 读取 ~/.aliyun/config.json 当前配置文件中的 dashscope.api_key → 如果找到则返回
2. 读取环境变量 DASHSCOPE_API_KEY → 如果找到则返回
3. 如果可使用 Alibaba Cloud CLI → 通过 generate_api_key() 自动创建并保存到配置文件
4. 以上方法均失败 → 显示包含设置说明的错误