alibabacloud-bailian-rag-knowledgebase：阿里云百炼知识库（RAG）基于先进的通义 Embedding、Rerank 模型，支持丰富的文本、多模态检索能力，助力企业构建专属知识库。通过离线索引构建与在线应用运行，子环节可见，实现关键链路可解释、可运营、可干预；可通过离线数据增强与 meta 信息自定义抽取，定向增强企业场景效果，通用场景端到端满意度高达 80%+，简单优化可达 90% 以上。

百炼知识库检索

本 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 当前 profile 的 dashscope.api_key
2. 环境变量 DASHSCOPE_API_KEY
3. 阿里云 CLI 可用时自动创建并保存（generate_api_key()）

所有脚本都使用这一统一方式

from api_key import get_api_key

api_key = get_api_key() # 返回 str，未找到时抛出 ValueError

手动配置环境变量：

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. 更新插件**

更新插件到最新版本

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. 访问[百炼知识库页面](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/knowledge-base)
2. 点击 **"立即开通"** 按钮
3. 确认开通并等待服务生效（通常 1-2 分钟）

可观测性（每条 aliyun 命令都必须遵守）

加载本 Skill 时，生成一个随机 session 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/ 目录：

工作流

步骤 1：查询知识库列表

运行 scripts/list_indices.py 获取所有可用知识库：

python3 scripts/list_indices.py

返回格式：

[
  {
    "id": "qf91w6402d",
    "name": "产品文档",
    "description": "包含产品用户手册、API 文档等"
  },
  {
    "id": "ip93d2pyvz",
    "name": "客服问答",
    "description": "FAQ、客服话术"
  }
]

分页： page_number 从 1 开始（默认），page_size 默认 10。若当前页未完全获取，继续获取下一页：

python3 scripts/list_indices.py 2 10

步骤 2：智能选择知识库

根据用户问题和知识库描述，选择 1-3 个最相关的知识库进行检索。

选择策略：

• 匹配关键词（问题中的关键词 vs 知识库名称 / 描述）
• 优先选择描述中明确包含相关领域的知识库
• 不确定时，选择全部或让用户手动选择

步骤 3：执行检索

对每个选中的知识库，运行 scripts/retrieve.py index_id query [top_n]：

python3 scripts/retrieve.py lj3hgbq60t "java" 5

参数：

• index_id（必填）：知识库 ID
• query（必填）：搜索查询文本
• top_n（可选）：返回的 top 结果数量，默认 5，最大 20

检索 API 使用以下配置：

• dense_similarity_top_k: 100
• sparse_similarity_top_k: 100
• enable_reranking: true
• rerank: qwen3-rerank-hybrid，similar 模式

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

{
  "indexId": "lj3hgbq60t",
  "chunks": [
    {
      "content": "文档分块内容...",
      "score": 0.6040189862251282,
      "doc_name": "example-doc.pdf",
      "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"}

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

用法示例

用户： "我们的产品支持哪些认证方式？"

流程：

1. 查询知识库 → 返回 3 个知识库
2. 选择知识库 → "产品文档"（最相关）
3. 检索 → 获取认证相关文档分块
4. 回答 → "根据产品文档，支持 OAuth2.0、SAML 和 API Key 认证方式……"

注意事项

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

API Key 自动获取流程：

1. 读取 ~/.aliyun/config.json 当前 profile 的 dashscope.api_key → 找到则返回
2. 读取环境变量 DASHSCOPE_API_KEY → 找到则返回
3. 阿里云 CLI 可用 → 通过 generate_api_key() 自动创建并保存到配置
4. 以上全部失败 → 报错并附设置说明