不引入 LangChain 全家桶,我做了一个本地 RAG 知识库服务

66 阅读12分钟

我手上有三堆东西:3 个 Markdown 写的项目文档、2 个从内部系统导出的网页、还有一张 2 万行的测试用例表。

它们不能传到在线文档,也不适合丢进任何一个 SaaS 知识库。我想要的东西其实很朴素:一个跑在本机、断网也能用的服务,把这几类资料收进同一个库,一句话能查到原文,最好 Claude Code、Cursor 这类工具也能直接调。

RAGFlow、MaxKB、AnythingLLM 完成度都比我高,看过也试过。但它们要么偏重,要么绑着自己的一套 UI 和工作流。我要的只是「能被 Agent 调用的本地检索层」,不是一个知识库产品。想清楚这一点,就自己写了。

这篇写给写过 RAG、被向量检索坑过、又不想为了一个本地检索层引入一整套框架的人。

一、先说清楚我到底要什么

后面所有取舍都是从这四条约束里长出来的,先摊开:

  • 数据不出本机;
  • 一台普通机器就能长期常驻,不挑显卡,不是跑一次 demo 就关;
  • 没配大模型的时候,写入、入库、检索必须完整可用;
  • REST、MCP、CLI 三个入口共用同一份数据,能被别的程序直接调用,不只是一个给人点的界面。

尤其第三条。当时我见到的多数方案,都是把「检索」当成「生成」的前半截,检索本身不做产品化。可我大量时间花在「找一份文档」「查一个单元格」上,这些事根本不需要谁替我组织语言。

二、为什么没上 LangChain 全家桶

先声明:不是框架不好,是我这几条约束跟它的抽象对不上。

第一处别扭在融合。LangChain 的 retriever 把向量检索和关键词检索当成可替换组件,融合常见就是 RRF(= 只按名次算分,不管分数差多少)或者简单加权。但我需要的是「某一路根本没命中时,分母别把它算进去」——这个判断得写在融合函数里,塞进链式调用反而绕。第四节会讲为什么这条这么要命。

第二处是降级路径。没配 LLM 时检索要照常跑;配了 LLM 但连不上,要能退回纯检索;表格问题压根不该碰模型。这些都是业务规则,我更愿意让它们出现在一个能一眼看全的地方,而不是散在链的各个节点里。

第三处是依赖预算。LangChain 本身不大,麻烦的是它带来一整套版本约束,跟 Chroma、transformers 叠在一起,哪天想升级就得一起算账。一台要长期常驻的机器上,我宁可少一层。

最后核心依赖就这些:FastAPI、uvicorn、mcp、ChromaDB、rank_bm25、jieba、sentence-transformers、transformers、httpx、pydantic-settings、typer、rich,外加一个 langchain-text-splitters。

对,还是留了一个 LangChain 家的包。它只做切分,没有别的耦合,为这点功能自己写一套递归切分不值得。所以标题说的是「不引入全家桶」,不是「一行 LangChain 都没有」——这种话我不敢说。

三、模块分层

在这里插入图片描述图 1:五层模块地图。三个协议入口最后都落到同一个 KBService;Web UI 只是 REST 的客户端。 五层,最底下那层是上面四层共用的底座:

入口层   Web UI / REST / MCP / CLI     ← 三个协议入口都落到 KBService
编排层   KBService · ScopeManager · Audit · Governance
检索层   HybridRetriever · Reranker · Sparse · Eval
存储层   ChromaStore · BM25Index · Links · Ingest / Watcher
基础层   Config · Record · Embedder · LLMClient

入口层其实只有三个协议:REST、MCP、CLI,彼此不引用,只做参数校验和协议翻译,最后都掉进同一个 KBService。Web UI 不算第四个协议,它是个 1635 行的单文件静态页,只是 REST 的一个客户端——这点我含糊过一次,被人问了才写清楚。

编排层是唯一知道业务规则的地方:一个文件切成几条记录、走不走表格那条路、什么时候去问 LLM、上下文按多少字截断。旁边几个是配套:ScopeManager 管项目子库和懒加载;Audit 把每次存取记成 JSON,按客户端和项目分文件,内容只记前 50 个字;Governance 放的是衰减和去重的开关,注意是开关,默认全关,开了才会改排序或者拦截写入。KBService 自己还带一把写锁,并发入库时不至于抢 Chroma 的 collection。

