我手上有三堆东西: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.py | create_app()、create_mcp_server() |
| 业务规则 | kb/service.py | add_document()、search()、ask()、_table_answer() |
| 融合 | kb/retriever.py | weighted_fuse(),注释里写了 N32/N33 两次修正 |
| 项目子库 | kb/scopes.py | get()、locate(),count.txt 那段 |
| 三套存储 | kb/storage.py、kb/bm25.py、kb/links.py | — |
| 表格解析与问答 | kb/tables.py | parse_table_file()、query_rows() |
| 检索评测 | kb/eval.py | compute_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,可商用。
- GitHub:github.com/fish827-08/…
- Gitee:gitee.com/little-fish…
- PyPI:pypi.org/project/kb-…
一个人维护,star 和 issue 都是实打实的反馈,尤其 issue——装不上、跑不通的地方,比一句「写得不错」有用得多。
最后想问个可能有点争议的问题:你们有没有遇到过那种明明该用精确匹配,却被硬塞进向量检索的场景?还是说我这判断本身就想多了,现在的 embedding 已经够用?评论区聊聊,我挺想知道别人怎么处理的。