RAG Assistant

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

⚠️ 从 1.x 升级到 2.x 必须重建 HNSW 索引

2.x 将向量搜索引擎从 ChromaDB 内置 HNSW 替换为独立 hnswlib 索引，以解决 ChromaDB Rust 后端在 Windows 上的 HNSW 持久化 bug。

升级后首次搜索会自动触发懒重建（每个 KB 约 1-2 分钟），也可手动点击 🔨 HNSW 按钮，或通过 POST /api/kb/rebuild-hnsw API 触发。

• 重建不可跳过：ChromaDB HNSW 和 hnswlib 索引格式不兼容
• 旧索引自动清理：重建后 ChromaDB 的 HNSW 段文件会自动废弃
• 数据不丢失：文档文本和 metadata 全部保留，仅重新计算向量索引

基于 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

更新说明

[2.1.0b1] - 2026-07-23

重大新增 — 插件系统

RAG Assistant 引入标准化插件系统，支持信息补充类（input_return）和外部输出类（input_output）两种插件类型。智能体完全掌握决策权，插件为纯执行者，不做判断不主动触发。

新增

• 插件框架：rag_assistant/plugins/base.py — PluginBase 抽象基类，定义 execute() 和 open_config_ui() 接口
• 插件管理器：rag_assistant/plugins/manager.py — 插件发现/注册/生命周期/配置持久化/超时熔断/文件沙箱/输出校验
• 内置联网搜索插件：rag_assistant/plugins/builtin/web_search/ — 首个内置插件，支持 DuckDuckGo/Tavily/Google/Bing/自定义 五种后端，含 Tkinter 配置界面。前 3 个搜索结果自动抓取页面正文（content 字段优先，snippet 兜底，不足 100 字自动 urllib 抓取），Tavily 的 content 字段正确映射
• 插件 Web UI 管理面板：Web 界面新增"🔌 插件"Tab，支持查看/启用/禁用/配置插件，刷新按钮重新扫描
• 插件引用标注：LLM 回答中引用插件信息时标注 [插件名称]（如 [联网搜索]），与知识库 [n] 编号引用共存
• SM3 签名工具：tools/sign_plugin.py + tools/verify_plugin.py，对插件代码文件和 plugin.json 计算 SM3 国密哈希（已修复 plugin.json 自引用问题，签名时自动排除 sm3_hash 字段）
• SM3 校验修复：manager.py 的 _compute_hash() 在读取 plugin.json 时先去除 sm3_hash 字段，与签名工具计算方式一致

插件系统设计要点

• 标准化接口：6字段池（question/answer_draft/thinking/rag_context/session_id/plugin_dir）→ 插件按需声明 → 智能体裁剪传递
• 标准化返回：{type, content, priority, execution_error}，支持 markdown/json/csv/plain_text
• mandatory 机制：mandatory=true 时智能体必须调用（适合输出类插件），false 时智能体自主判断（搜索类）
• 错误分级：无 execution_error → 只报"xxx调用失败"；有 execution_error → 报"xxx调用失败：原因"
• 5 道安全防线：信息隔离（只给声明字段）→ 文件沙箱（仅 data/plugins//）→ 超时熔断（连续 3 次失败自动禁用）→ 输出校验（schema 非法丢弃）→ SM3 签名（可选）
• 最小入侵：不修改 agent.py 决策循环/动作解析/RAG 检索核心，只在 chat() 返回链路插入 2 个钩子点（before_response + after_response）

修复

• 联网搜索字段映射错误：Tavily 返回 content（全文）而非 snippet，插件 execute() 改为优先取 content，其次 snippet，不足 100 字自动抓取页面

变更

• Agent 启动流程：插件管理器从延迟加载（首次 chat() 时）改为 Agent.__init__() 立即初始化，确保 Web UI 在首次对话前即可展示插件列表
• 配置页移除旧搜索 UI：原 LLM 配置卡片的"联网搜索"checkbox 和搜索后端配置已移除（由插件系统接管），移除对应 3 个 JS 函数和 3 个 Python 模板变量