SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场alibabacloud-bailian-rag-knowledgebase

alibabacloud-bailian-rag-knowledgebase

数据与分析

查看项目

更新于 10-15 14:42

技能介绍

用途

本技能为阿里云百炼知识库提供查询与检索能力，通过 HTTPS API 访问知识库内容。适用于用户需要查询知识库、检索文档资料等场景。

主要能力

  • 查询知识库列表：获取当前账号下所有可用的知识库及其 ID、名称、描述。
  • 检索指定知识库：根据查询文本从指定知识库中检索相关内容，返回文档分块、来源文档名、章节标题和匹配分数。
  • API Key 自动管理：脚本内部通过 api_key.py 自动从配置文件或环境变量获取密钥，Agent 无需手动处理密钥值。

使用方式

首次使用前置配置

  1. 配置 API Key。密钥由统一的 scripts/api_key.py 模块管理，获取优先级为：阿里云 CLI 配置 ~/.aliyun/config.json 当前 profile 的 dashscope.api_key；环境变量 DASHSCOPE_API_KEY；在阿里云 CLI 可用时自动创建并保存。也可手动配置环境变量：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

  2. 阿里云 CLI 配置（用于 API Key 自动创建/删除）。需先更新插件：aliyun plugin update；再安装 ModelStudio 插件：aliyun plugin install --names aliyun-cli-modelstudio --enable-pre。涉及命令包括 aliyun modelstudio list-workspaces（获取百炼工作空间 ID）、aliyun modelstudio create-api-key（创建 DashScope API Key）、aliyun modelstudio delete-api-key（删除云端 API Key）。

  3. 重要前提：开通百炼知识库服务。使用前必须先在阿里云百炼控制台开通知识库服务：访问百炼知识库页面，点击“立即开通”按钮，确认开通并等待服务生效（通常 1-2 分钟）。

可观测性要求

加载本技能时生成一个随机会话 ID（32 位小写十六进制字符串）并导出为 SKILL_SESSION_ID，整个技能会话期间保持不变。每条 aliyun CLI 命令和 HTTPS API 调用都必须携带 User-Agent 标识，格式为：AlibabaCloud-Agent-Skills/alibabacloud-bailian-rag-knowledgebase/{session-id}。CLI 命令通过每条命令的 --user-agent 参数设置，禁止通过全局配置命令设置 User-Agent。HTTPS 请求通过 User-Agent HTTP 头设置。

可用脚本

所有脚本位于 scripts/ 目录：

  • api_key.py：API Key 管理（获取、创建、删除）。
  • list_indices.py：查询知识库列表，参数 [page_number] [page_size]。
  • retrieve.py：从指定知识库检索，参数 index_id query [top_n]。

工作流程

步骤 1：查询知识库列表。运行 python3 scripts/list_indices.py 获取所有可用知识库。返回格式为包含 id、name、description 的 JSON 数组。分页时 page_number 从 1 开始（默认），page_size 默认为 10；若当前页未取完，继续取下一页，例如 python3 scripts/list_indices.py 2 10。

步骤 2：智能选择知识库。根据用户问题和知识库描述，选择 1-3 个最相关的知识库进行检索。选择策略：匹配关键词（问题中的关键词与知识库名称/描述对比）；优先选择描述中明确包含相关领域的知识库；若不确定，选择全部或让用户手动选择。

步骤 3：执行检索。对每个选中的知识库运行 python3 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 with similar mode。返回格式中，每个 chunk 的 content 表示分块内容，doc_name 表示来源文档，score 表示匹配分数，title 表示分块章节标题。

步骤 4：整合答案。根据检索结果：按相关性排序（分数降序）；提取关键信息；用自然语言组织答案。请在生成的答案末尾标注信息来源（知识库名称；文档名称；章节名称），可引用多个文档和章节。

适用场景

  • 用户询问产品文档、API 文档相关内容。
  • 用户需要从客服问答、FAQ 等知识库中检索答案。
  • 需要跨多个知识库检索并整合信息的问答场景。

限制与注意事项

  • 使用前必须开通百炼知识库服务，否则返回 403 Forbidden（Service not activated）。
  • API Key 不正确或未配置时返回 401 Unauthorized（InvalidApiKey）。
  • 不支持 sk-sp-xxx 格式的 Coding Plan Key。
  • API Key 由脚本自动获取，Agent 不应直接处理密钥值；禁止硬编码密钥、从 CLI 输出提取密钥、在任何输出中暴露密钥、从配置文件读取或打印密钥。任务完成前必须运行 grep -rn "sk-" <output_directory>/ 自检所有输出文件，若发现以 sk- 开头的字符串（sk-xxx 占位符除外），删除受影响文件并重新生成。
  • 从多个知识库检索时，需合并结果并去重；按分数排序，优先高相关内容。
  • API Key 自动获取流程：读取 ~/.aliyun/config.json 当前 profile 的 dashscope.api_key → 找到则返回；读取环境变量 DASHSCOPE_API_KEY → 找到则返回；阿里云 CLI 可用 → 通过 generate_api_key() 自动创建并保存到配置；以上均失败 → 报错并给出配置说明。