检索层不知道业务,只接一个 query 和一个作用域,返回排好序的候选。HybridRetriever 是主路;Reranker 是可选的交叉精排;Sparse 是已经写完的稀疏第三路,用 KB_SPARSE_ENABLED 开,默认关;Eval 离线跑 Recall@1 / Recall@5 和 MRR(= 正确答案排第几名,取倒数再平均),改动前后比一下,看有没有把检索搞坏。

存储层三套东西:Chroma 存向量和原文,BM25 存关键词索引和落盘语料,SQLite 存记忆之间的关联边。没有 Redis、没有 Elasticsearch,也没有单独的向量库进程。Ingest / Watcher 会盯着一个目录,文件变了自动重新入库——改完一个 Markdown 不用手动重传,这个我自己的使用频率最高。

基础层被上面四层共用:Config 读 KB_* 环境变量,Record 是统一数据模型,Embedder 管模型的懒加载和卸载,LLMClient 有 off / local / auto / cloud 四档。

这么分不是为了画图好看。后来我把融合算法从 RRF 换成归一化加权,只动了 retriever.py 里一个函数,API、存储、测试都没改。分层值不值,看这种时候就知道了。

四、检索:两路召回,然后融合

一次混合检索走下来是这样:

query
 ├─ embed_query()               → 向量
 ├─ Chroma.query(vec)           → 向量候选
 ├─ BM25.search(query)          → 关键词候选
 ├─ 相关性下限过滤(余弦 < 0.30 丢掉)
 ├─ 每路 min-max 归一化 → 融合
 ├─ type / tag 过滤
 ├─ (可选) Reranker 精排
 └─ 截断 top_k

候选窗取 max(30, 3*top_k)。要是只取 top_k 个候选,融合之前就可能把相关记录截掉,后面排得再准也救不回来。

向量路有个最低分 0.30。不加这条,一个完全不相关的问题也能靠「这一路只有我一个候选」拿到归一化后的 1.0,看起来特别像命中。

融合是每路先独立 min-max 缩放到 [0,1],再按这条记录实际出现在几路去除,不是按总路数除。原因是一个真实的坑:中文提问查英文笔记,向量路排第一,BM25 路因为没有词面重叠直接缺席;要是统一除以 2,那条 1.0 就被砍成 0.5,被一堆中文文档挤出 top_k。这个过程我写在系列下一篇,等发了把链接补过来。

这个改法有代价,得说清楚:它偏向「单路特别强」的记录,所以必须配 0.30 那个下限,不然噪声也会靠单路混进来。

过滤放在截断之前,否则会出现「明明有匹配,截断完再一过滤就空了」。精排如果开了,同样是在截断之前把候选重新打一遍分。

整条链路没有任何「智能」成分,全是能写进代码的判断。但检索结果的下限就是这些判断决定的。

五、项目隔离:每个项目一套库

一开始我用 metadata 过滤区分项目,踩过两次:过滤条件写错一次就串库;项目一多,单库 BM25 语料越来越大,检索跟着变慢。

后来改成物理隔离,每个项目一套独立的 Chroma、BM25 语料和 SQLite 边库:

kb_data/
├── chroma/                 # 全局库
├── projects/
│   ├── smoke/
│   │   ├── chroma/
│   │   ├── bm25_corpus.json
│   │   └── links.db
│   └── prod/

带 project 检索时,范围是「这个项目子库 + 全局库」,项目里的命中加 0.05 分,并用 min(1.0, ...) 钳住上界;不带 project 就只查全局。代价是磁盘随项目数涨,好处是删目录就是删项目,检索范围也天然收窄。

同时打开的子库有上限(默认 4 个),超了淘汰最久没用的。统计接口不会为了报一个数字把所有库都加载一遍——没打开的直接读 count.txt。

六、常驻成本:懒加载和空闲卸载

默认嵌入模型是 bge-small-zh-v1.5,约 92MB、512 维(= 把一句话变成 512 个数字,机器才能比「意思」)。服务启动时不加载,第一次写入或检索才加载;空闲 600 秒自动卸载。

卸载不止是 del model。我踩过一次:模型对象删了,内存没还给系统。现在会 gc.collect(),Linux 上再调一次 malloc_trim(0)(glibc 默认不把释放的大块内存还给系统),CUDA 上补 empty_cache()。听着都是底层碎活,但在内存吃紧的机器上,它们决定服务能不能连着跑一周。

加载前还会固定 CPU 线程数,按 affinity / cgroup 配额算,最多 4 条。容器里 os.cpu_count() 报的还是宿主机核数,不看配额就按 64 核开线程,自己抢自己。

