RAG Assistant — 本地知识库问答智能体

基于 LLM 的组合式语义检索与多库路由智能体。连接本地 LLM，对你的文档库做知识问答——自动识别查询意图、拆分组合检索、跨库路由、精排与语义验证，最终给出带来源的答案。

版本：2.2.11 | 作者：wUwproject | 许可证：Apache 2.0

目录

• 一、它是什么
• 二、环境要求与依赖
• 三、搭建步骤
• 四、使用流程总览
• 五、启动模式
• 六、三端口架构
• 七、知识库管理
• 八、查询流程详解
• 九、功能开关与配置
• 十、联网搜索
• 十一、记忆系统
• 十二、提示词管理
• 十三、插件系统
• 十四、外部 API（系统集成）
• 十五、常见问题
• 协议

一、它是什么

RAG Assistant 是一个完全本地运行的知识库问答智能体。你导入文档、建立知识库，然后像聊天一样提问，它会：

1. 由 LLM 判断意图：闲聊直接答，知识问题进入检索
2. 对问题做 实体/属性拆解，穷举组合生成多个检索切片，逐片独立检索
3. 按内容自动路由到最合适的知识库，相似度检索后用重排序器精排、NLI 语义验证过滤矛盾内容
4. 合并去重后，由 LLM 综合回答，标注来源

核心设计理念：组合式查询（不遗漏任何检索角度）+ 确定性校验（不捏造不矛盾）+ 多库路由（知识分散也能找对）。

二、环境要求与依赖

模型下载

嵌入 / 重排序 / NLI 三类模型在需要时自动下载，内置多源探测：

系统会自动探测可用源并选择最快的。断网环境下需提前手动放置模型文件到 data/models/。

模型推荐：嵌入 BAAI/bge-small-zh-v1.5（中文友好）、重排序 BAAI/bge-reranker-base、NLI MoritzLaurer/mDeBERTa-v3-base-mnli-xnli。NLI 与重排序模型较大，如果只做基础检索可以不启用（见「功能开关」）。

兼容性说明

• 1.x → 2.x 升级必须重建索引：2.x 将向量存储从 ChromaDB 内置 HNSW 换成独立 hnswlib（修复 Windows 持久化 bug）。升级后首次搜索自动懒重建（每个库约 1-2 分钟），不可跳过，数据不丢失

三、搭建步骤

方式一：Windows 一键启动

1. 确保 LM Studio（或 Ollama）已运行，且已加载一个模型
2. 双击 setup.bat
3. 浏览器访问 http://localhost:8765

方式二：手动启动

# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动（首次启动会自动下载嵌入模型）
python main.py

# 3. 浏览器访问 http://localhost:8765

首次使用配置

四、使用流程总览

创建知识库 → 导入文档 → 自动切分 → 提问
                                      ↓
[LLM 决策层] 闲聊 → 直接回答
             │
             └─ 知识库查询 → 实体/属性拆解
                 → 组合展开（穷举检索角度）
                 → 逐片检索：路由 → 相似度 → (精排) → (NLI 验证)
                 → 去重合并 → LLM 综合回答（带来源）

五、启动模式

通用参数：--port（8765）、--host、--config（配置文件路径）、--data-dir（数据目录）、--pidfile。

六、三端口架构

对外集成只用 8767：第三方系统（如结构化写作智能体）通过 8767 的 /api/kb/query 检索知识库，不接触界面。

七、知识库管理

基本操作

文本切分

导入文档时自动切分，内置 5 种切分策略：

切分前有 5 道守卫（mermaid 图 / 代码块 / 数学公式 / 表格 / HTML）——先保护这些特殊块不被切坏，切完再还原。带公式、代码、表格的文档选 semantic 或 headers 策略效果最好。

HNSW 索引

• 每个知识库维护独立的 hnswlib 索引
• 索引损坏时自动修复 / 懒重建
• 可在配置页调整 HNSW 参数（M、efConstruction 等）并手动重建

八、查询流程详解

1. 组合式查询（核心）

LLM 先把问题拆成实体（entities）和属性（attrs），然后穷举组合：

问题："张三在2024年发表的论文里，对比了哪两种模型？"
拆解：entities=[张三, 2024年论文]  attrs=[对比, 模型]
切片：实体单独查 → 实体×属性两两组合 → 实体关系两两配对
→ 每片独立走完整检索流程 → SM3 去重合并 → LLM 综合回答

这样不会漏掉任何检索角度——即使提问方式模糊，组合切片也能覆盖。

2. 多库路由

问题会被自动路由到最合适的知识库，两级策略：

1. 硬编码关键词规则（快速命中，如"股票"→财经库）
2. 嵌入模型 × 库签名 语义回退（对每个库生成语义签名，匹配最相似的）
3. 兜底 default 库

库签名自动归纳：四分采样 → 质心 → 分词 → 嵌入反哺，无需手动维护。

