一、为什么写这篇
本地知识库是很多团队的刚需:资料不出内网,检索要快,最好还能用自然语言问答。但这类项目普遍的现象是搭起来快,好用起来慢——性能、召回、上下文、可维护性,每道坎都要踩一遍。
这篇文章把我做一套知识库的完整流程拆成七个步骤,每一步给出判断依据和可复用的结论。数据规模是六百多个词条、七大类八十多个子类,技术栈全程只用 Python 标准库加本地模型,没有数据库、没有 Web 框架、没有向量库。
二、第一步:先量化,再优化
性能工作最容易犯的错误是凭直觉动手。我最初判断检索慢是磁盘 IO 的问题,因为每次检索要读六百多个正文文件。但性能分析工具的结果推翻了这个假设:真正的热点是一个路径解析函数,在循环里被调用了六百多次,单次调用涉及系统级的真实路径解析,累计吃掉了八秒多。
这一步的方法论是三句话。
第一句,让数据说话。用性能分析工具跑一次完整调用,看累计耗时排名前十的函数,而不是猜。
第二句,看调用次数。六百个词条对应六百多次调用,这个数字本身就是线索——说明某个本该只做一次的事被放进了循环。
第三句,盯紧系统调用。路径解析、环境变量查询、配置读取这类操作单次成本不高,但被循环放大几百倍就是灾难。
可复用结论一:循环体里禁止出现无缓存的路径解析、配置读取、环境变量查询。修复后检索从二十九秒降到零点零三秒。这轮定位是用 Ai Py 做的,各个专家组团攻坚,图它省事省力。
三、第二步:分层,标准是能否独立替换
系统分三层。数据层用 JSONL 存词条元数据、Markdown 存正文、numpy 的压缩格式存语义索引;服务层用标准库的线程化 HTTP 服务实现,零第三方依赖;展示层是三个静态页面,没有构建工具。
分层的价值不在于看起来整齐,而在于替换成本。换检索算法,前端不用动;换模型,检索不用动;换存储方式,接口不用动。判断一个分层设计好不好,就看这三条能不能成立。
可复用结论二:每加一层之前先问"未来什么东西最可能换",最可能换的那个东西单独成层。
四、第三步:检索分级加权,剪枝要验证召回
关键词检索的打分按信号强度分级:标题命中五分,标签四分,摘要三分,正文一到两分。这个顺序有依据:标题是作者对主题的明确声明,标签是人工标注,摘要经过提炼,正文范围最大信号最弱。
性能上引入剪枝:标题精确命中时跳过正文扫描。但剪枝有代价,我第一版条件写宽了,"明朝"这个查询返回零条——因为很多书的标题里没有"明朝",正文里却有大量相关内容,全被跳过了。收窄到仅标题命中才剪枝,召回恢复正常。
可复用结论三:剪枝上线前必须准备一组反向测试用例——标题不含关键词但正文相关的条目,验证不误伤。
单路检索要有兜底。关键词搜不到时走语义检索,两路结果用倒数排名融合,兼顾语义相近和字面匹配。
五、第四步:RAG 的瓶颈通常在输入侧
问答效果差的时候,多数人的第一反应是换模型。方向反了。
我遇到的典型案例:问答接口返回"未找到相关内容",但检索明明有结果。排查发现喂给模型的上下文只有标题和摘要,而摘要字段的值是"待人工补充"。模型看到的是三行空元数据,它不是答不好,是根本没材料。
改成读正文后,取前四条、每条截取两千六百字,同样的问题立刻能答出具体数据、章节结构和方法论,还能标注引用来源。
可复用结论四:排查顺序应该是先看上下文里有什么,再看检索是否召回,最后才考虑换模型。八成的"模型不行"其实是"资料没给对"。这个结论是拿 Ai Py 反复对比验证的,您用别的工具同样能验。
六、第五步:本地模型的边界写进代码
本地模型通过 OpenAI 兼容接口调用,地址限定在本机。这个约束不能只写在文档里,要做成代码级白名单:允许的主机只有本机回环地址,配置里出现任何其他地址,请求发出前直接拒绝。
这样即使配置文件被误改,内部资料也出不了本机。对话内容只在内存中,不落盘;检索命中可以记录用于统计,问答过程不留痕。
可复用结论五:涉及数据出域的约束必须是代码级强制,不能依赖配置正确或使用者自觉。
七、第六步:错误要暴露,不要粉饰
原始实现里问答接口把所有异常包住,失败时返回一句"本地模型当前离线"。看起来友好,实际上把真正的错误藏了——有一次模型明明在线,报的是编码错误,用户看到的却是"离线",排查方向完全错。
改成透传真实错误信息后,问题一眼定位。原则很简单:面向开发者的接口暴露完整错误,面向最终用户的界面才做友好包装,两者别混在一起。
八、第七步:写盘异步化
检索命中后要更新统计计数。原始实现每条同步写一次文件,五条结果五次写盘。统计类写操作不影响主流程正确性,却实实在在拖慢响应,改成内存队列加后台线程批量落盘即可。
可复用结论六:日志、计数、统计类写操作,默认都应该异步批量。
九、可复用清单
把上面六步压缩成一份检查清单,下次项目直接对照。
1. 性能优化前先跑分析工具,找出调用次数异常高的函数
2. 路径解析、配置读取提到循环外或加缓存
3. 分层的标准是能否独立替换,最常换的东西单独成层
4. 检索打分按信号强度分级,标题权重最高
5. 剪枝上线前用反向用例验证召回
6. 单路检索要有兜底,两路结果用排名融合
7. RAG 效果差先查上下文,再查召回,最后才换模型
8. 喂给模型的正文长度要权衡,两三千字是可用起点
9. 数据出域约束写成代码级白名单
10. 开发者接口暴露完整错误,用户界面友好包装
11. 统计类写操作异步批量处理
十、小结
这套系统最终形态:六百多个词条,检索零点零三秒,语义检索一秒内,问答半分钟出结果,部署零依赖。整理这些结论和核对数据用的是 Ai Py,图它成本低、省事,您用顺手的工具也一样。
数字会随硬件和数据量变化,但这十一条判断依据可以迁移到下一个项目。方法论的价值不在结论本身,在得出结论的过程。