RAG Assistant

本地知识库问答智能体 — LLM 驱动的组合式语义检索与多库路由。 版本：1.7.0 | 作者：wUwproject | 许可证：Apache 2.0

基于 local-rag-builder 技能构建的独立 RAG 智能体，支持 LM Studio / Ollama 双后端。

快速开始

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

# 2. 启动（需要 LM Studio 或 Ollama 运行中）
python main.py

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

# 同时启动外部 API（可选）
python main.py --api-port 8767

核心特性

文件结构

rag-assistant/
├── main.py                           # 入口（CLI/Web/Batch/External API 四模式）
├── setup.bat                         # Windows 一键启动
├── requirements.txt                  # 依赖清单
├── CHANGELOG.md                      # 版本更新日志
│
├── rag_assistant/                    # 智能体核心
│   ├── agent.py                      # LLM 决策循环
│   ├── web_ui.py                     # Web 界面（port 8765）
│   ├── external_api.py               # 外部接入 API（port 8767）← 新增
│   ├── llm_client.py                 # LLM 统一客户端（LM Studio / Ollama）
│   ├── rag_wrapper.py                # 技能封装层
│   ├── search.py                     # 联网搜索（5 种后端）
│   ├── memory.py                     # 三层记忆系统
│   └── _fix_rag.py                   # 破损数据修复工具
│
├── engine/                           # 技能引擎（独立副本）
│   ├── rag_core.py                   # 检索/路由/rerank/NLI 编排
│   ├── router.py                     # 两级路由 + KB 签名生成
│   ├── reranker.py                   # 重排序（model/rule/hybrid）
│   ├── nli_classifier.py             # NLI 三向分类器
│   ├── knowledge_base_manager.py     # KB CRUD + 备份/恢复/移动
│   ├── text_splitter.py              # 5 种切分策略 + 5 种守卫
│   ├── prompt_manager.py             # 提示词管理（模板/插槽/预设）
│   └── ...
│
├── vendor/                           # 内嵌第三方库（bs4/pypdf/markdownify）
└── data/                             # 运行时数据
    ├── config/rag_config.json        # 全量配置
    ├── kb/                           # ChromaDB 知识库
    ├── models/                       # 嵌入/reranker/NLI 模型
    ├── sessions/                     # 会话历史
    ├── memory/                       # 压缩摘要/知识缺口/习惯
    └── prompts/                      # 自定义模板/预设

启动模式

python main.py                              # Web UI（port 8765）
python main.py --api-port 8767              # Web UI + 外部 API
python main.py --no-web --api-port 8767     # 仅外部 API
python main.py --no-web                     # CLI 交互模式
python main.py --batch --input q.json --output r.json   # 批量处理
cat queries.jsonl | python main.py --jsonl              # 管道模式
python main.py migrate                      # 从 local-rag-builder 迁移

架构概览

用户输入
  → [LLM 决策层]
       ├─ 闲聊 → 直接回答
       └─ 知识库查询 → entities/attrs 分词
           → [组合展开器] 穷举 entities × attrs
           → [多切片检索] 每片独立走完整 RAG 流程
              1. 路由（嵌入模型 × KB签名/关键词）
              2. 检索（Chroma 相似度）
              3. (可选) 重排序（reranker）
              4. (可选) NLI 三向分类（entailment/neutral/contradiction）
           → [SM3 去重合并]（保留 NLI 标签）
           → [LLM 综合回答]（带 NLI 标签辅助判断）

文档导航

三端口架构

技术栈

• LLM 后端：LM Studio（OpenAI 兼容） / Ollama
• 向量存储：ChromaDB（langchain-chroma）
• 嵌入模型：BCE-embedding-base_v1（本地加载）
• Reranker：BAAI/bge-reranker-base（本地加载）
• NLI 分类：MoritzLaurer/mDeBERTa-v3-base-mnli-xnli（本地加载）
• 文本切分：5 种策略 + GuardStack 守卫栈
• 哈希去重：SM3 国密哈希

依赖

• LM Studio 或 Ollama（本地 LLM 推理服务）
• Python 3.9+
• 嵌入模型（推荐 maidalun1020/bce-embedding-base_v1）
• ChromaDB（向量存储，自动安装）

协议

Apache 2.0

更新说明

[1.7.0] - 2026-07-21

新增