3. 三层推理流水线

NLI 的意义：检索到的片段可能与问题语义矛盾（如"旧政策已废止"）。NLI 把矛盾片段标注出来，LLM 综合回答时不会被误导。

4. 自修正决策

LLM 的动作/格式输出错误时，系统自动反馈重试（最多 5 次）；重试耗尽后清空上下文重来。防止模型捏造检索参数——校验 entities/attrs/证据来源必须来自原文。

九、功能开关与配置

所有开关运行时可切换，无需重启（Web 界面或外部 API 均可）：

查询类型

内置 4 种查询模式：事实（fact）/ 对比（compare）/ 对立（opposition）/ 分析（analysis），可用配置覆盖扩展。不同模式影响检索切片组织方式。

检索参数

极客模式

配置页可切换为 JSON 编辑模式（极客模式）——直接编辑完整配置对象，适合高级用户精细调参；普通用户用表单模式即可。

十、联网搜索

知识库无结果时可选联网补充（总开关 web_search_enabled）。5 种后端：

配置都在 search 配置段。只想要免费体验就用 DuckDuckGo。

十一、记忆系统

Web 界面可手动执行：重置记忆 / 强制压缩 / 注入记忆 / 清空。

十二、提示词管理

十三、插件系统

Web 界面可：查看插件列表 / 开关 / 配置 / 刷新 / AI 生成插件（用描述让 LLM 生成新插件）。

十四、外部 API（系统集成）

8767 端口提供 35 个 REST 端点，面向系统集成（如 Structured Writer）：

完整契约见 EXTERNAL_API.md。

十五、常见问题

Q：首次启动卡在"下载模型"？ A：系统会依次尝试 ModelScope → hf-mirror → HuggingFace 官方。如果都失败（完全断网），需手动下载嵌入模型放入 data/models/。国内网络一般 ModelScope 可用。

Q：检索结果不准 / 答非所问？ A：按顺序排查：① 文档是否切分合理（公式/表格多的用 semantic 或 headers 策略）；② 是否开了重排序（reranker.enabled）；③ 是否开了 NLI（过滤矛盾）；④ top_k 是否太小。

Q：NLI 开关开了但没生效？ A：NLI 需要 mDeBERTa 模型下载完成。模型未就绪时该功能自动降级跳过，检查配置页模型状态。

Q：从 1.x 升级后搜索报错？ A：2.x 需要重建 HNSW 索引。首次搜索自动懒重建，或手动点 🔨 HNSW 按钮 / 调 /api/kb/rebuild-hnsw。不可跳过。

Q：怎么让结构化写作工具用我的知识库？ A：以 --no-web --api-port 8767 启动，然后在 Structured Writer 的配置页填入本程序路径并「冷启动 RAG」即可。

Q：插件总是被禁用？ A：连续 3 次失败会熔断。看插件日志找失败原因（常见：网络不通、API Key 无效），修复后在界面重新启用。

协议

Apache 2.0 © wUwproject

更新说明

[2.3.0] - 2026-08-20

新增（top-N 多 KB 路由 + 死代码清理）

本次更新使用 CodeArts + GLM-5.2 协同完成。

• top-N 多 KB 路由：route_query() 从 top-1（只取最高分 KB）改为 top-N（收集所有过阈值 KB → 按分数降序取前 N 个），激活 retrieve_context 中预留的多 KB 并查循环。跨域问题（如"量子物理与音乐的关系"）不再漏召回次相关 KB。三层防护：UI 限 1-10 → 代码夹 [1,10] → 运行时限实际过阈值 KB 数。默认 top_n=1 保持兼容，单域问题不受影响
• 外部 API POST /api/kb/query 支持 top_n 参数：单次查询临时指定查几个 KB，不改全局配置。调用链 external_api → rag_wrapper → retrieve_context → route_query 4 处签名透传，外部传参优先于配置
• Web UI 出库路由区新增"路由阈值"和"候选KB数"输入框：router.classify_threshold（主路由 KB 分数下限）和 router.top_n（候选 KB 数量上限）可直接在配置页编辑
• config.py router 默认配置新增 classify_threshold: 0.3 和 top_n: 1：原靠代码 .get(..., 默认值) 兜底，现显式写入配置

变更

• 移除"出库最低分"UI 输入框：该字段 router.fallback.min_score_threshold 的消费方 FallbackRouter（reranker.py:360）为 0.5.0 弃用的死代码，UI 入口能改但改了无效果。移除输入框避免误导
• reranker.py FallbackRouter 类加死代码注释：标注 0.5.0 弃用原因（reranker 多语言混合场景得分不稳定甚至全负）、0.7.0 迁入后无调用方、保留供未来参考
• config.py router.fallback 子节点加注释：标注 min_score_threshold 为死配置、signature_auto_rebuild 仍被 knowledge_base_manager.py 读取保留
• bump 2.3.0（不 git-sync，用户指示）