百炼知识库检索

此 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（编程计划密钥，不支持知识库服务） | | 获取密钥 | 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 密钥管理（获取、创建、删除） | - | | 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，使用相似度模式

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

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

步骤 4：整合答案

根据检索结果：

1. 按相关性排序（分数降序）
2. 提取关键信息
3. 使用自然语言组织答案
4. 请在生成答案的末尾标注信息来源（知识库名称；文档名称；章节名称），可以引用多个文档和章节。

常见错误

401 未授权

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

API 密钥不正确或未配置。引导用户检查其 API 密钥配置。

403 禁止访问

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

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

使用示例

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

流程：

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

注意事项

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

API 密钥自动获取流程：

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