• 外部接入 API（port 8767）：rag_assistant/external_api.py 独立服务，6 个能力域 27 个 REST 端点，与 Web UI 完全隔离
• 功能开关运行态切换：POST /api/feature/toggle + GET /api/feature/status，运行态切换 router/reranker/nli/web_search/auto_classify/geek_mode，持久化到 config.json，免重启
• 模型直接调用：POST /api/model/embed 嵌入、/api/model/rerank 重排序、/api/model/nli 三向分类，绕过完整 RAG 流程独立调模型
• KB 管理 API：POST /api/kb/create / /delete / /move + GET /api/kb/list / /sources / /backups + POST /api/kb/backup / /restore
• KB 签名管理：GET /api/kb/signatures + POST /api/kb/signature/build + POST /api/kb/signature/rebuild-all
• 提示词管理 API：模板读写/重置（/api/prompt/template）、插槽读写（/api/prompt/slots）、预设 CRUD+应用（/api/prompt/presets / preset / preset/delete / preset/apply）、系统前缀（/api/prompt/system-prefix）
• 输入管理 API：文本切分（POST /api/input/split，透传 5 种切分策略 + 5 种守卫）、问题组合切片展开（POST /api/input/query-slices，entities×attrs 穷举）、策略列表（GET /api/input/strategies）
• CLI 参数：--api-port 指定端口启动外部 API（默认不启动，兼容旧用法）

修复

• llms.txt 全面过时：版本从 v0.1.0→v1.7.0，修复自修正重试次数（2→5）、压缩阈值（40行→token-based）、API端点数（13→30+）、路由模型角色混淆、文件名引用错误等全部过时信息
• PROTOCOL.md 版本滞后：v0.1→v1.0，补充外部 API 交叉引用
• rag-assistant-architecture.md 多处过时：版本 v0.9.0→v1.7.0b1→v1.7.0，修复 RAG_PROTOCOL.md→PROTOCOL.md 文件名错误、端点列表从 16 个补全到 32 个、新增 5.2b 外部 API 节、压缩阈值描述修正（行数→token比例）、搜索引擎列表从 2 种补全到 5 种

变更

• 版本从 1.7.0b1 升级为 1.7.0（正式版，去掉 beta 标记）
• README.md 全面更新：文件结构对齐当前架构、新增外部 API 说明、新增协议文档导航
• main.py +--api-port 参数，daemon 线程启动外部 API

重大变更

• KB 签名生成机制重构：四分法采样后 4 象限各算独立质心 → 各取近 20 个 chunk → 各象限独立 jieba + 停用词 + BCE 排序 → 四段拼接（每象限前 20 直接拼），签名上限 12→80 词。router.py build_kb_signature() 重写
• 多向量路由：kb_signatures.json 新增 signatures 字段存储各象限签名，route_query() 区分多向量（逐个 cosine 取最高分）与单向量（fallback），数据驱动不再硬编码
• 反哺策略改为四象限均分：(30 - count(originals)) // 4 每象限配额，取代全局 top-30 竞争，router.py:343-377

新增

• 签名重建控制：config.py 新增 signature_auto_rebuild: False 配置项，knowledge_base_manager.py:658-667 入库时根据开关决定全量/增量更新
• Web UI 签名管理：KB 签名区新增"入库全量重建"开关 toggle，KB 列表每行新增"重建签名"按钮，JS 添加 rebuildOneSig() + toggleAutoRebuild() API
• 单 KB 重建 API：rag_web_ui.py 新增 POST /api/router/rebuild-one 和 POST /api/router/toggle-auto-rebuild
• 查询类型参考修复：web_ui.py 补上 setTimeout(loadQueryTypes, 500) 页面初始化调用，4 个内置类型正常显示
• 停用词扩展：router.py:167 新增 接上、转下页、上一页、下一页、上页、下页、翻页、第几页 8 个 PDF 分页残留词

修复

