RAG-KB · 企业内部知识库问答系统产品系统

中小团队的内部知识大多散落在共享盘、邮件附件和群文件里：制度、产品手册、报价规则、项目纪要各存一份，找个条款靠文件名搜索再问一遍老同事，新人培训基本靠口口相传。直接把资料丢给通用大模型提问，看似省事，但它会补出不存在的规定、给不出口径一致的出处，答案没法进正式流程；而文档一更新，靠微调或人工维护 FAQ 的方式又跟不上。企业侧还有一笔算不清的账：谁在用、答得对不对、每天消耗多少 token，没有记录也没有上限，试用到一半常常因为成本和「不敢信」停掉。

本项目把目标收敛成一个可验证的边界：单客户、单实例、单知识库的内部资料问答工具，一个实例服务一个团队，所有登录用户共享同一份资料，明确不做多租户 SaaS。选 RAG 而不是微调，是因为内部知识更新频繁、重训成本高，且检索到的原文可以直接作为答案出处。为了把「有出处」从提示词要求变成代码约束，系统做了引用编号校验、按格式定位（PDF 页码、DOCX 章节与表格行、PPTX 幻灯片、XLSX 单元格区域）和回源查看原文，证据不足时由拒答闸直接拒答、不调用大模型；成本侧用模型分级、语义缓存、每日硬闸门和单用户配额兜住。

两点边界先说明：文档解析、向量化、检索与存储全部在本机完成，但答案生成仍需调用云端大模型，因此它不是「数据绝不出内网」的完全离线方案；这是个人独立开发的自建 MVP 与作品集原型，语料为内置教程文档和一套明确标注虚构的演示语料，没有真实客户，也未上线生产。

单实例私有部署，含原生 JS 聊天页与管理后台，模块如下：

1. 文档接入：md/txt/pdf/docx/pptx/xlsx 六种格式；后台异步上传、CLI 增量追加、全量重建、覆盖与删除。
2. 解析与切分：PDF 页码、DOCX 章节/表格行、PPTX 幻灯片、XLSX 单元格区域；表格重复表头；文本按中文分隔符切为父子块（1500/500/50），小块检索、大块生成。
3. 混合检索：Chroma 向量 + BM25（jieba）各召回 20 条 → RRF 融合（k=60）→ bge-reranker-v2-m3 精排取 Top-4；支持来源过滤、父子块回扩。
4. 问答编排：chain（LCEL）/ graph（LangGraph 换词重试）/ agent（ReAct 调 9 工具）三种模式，统一 SSE 流式与过程事件。
5. 生成前决策：追问由小模型改写为独立问题；闲聊路由跳过检索；证据不足时拒答闸不调大模型；可选 HyDE / Multi-Query / Self-RAG。
6. 引用溯源：答案标 [1][2] 并校验越界与缺失，前端展示「文件 + 定位标签 + 原文片段」；Word 不伪造页码。
7. 用户与权限：账号角色、PBKDF2 哈希、三类凭证、审计日志，会话消息落 SQLite（11 表）。
8. 成本治理：按模型记 token 与成本、每日硬闸门、单用户配额、滑动窗口限流、三级语义缓存、数据看板。
9. 运维：启动拒绝默认密钥、动态配置（敏感项加密只回掩码）、一键重建（原子切换 + 失败回滚）、指标与日志、备份恢复。
10. 评测与工程化：78 题评测集跑 Hit@k / MRR / LLM-as-judge / 引用违规率，34 个测试文件挂 CI，Swagger、Docker 部署、26 章文档。

本人独立完成需求、架构、前后端、文档与部署，约 2 万行 Python、53 个接口、34 个测试文件。

技术栈：Python 3.11 / FastAPI / LangChain（LCEL）+ LangGraph / Chroma / FastEmbed（bge 向量 + reranker 重排）/ BM25 / SQLite / Docker Compose；LLM 由 build_llm(role) 工厂切换 DeepSeek、智谱 GLM、百炼通义，按角色分级。

架构分五层，Store 封装全部 SQL、get_retriever() 是唯一向量库耦合点；检索调用从 LCEL 链前移到 ask()，让生成前决策可见可测。

设计取舍：
1. RRF 按排名融合而非分数加权，因向量距离与 BM25 分数量纲不可比；父子块扩展放在重排之后，避免长文本拉低交叉编码器精度。
2. 引用做成闭环：拒答话术抽成单一常量与判定器同源，校验剔除代码块、越界与缺失分开统计；回源按定位重读源文件而非切分后 chunk。
3. 重建写新集合后以 os.replace 原子切换生效指针再删旧集合——容器卷挂载点无法 rmtree，失败时旧索引继续服务。
4. 语义缓存实测「块太大/块太小」相似度 0.958 与同义改写重叠，故直返阈值收到 0.99、灰区交小模型判等价。
5. 拒答闸证据不足 fail-closed、自身异常 fail-open；危险工具审批超时按拒绝；厂商 Key 加密存储且只回掩码。

评测：78 题集 Hit@4 约 89.7%、MRR 约 0.78；CI 不注入 API key。

边界：自建 MVP / 作品集原型，无真实客户与上线部署；工具网关与 SSO 为预研 Mock 骨架且默认关闭；单实例、无多租户、无 OCR、无本地 LLM。