换模型也不用清库了。v2.5.0 起每个模型在各自作用域里有独立 collection,切换时后台逐条迁移,期间只读:写入返回 409(= 冲突、拒绝写入),读取和关键词检索照常,语义检索临时降级到 BM25;全量同步完才切过去,失败就留着旧库,直接重试。迁移前会先卸载旧模型,免得低配机器上两个模型同时驻留。

七、没有大模型时,它到底能做什么

这一节我最想写清楚,因为「无 LLM」太容易被读成「功能残缺」。

能力没配 LLM配了 LLM
文档 / 表格入库能能
混合检索、来源追溯能能
记忆写入、更新、删除能能
表格单元格精确查询能,确定性匹配能,还是确定性匹配
表格内简单聚合(总分 / 平均)能,确定性算能
跨文档归纳、模糊概念问答不能能

说人话:没 LLM 时能查到准确的东西,有 LLM 时才把东西讲成话。

有个容易混的点:不需要的是大模型,检索还是要嵌入模型的。但表格那条路连嵌入模型都不用——CSV / Excel 逐行变成 列名=值 | ... 的文本,写入时填一个常量单位向量跳过编码,问答直接走确定性匹配。所以「五班张芳的数学成绩」这种问题,在完全没配 LLM、嵌入模型都没加载的情况下也能答。代码里给这些行填的是 1/√维度 的常量单位向量,它跟真实查询的余弦相似度接近 0,会被 0.30 那个下限挡掉,不会混进语义检索的结果里。800 行表格入库从约 24 秒降到约 2 秒,就是这么来的——service.py 的 _embed_for_records() 注释里把这笔账写得挺清楚。

把 kb 挂进 Agent 之后,边界又变了一次:kb 自己不需要大模型,因为 Agent 就是那个大模型。服务只管精确检索,生成交给客户端。MCP 那 13 个工具里,search_memory 比 ask_kb 更值得先用,就是这个道理。

顺带说一句,文档、网页、表格这些入库内容不参与遗忘和衰减。会随时间变淡的只有 type=memory 的记忆。资产和笔记混在一起衰减,是件挺吓人的事。

八、实测

不是 benchmark,就是我机器上的数字(CPU):

  • 那 3 个 Markdown 切出 117 块,入库 10 秒出头(随手记的,没有脚本产出);
  • 2 万行真实业务表(14 列):解析 7.97 秒、入库 31.80 秒,全程嵌入模型 unloaded;
  • 表格问答:问题里带表名时稳态 7.5ms;不带表名、要扫全部 2 万行时约 326ms;
  • 另一组 40 sheet / 5 列的 2 万行表:入库 15.53 秒,1288 行/秒;
  • 全量测试 589 passed / 1 skipped(2026-11-08,约 3 分钟)。跳过那条是 Windows 平台门,不是缺陷。

表格那几组可以用仓库里的 scripts/bench_table_query.py 复现。数字不大,胜在能自己跑一遍。

九、代码从哪看

想看什么文件先看哪个函数
三个入口怎么汇到一起kb/api.py、kb/mcp.py、kb/cli.pycreate_app()、create_mcp_server()
业务规则kb/service.pyadd_document()、search()、ask()、_table_answer()
融合kb/retriever.pyweighted_fuse(),注释里写了 N32/N33 两次修正
项目子库kb/scopes.pyget()、locate(),count.txt 那段
三套存储kb/storage.py、kb/bm25.py、kb/links.py—
表格解析与问答kb/tables.pyparse_table_file()、query_rows()
检索评测kb/eval.pycompute_metrics():Recall@1 / @5、MRR 怎么算

最后

如果也在做本地知识库,我唯一想说的是:先想清楚哪些问题不该用向量检索,再决定要不要上 RAG。

向量检索解决的是「意思相近」,不是「值相等」。「用户 550 的分数是多少」这种问题硬塞给 embedding,多半答不准,然后就开始堆 prompt、加重排、换模型,一路补下去。我在这上面绕过的弯,比在融合上花的时间多。

想跑一下:

pip install "kb-memory[ingest]"
python -m kb serve

打开 http://127.0.0.1:8000/ui 就能拖文件进去。项目是 Apache-2.0,可商用。

一个人维护,star 和 issue 都是实打实的反馈,尤其 issue——装不上、跑不通的地方,比一句「写得不错」有用得多。

最后想问个可能有点争议的问题:你们有没有遇到过那种明明该用精确匹配,却被硬塞进向量检索的场景?还是说我这判断本身就想多了,现在的 embedding 已经够用?评论区聊聊,我挺想知道别人怎么处理的。