• _originals 持久化缺陷：_save_rules() 入口自动补齐 _originals（knowledge_base_manager.py:72-77），不再依赖反哺阶段的条件保存
• rag_core.py 死代码：删除第 505-513 行引用不存在的 update_kb_signature 的多余代码
• update_kb_signature 缺失导入：rag_web_ui.py:23 补上 build_kb_signature 导入
• 签名预览截断：Web UI 签名行显示从 [:80] → [:120]，鼠标悬停看全文
• 签名重建无反馈：按钮重建过程禁用 + loading 态，完成后立即执行 location.reload()
• 查询切片缺失 entity 单独层：agent.py 补上 _slices.add(e)，对齐三层策略
• 多实体 rel 切片缺失宽匹配：agent.py 多实体时同时生成 e1 e2 rel 和 e1 e2 attr rel 两种
• 空 evidence 值绕过校验：agent.py:510 增加 not v.strip() 检查，空值不再因 Python 的 "" in src 特性放行
• LLM entities 拆碎修饰域：system prompt 第 184 行加"不要将修饰域拆为独立 entity"，第 185 行 attrs 允许复合短语，第 190 行加"凝缩而非泛化"规则

变更

• 路由截断 [:200] → [:512]（适配长签名）
• 清理死常量 SIGNATURE_MAX_WORDS = 12
• 保留 idf: dict = None 参数兼容（TF-IDF 恢复待后续）

重大变更

• 多会话管理：替换"重置对话"为"新建会话"，侧边栏列出所有历史会话，支持切换/归档/恢复。agent.py 新增 new_session()、list_sessions()、archive_session()、delete_session()、_generate_session_id()
• 压缩阈值改为 token 比例：删除硬编码 100 行阈值，改为 max_tokens × compress_ratio（默认 4096×0.7=2867 token）。memory.py 新增 estimate_token_count()，可配置压缩触发比例和移出比例

新增

• 聊天侧边栏：左栏 260px 宽，列出所有会话（含最近消息预览）。每个会话右侧 📦 归档按钮，归档会话灰显，点击 ↩ 可恢复。底部显示归档数量展开按钮
• 会话归档系统：归档将会话文件移入 data/archives/sessions/，压缩记忆移入 data/archives/memory/，不删除数据。max_sessions 配置（默认 20）控制非活跃会话上限，超出自动归档最旧的
• 配置折叠：配置 tab 的 LLM/记忆/搜索卡片可点击 ▾ 折叠，状态存入 localStorage
• memory.compress_ratio/compress_remove_ratio/max_sessions 配置：在 8765 配置行中与 LLM 设置同排显示，支持实时修改
• KaTeX 字体文件：复制 60 个字体文件到 static/fonts/ + NOTICE.md 许可证声明
• PCR/CT值 路由到生物医疗：auto_classify_rules.json 中生物医疗 _originals 新增 PCR、聚合酶链式反应、CT值、核酸、基因检测等 10 个关键词

修复

• Tab 切换 8766 泄漏：消除 .tab-content.active { display: block } 与 #chat-content.active { display: flex } 的 CSS 冲突，改 JS 直接设置 style.display（block/none/flex），不再依赖 CSS class 控制显隐。CSS 中 #config-content.tab-content { display: block } 只作默认值，JS inline style 优先级更高，切换时绝对覆盖
• web_ui.py 重建：因 git checkout 误操作丢弃未提交改动，据 CHANGELOG + agent.py/memory.py API 重构 web_ui.py。侧边栏/会话管理/配置折叠/压缩比例全部恢复
• 双滚动条：chat-messages 与 chat-content 高度溢出导致 body 额外滚动，#chat-panel 加 overflow: hidden + flex 子项最小高度 0 修复
• kb-status / llm-config Null 报错：删除 status-bar 后残留 JS 引用加 null 守卫
• Enter 键未绑定：从 addEventListener（注册时机问题）改为 textarea onkeydown 内联属性
• setup.bat 杀不掉旧进程：netstat|find|tokens=5 因 Windows 版本列偏移失效。改为 PowerShell Get-CimInstance Win32_Process 按命令行查杀 + Get-NetTCPConnection 按端口兜底
• MiniCPM 语义判断方向错误：原为 value 在 sources 中搜索，改为 key vs value 语义一致性判断

变更

• agent.py 所有 Memory 方法从固定 "default" session_id 改为动态生成
• 配置 tab 从原水平带状改为两张独立卡片（LLM + 记忆），统一 grid 布局 + border-radius:10px
• 删除 status-bar（kb-status、llm-config、压缩/清除/重置按钮）
• memory.py 删除 COMPRESS_THRESHOLD、COMPRESS_REMOVE 硬编码，新增 COMPRESS_REMOVE_RATIO
• pop_oldest_lines() 参数从 n=int 改为 ratio=float

移除

• 重置对话按钮、清除上下文按钮（由新建会话 + 归档替代）
• status-bar 相关元素及 JS 引用