llm_wiki 项目实战把散落文档变成能对话的知识引擎最近把个人积累了好几年的技术笔记、项目文档、实验记录全部折腾进了一个叫 llm_wiki 的自建知识库系统里。折腾完最大的感受是以前用 Wiki 是“我找知识”现在是“知识找我”——你直接问它“上次那个服务内存泄漏最后是怎么定位的”它能翻遍你写过的所有文档把当时的排查思路、关键命令、最终结论一次性给你列出来还带原文引用。这个项目解决的就是知识管理最常见的痛点东西都有但要用的时候捞不出来。这里把整个项目从设计思路到落地实操完整梳理一遍。无论你是想给团队搭一个私有知识库还是准备把自己的笔记库升级成能问答的智能系统这篇内容应该都能帮你少走不少弯路。说明一下下文涉及的代码和配置都是基于常见实践给出的实现方案不同版本环境的参数差异我会在对应位置标注清楚。1. 为什么做 llm_wiki传统 Wiki 的死穴到底在哪知识库工具用过不少Confluence、Notion、语雀甚至纯 Markdown 文件加 Git 都试过。用久了你会发现一个很尴尬的事实知识库越用越臃肿越用越没人愿意维护。不是工具不好而是传统 Wiki 的底层逻辑决定了它有天花板。1.1 “维护成本”是知识库的第一杀手传统 Wiki 的知识组织依靠“分类 标签 目录层级”。听起来很合理但实际使用中一篇文档该放哪个分类下标签该打几个页面之间怎么建立关联这些动作本身就是在消耗你的精力。更麻烦的是当知识库膨胀到几百个页面之后你根本记不清某个细节到底记在哪一篇里。我用过一段时间 Confluence最大的感受是写文档是件反人性的事。大多数人的工作节奏是“做完了就直接进入下一件事”极少有人愿意花额外的 10 分钟把自己踩过的坑规规矩矩地整理到 Wiki 上。就算当时整理了三个月后你自己回去翻也得先想“我当时记在哪个空间 / 哪个页面下的”。llm_wiki 的思路不一样它不要求你有一级二级三级分类不需要你精心维护页面之间的链接关系。你只要把文档丢进来剩下的事情交给检索和生成。1.2 检索和问答是两种完全不同的体验传统 Wiki 的搜索是基于关键词匹配的。搜“内存泄漏”就要文档里出现“内存泄漏”几个字否则就搜不到。但实际情况是你可能在文档里写的是“GC 频繁导致 CPU 飙升”“heap 使用率异常”之类的描述你和搜索引擎说的根本不是同一个词。llm_wiki 的价值在于把“检索”升级成了“问答”。它把文档向量化之后你问一句“上次服务频繁 Full GC 是怎么解决的”系统会把文档里语义相关的片段捞出来交给大模型整理成直接可用的答案。这就像是给每个知识库配了一个同时熟读所有文档的同事你只需要说明需求不用猜关键词。1.3 这个项目到底适合谁从我的实际使用经验来看有三类人最适合折腾这套东西个人知识管理重度用户积累了大量笔记、文章、技术草稿想要一个能“问”的笔记库小团队内部协作场景SOP、项目文档、故障复盘散落在各处新人问老员工的时间成本太高技术爱好者自己折腾想用一个实战项目把 RAG、向量检索、大模型应用串起来。需要提醒的是llm_wiki 不适合做大而全的企业级知识管理平台。它是轻量的、灵活的工具强项是“快速跑起来 私有化部署 内容完全掌握在自己手里”。2. 整体架构与关键技术选型llm_wiki 的整体设计并不复杂核心就是一条管道把文档拆碎、转成向量、存起来然后在用户提问时把相关内容捞出来送给大模型。这个套路就是现在大家常说的 RAG检索增强生成但具体到工程实现有几个选型值得认真讲讲。2.1 系统架构一条清晰的数据流水线先看整体数据流向理解了它后续所有细节都顺了内容层所有知识源以 Markdown 文件形式存储在本地目录天然支持 Git 版本管理索引层文档被切分成块chunk每块经过向量化模型转成 embedding同时保存一份原文用于后续展示存储层向量数据库保存 embedding 和原始文本元信息同时保留一份倒排索引用于关键词检索检索层用户提问后系统并行执行向量检索和关键词检索合并结果后经重排序选出最相关的片段生成层选中的片段注入 Prompt 模板连同用户问题一起发送给大模型生成最终答案并附上引用来源。这五个层次各司其职哪一层出问题都会直接反映到最终答案质量上。我在调试过程中最大的体会是RAG 系统的问题大多数不是出在大模型而是出在索引层和检索层。这个问题后面专门说。2.2 存储层设计Markdown 文件本身就是数据库llm_wiki 在存储设计上做了一个我认为最关键的决策用户接触到的知识源是纯 Markdown 文件而不是数据库里的记录。这意味着你可以继续使用自己熟悉的编辑器VS Code、Obsidian、Typora写作可以使用 Git 做版本管理可以方便地批量处理、迁移。数据库只是内容的派生品随时可以删掉重建。这种设计带来了一个额外的好处内容永远掌握在自己手里不会被某个平台的私有格式绑架。目录结构大概是这样的llm_wiki/ ├── docs/ # 知识源目录Markdown 文件随便丢 │ ├── 2024-10-网络排查记录.md │ ├── Docker部署踩坑.md │ └── ... ├── src/ # Python 源码 ├── data/ # 向量数据库、缓存文件存放目录 ├── config.yaml # 配置文件 └── requirements.txtdocs 目录就是你的 Wiki用子目录分类可以不用分类平铺也可以。llm_wiki 能自动读取全部 Markdown 文件并且支持监听文件变动、增量更新索引。2.3 Embedding 模型选型中文场景的取舍向量化模型的核心任务是把文本变成一组数字让语义相近的文本在向量空间里距离更近。选型时主要考虑三个维度中文效果、维度大小、运行环境。实测下来有几个方向可以用BGE 系列如 bge-large-zh-v1.5中文效果很能打但模型体积偏大CPU 环境下批量索引会有压力gte 系列如 gte-small-zh体积小、速度快效果和 BGE 略有一点差距但胜在轻量文本嵌入模型 API效果稳定但要走网络请求私有化部署场景不太合适Ollama 内置的嵌入模型如 nomic-embed-text、bge-m3胜在部署省事一条命令就能跑起来适合快速验证。我的建议是先跑通整体流程用 Ollama 里现成的嵌入模型起步。等确认整个链路没问题了再根据自己的实际数据量评估是否换更重的模型。毕竟对个人知识库来说嵌入模型的差距远不如切块策略和检索策略的影响大。2.4 LLM 推理方案本地模型优先llm_wiki 的定位是私有知识库所以默认推荐本地推理方案。我之前用的组合是 Ollama Qwen2.5 系列模型效果和资源占用平衡得不错。如果你的机器配置不高可以换更小的量化版本或者用 7B 模型的 Q4 量化版。本地推理的优势是显而易见的数据不出内网隐私安全有保障没有 API 调用费用不依赖外网连接。代价是首轮推理速度和生成质量跟云端大模型比有差距但用在知识库问答场景完全够用。配置里需要指定两样东西Embedding 模型和对话模型。把它们拆开配置是有讲究的——Embedding 模型只负责“转向量”对话模型只负责“读文本生成答案”两个任务对模型能力的要求完全不同没必要用一个重模型干两件事。3. 核心机制从“文档检索”到“生成答案”的关键细节这部分是 llm_wiki 的灵魂。同样一个知识库检索策略设计得好不好直接决定你是“拿到了可用的答案”还是“得到了一堆废话”。3.1 文档切块策略最容易被低估的环节切块就是把长文档拆成小块文本让每一块都能单独被向量化、检索。听起来很简单但切块的好坏直接影响检索质量。我一开始犯过错误按固定长度切块比如每 500 个字符切一块带 100 字符重叠。结果发现两个问题一个完整的技术方案被拦腰截断语义破碎检索时匹配到的片段经常是一段话开头没头没尾如果文档里还有代码块固定长度切块时经常会从代码中间切开检索时捞出来的是一半代码根本没法用。后来换成了按文档结构切块优先按 Markdown 标题层级H1、H2、H3作为天然边界一个标题下的内容作为一个逻辑块。如果某个标题下的内容还是太长比如超过 800 字再在该区间内按段落边界二次切分并且控制相邻块之间有适当重叠。实现时的大致逻辑是from bs4 import BeautifulSoup import re def split_markdown_by_heading(md_text, max_chunk_size800): # 先用正则把 Markdown 标题的位置和层级找出来 heading_pattern re.compile(r^(#{1,4})\s(.)$, re.MULTILINE) matches list(heading_pattern.finditer(md_text)) sections [] for i, match in enumerate(matches): start match.start() end matches[i 1].start() if i 1 len(matches) else len(md_text) sections.append(md_text[start:end].strip()) # 对超过 max_chunk_size 的 section 按段落边界二次切分 chunks [] for section in sections: if len(section) max_chunk_size: chunks.append(section) else: chunks.extend(split_by_paragraphs(section, max_chunk_size)) return chunks切块的“度”要靠实验来调。块太小检索时缺上下文块太大向量语义被稀释而且后续塞进 Prompt 时浪费 token。个人经验是400 到 800 字符是比较舒服的区间具体还要看你的文档风格。3.2 混合检索向量检索和关键词检索一个都不能少纯向量检索有个天然缺陷它在语义上“模糊”但在精确匹配上“迟钝”。比如你文档里写了一个 API 名称 “llm_wiki.search_embedding”问它时准确拼错了向量检索可能还能凭语义找到但如果你的文档里有一串代码time.sleep(30)、一个具体的报错信息ImportError: No module named xxx这时候关键词精确匹配反而更可靠。所以 llm_wiki 用了混合检索方案向量检索 BM25 关键词检索并行执行各自捞回一批候选结果然后合并去重。BM25 是经典的关键词匹配算法它的核心思路是一个词在文档中出现的次数越多文档越相关但同时这个词在全库中出现得越普遍它对相关性的贡献就越小。比如“部署”这种词到处都有它就不该被赋予过高的权重而“OOMKilled”这种只出现过几次的词一旦出现就应该是强信号。向量检索和 BM25 打分完成后还需要把两类分数归一化到同一个量纲再加权合并。常见做法是用reciprocal rank fusionRRF原理很简单给每个结果按排名分配一个加权分数排名越靠前分数越高这样两类检索结果可以公平竞争。def reciprocal_rank_fusion(vector_results, bm25_results, k60): fused_scores {} for rank, doc_id in enumerate(vector_results): fused_scores[doc_id] fused_scores.get(doc_id, 0) 1 / (k rank 1) for rank, doc_id in enumerate(bm25_results): fused_scores[doc_id] fused_scores.get(doc_id, 0) 1 / (k rank 1) return sorted(fused_scores.items(), keylambda x: x[1], reverseTrue)这个 RRF 公式虽然简单但实际效果出奇地稳定而且不用调权重也不存在“向量分数和关键词分数怎么比”的困扰。强烈推荐直接用。3.3 重排序为什么检索出来的内容还需要再筛一遍经过混合检索捞回的候选块可能还有二三十个但真正相关的可能就三五个。如果直接把全部候选块塞给大模型一方面浪费 token另一方面噪声太多大模型的注意力会被无关信息带偏答案质量反而下降。这时候需要一层重排序rerank来精筛。我用的方案是 bge-reranker 这类专门的重排序模型。它的工作方式和嵌入模型不同嵌入模型是对文本单独编码成向量重排序模型是把问题和一个待选文本拼接在一起训练目标就是直接输出“这个文本和这个问题相关性的分数”。所以在逻辑上重排序的结果应该比向量检索更准。实际跑下来也印证了这一点特别是当问题里有否定词、比较关系、条件限定的时候重排序的优势非常明显。重排序的设置需要注意一个细节耗时比向量检索高一个数量级。所以一般做法是先用向量 BM25 粗筛出 Top 20 到 30 条再交给重排序模型精选出 Top 3 到 5 条。这样既能保证质量又不至于让响应时间太离谱。3.4 Prompt 模板与引用追溯知识库问答和普通聊天有一个本质区别知识库问答要求答案必须“有依据”不能靠大模型编。我在 Prompt 模板里做了三个关键限制只允许基于上下文字段回答超出上下文范围的必须明确说“知识库中没有找到相关信息”每个结论都要标注来源用[来源: 文件名#小节标题]的格式上下文数量限制在 5 块以内避免信息过载。实际验证下来这个模板能明显减少幻觉。特别是第 1 点一开始我没加这个限制的时候模型有 20% 的概率会用自己训练时学到的知识来“补全”答案——尤其在网络技术、编程这类信息高度重叠的领域它编出来的答案甚至看起来比真实文档还流畅但它不是你的记录这就失去了私有知识库的意义。每个候选块在入库时都会记下来源文件的路径和所在的小节标题这样最终答案生成时能自然地带上引用。这一步对知识库使用者非常关键看到答案能直接跳回原文核对细节。4. 部署与配置实操从零跑通 llm_wiki讲完核心机制这部分是动手环节。按下面的顺序来多数环境半小时内能跑起来。4.1 环境准备与依赖安装我的部署环境是 Ubuntu 22.04 Python 3.10显卡是 RTX 3090。如果你只有 CPU也能跑只是索引大文档库时速度慢一些问答体验会受影响。需要先装好的基础组件Python 3.10Ollama用于本地大模型和嵌入模型推理GitPython 依赖主要集中在几个库pip install fastapi uvicorn pip install chromadb # 向量数据库轻量单机首选 pip install rank-bm25 # BM25 关键词检索 pip install sentence-transformers pip install pypdf python-docx # 文档解析用于支持 PDF/Word 导入向量数据库我用的 Chroma主要原因不是它能力最强而是它足够简单数据落盘就是一个本地目录备份、删除、重建都非常容易。如果你后续要支撑几十万的文档规模再考虑换成 Qdrant 或 Milvus 也不迟接口层级是类似的。4.2 项目启动配置项目配置文件config.yaml是最核心的部分关键项如下embedding: provider: ollama model: bge-m3 # 嵌入模型名称 llm: provider: ollama model: qwen2.5:14b # 对话模型 temperature: 0.2 # 知识库问答建议用低温度 max_tokens: 2048 vector_store: persist_dir: ./data/chroma # 向量数据持久化目录 retrieval: chunk_size: 600 # 切块大小 chunk_overlap: 80 # 相邻块重叠 top_k_hybrid: 25 # 混合检索粗筛条数 top_k_rerank: 5 # 重排序后保留条数 watcher: enable: true # 监听 docs 目录变化自动增量索引 interval: 30 # 扫描间隔秒几个参数的具体含义我说明一下temperature设置为 0.2 是刻意为之。知识库问答我们希望答案稳定、忠实于原文而不是像聊天机器人一样自由发挥。温度越低输出的随机性越小。如果设成 0.7 以上同样的提问可能两次得到意思不同、甚至互相矛盾的答案。chunk_overlap设置 80 字符是为了避免两个相邻块之间内容完全断裂。假如一个知识点恰好被切到两块边界处有重叠就能让前后块都保留一部分完整语义。4.3 首次索引与问答测试首次索引会遍历整个 docs 目录把每个文件切块、向量化、写入向量库。对几百篇文档的量级来说在有 GPU 的环境下几分钟就能完成纯 CPU 可能要等十几分钟。python -m llm_wiki.index --config config.yaml python -m llm_wiki.server --port 8080启动后用浏览器打开http://localhost:8080进入问答界面。我建议第一次测试先问一个你自己确定记录过的、带具体细节的问题比如“xx 服务的端口配置在哪个文件里”这样能快速确认整套链路是否通畅。如果你拿到答案之后能从引用链接直接跳转到对应的原文档片段说明链路是通的接下来就可以正式把文档导入进去。5. 常见问题与排查技巧实录下面是实战过程中踩过且比较有代表性的问题整理成速查表方便遇到同类问题时快速定位。现象可能原因排查方式答案和知识库内容明显矛盾检索阶段没召回正确片段打开检索调试模式直接查看送进大模型的上下文是什么明明有相关内容但答不出来切块把语义切碎了检查切块结果手动查看相关文档被切成什么样回答速度太慢检索召回量太大或重排序耗时高降低 top_k_hybrid 和 top_k_rerank同一个问题每次答得不一样温度参数偏高把 temperature 降到 0.2 以下新加的文档问答时找不到增量索引未触发检查 watcher 是否运行或手动执行一次全量索引中文文档检索效果差切块粒度不合适或嵌入模型不适合中文按标题重新切块换用 bge-m3 等中文本地化模型5.1 检索阶段“召回”为空或召回错误这是最影响体验的问题。出现“答非所问”时先不要怀疑大模型90% 的情况是检索没召回对的片段。我调试时的做法是打开检索的 debug 日志直接把系统最终挑选出的候选块原文打出来看一眼。如果召回结果确实不对优先排查三点问法和原文差异太大比如原文写的是“GC”而问的是“内存清理”此时向量检索应该能兜底如果兜不住考虑换更适合中文语义的嵌入模型切块有问题导致包含关键答案的片段被切得七零八落向量化之后语义被稀释了文档格式特殊比如大量表格、代码块纯文本解析会丢信息需要单独处理。5.2 上下文窗口超限大模型对输入长度有上限有时候候选块多、每个块又长拼起来就超了。解决办法有几个方向降低top_k_rerank让最终进入 Prompt 的块更少减小chunk_size让单块更短在 Prompt 模板里对不必要的内容做截断。我个人的经验值最终送入的上下文总量控制在模型窗口的四分之一以内生成质量比较稳定。塞得太满反而会稀释关键信息。5.3 本地模型的内存和显存占用问题Qwen2.5 14B 的 Q4 量化版在加载后大约占 9GB 显存加上嵌入模型和重排序模型总占用会到 10GB 以上。如果你的显卡只有 8GB有两条路可以走对话模型降到 7B 甚至 3B 的量化版牺牲一些生成质量把对话模型和嵌入模型分开部署嵌入和重排序这种轻量任务可以放 CPU只把对话模型放 GPU通过 Ollama 的OLLAMA_HOST环境变量控制不同模型的部署地址。一个细节Ollama 默认会把模型常驻显存如果你的知识库同时有几个人在用堆多个模型进程很容易爆显存。可以在 Ollama 配置里设置OLLAMA_KEEP_ALIVE5m让模型空闲几分钟后自动卸载换资源占用取平衡。5.4 增量更新与索引一致性llm_wiki 支持监听 docs 目录的文件变化。文件修改、新增、删除会对应触发重索引或删除索引。这个机制看起来简单但有一个坑有时候编辑器保存文件会先删后建或者原子替换容易触发误删再加的循环导致索引反复重建刷日志刷得飞起。我的处理方式是监听器不直接响应文件系统事件而是每 30 秒扫描一次目录比对文件的mtime和hash有变化才触发重索引而且每次重索引前加一个短暂延迟避免编辑器连续保存触发多次。def scan_for_changes(self): current self.snapshot_dir() for file_path in current: if file_path not in self.last_indexed or \ current[file_path][mtime] self.last_indexed[file_path][mtime]: self.reindex_file(file_path) for file_path in self.last_indexed: if file_path not in current: self.remove_from_index(file_path)这个“延时扫描比对”的方案虽然不够炫酷但胜在稳定实际用了很久没出过问题。6. 内容体系构建不只是放进去还要更好用工具链跑通之后最大的工作量转移到了内容建设上。llm_wiki 本身只负责索引和问答但它能不能发挥价值完全取决于你往里放了什么。6.1 文档写作的“面向问答”优化用了 llm_wiki 一段时间后我写笔记的习惯发生了变化。以前喜欢写大段大段的描述现在会有意识地多用“结论先行”的写法一段话开头直接抛结论后面再补细节和原因保留关键操作记录比如当时执行了什么命令、出了什么报错、怎么解决的这些具体信息在问答场景下价值极高给重要文档加上清晰的标题层级因为切块是按标题来的标题语义明确切出来的块质量就有保障。这其实是反过来塑造写作习惯的一件事。当你意识到写下的东西将来会被一个“读遍所有文档的助手”调用时你会不自觉地写得更结构化、更完整。6.2 文档质量比数量重要我发现很多做知识库的人有个误区以为文档越多越好。实际上对 RAG 系统来说堆一堆低质量的碎片化笔记不如放几篇结构完整、内容准确的文档。原因在于检索的精度取决于“有效信息密度”。一篇含含糊糊、大量重复、描述前后矛盾的文档即使被召回了也只会让大模型生成出含含糊糊的答案。所以我会定期清理 docs 目录里那些临时记录、过时内容、重复文档。这个维护动作不花多少时间但对最终问答效果的提升非常明显。6.3 团队场景下的权限与多人协作llm_wiki 默认是单用户工具但在团队场景下可以通过简单的机制扩展用 Git 仓库承载 docs 目录团队成员各自 clone、提交目录层面按子目录划分责任区。问答服务只读索引已同步的内容配合定时拉取更新就能实现轻量级的多人知识库。权限方面如果需要做到不同成员只能访问不同目录的内容当前版本的方案是在检索阶段加过滤条件给每个文档块打上标签比如所属团队、目录路径用户提问时根据其角色注入允许访问的路径前缀。这是目前比较通透且改动最小的做法毕竟 llm_wiki 这类工具的初衷是“知识共享”优先重度的细粒度权限管控还是交给企业级平台更合适。最后再分享一点个人体会折腾 llm_wiki 这段时间最大的收获不只是跑通了一个工具而是重新理解了“知识管理”这件事。以前我总想着怎么把知识库整理得尽善尽美——分类严谨、标签齐全、层级分明结果每次都死在半路上。llm_wiki 让我放下了这个执念内容回归到最简单的 Markdown 文件剩下的脏活累活让检索模型和语言模型去干。如果你也打算搭一套我的建议很简单先用最小配置把链路跑通丢几篇自己最常翻的文档进去然后踏踏实实用一周。你会很快感觉到它在哪些场景下真的帮到了你哪些场景下回答还在胡扯。顺着这个反馈去调切块、调检索、调 Prompt比一开始就追求完美架构要高效得多。毕竟知识库这种东西用起来才有价值放着的都是负担。 llm_wiki实战：用RAG把散落文档变成能对话的知识引擎
llm_wiki 项目实战把散落文档变成能对话的知识引擎最近把个人积累了好几年的技术笔记、项目文档、实验记录全部折腾进了一个叫 llm_wiki 的自建知识库系统里。折腾完最大的感受是以前用 Wiki 是“我找知识”现在是“知识找我”——你直接问它“上次那个服务内存泄漏最后是怎么定位的”它能翻遍你写过的所有文档把当时的排查思路、关键命令、最终结论一次性给你列出来还带原文引用。这个项目解决的就是知识管理最常见的痛点东西都有但要用的时候捞不出来。这里把整个项目从设计思路到落地实操完整梳理一遍。无论你是想给团队搭一个私有知识库还是准备把自己的笔记库升级成能问答的智能系统这篇内容应该都能帮你少走不少弯路。说明一下下文涉及的代码和配置都是基于常见实践给出的实现方案不同版本环境的参数差异我会在对应位置标注清楚。1. 为什么做 llm_wiki传统 Wiki 的死穴到底在哪知识库工具用过不少Confluence、Notion、语雀甚至纯 Markdown 文件加 Git 都试过。用久了你会发现一个很尴尬的事实知识库越用越臃肿越用越没人愿意维护。不是工具不好而是传统 Wiki 的底层逻辑决定了它有天花板。1.1 “维护成本”是知识库的第一杀手传统 Wiki 的知识组织依靠“分类 标签 目录层级”。听起来很合理但实际使用中一篇文档该放哪个分类下标签该打几个页面之间怎么建立关联这些动作本身就是在消耗你的精力。更麻烦的是当知识库膨胀到几百个页面之后你根本记不清某个细节到底记在哪一篇里。我用过一段时间 Confluence最大的感受是写文档是件反人性的事。大多数人的工作节奏是“做完了就直接进入下一件事”极少有人愿意花额外的 10 分钟把自己踩过的坑规规矩矩地整理到 Wiki 上。就算当时整理了三个月后你自己回去翻也得先想“我当时记在哪个空间 / 哪个页面下的”。llm_wiki 的思路不一样它不要求你有一级二级三级分类不需要你精心维护页面之间的链接关系。你只要把文档丢进来剩下的事情交给检索和生成。1.2 检索和问答是两种完全不同的体验传统 Wiki 的搜索是基于关键词匹配的。搜“内存泄漏”就要文档里出现“内存泄漏”几个字否则就搜不到。但实际情况是你可能在文档里写的是“GC 频繁导致 CPU 飙升”“heap 使用率异常”之类的描述你和搜索引擎说的根本不是同一个词。llm_wiki 的价值在于把“检索”升级成了“问答”。它把文档向量化之后你问一句“上次服务频繁 Full GC 是怎么解决的”系统会把文档里语义相关的片段捞出来交给大模型整理成直接可用的答案。这就像是给每个知识库配了一个同时熟读所有文档的同事你只需要说明需求不用猜关键词。1.3 这个项目到底适合谁从我的实际使用经验来看有三类人最适合折腾这套东西个人知识管理重度用户积累了大量笔记、文章、技术草稿想要一个能“问”的笔记库小团队内部协作场景SOP、项目文档、故障复盘散落在各处新人问老员工的时间成本太高技术爱好者自己折腾想用一个实战项目把 RAG、向量检索、大模型应用串起来。需要提醒的是llm_wiki 不适合做大而全的企业级知识管理平台。它是轻量的、灵活的工具强项是“快速跑起来 私有化部署 内容完全掌握在自己手里”。2. 整体架构与关键技术选型llm_wiki 的整体设计并不复杂核心就是一条管道把文档拆碎、转成向量、存起来然后在用户提问时把相关内容捞出来送给大模型。这个套路就是现在大家常说的 RAG检索增强生成但具体到工程实现有几个选型值得认真讲讲。2.1 系统架构一条清晰的数据流水线先看整体数据流向理解了它后续所有细节都顺了内容层所有知识源以 Markdown 文件形式存储在本地目录天然支持 Git 版本管理索引层文档被切分成块chunk每块经过向量化模型转成 embedding同时保存一份原文用于后续展示存储层向量数据库保存 embedding 和原始文本元信息同时保留一份倒排索引用于关键词检索检索层用户提问后系统并行执行向量检索和关键词检索合并结果后经重排序选出最相关的片段生成层选中的片段注入 Prompt 模板连同用户问题一起发送给大模型生成最终答案并附上引用来源。这五个层次各司其职哪一层出问题都会直接反映到最终答案质量上。我在调试过程中最大的体会是RAG 系统的问题大多数不是出在大模型而是出在索引层和检索层。这个问题后面专门说。2.2 存储层设计Markdown 文件本身就是数据库llm_wiki 在存储设计上做了一个我认为最关键的决策用户接触到的知识源是纯 Markdown 文件而不是数据库里的记录。这意味着你可以继续使用自己熟悉的编辑器VS Code、Obsidian、Typora写作可以使用 Git 做版本管理可以方便地批量处理、迁移。数据库只是内容的派生品随时可以删掉重建。这种设计带来了一个额外的好处内容永远掌握在自己手里不会被某个平台的私有格式绑架。目录结构大概是这样的llm_wiki/ ├── docs/ # 知识源目录Markdown 文件随便丢 │ ├── 2024-10-网络排查记录.md │ ├── Docker部署踩坑.md │ └── ... ├── src/ # Python 源码 ├── data/ # 向量数据库、缓存文件存放目录 ├── config.yaml # 配置文件 └── requirements.txtdocs 目录就是你的 Wiki用子目录分类可以不用分类平铺也可以。llm_wiki 能自动读取全部 Markdown 文件并且支持监听文件变动、增量更新索引。2.3 Embedding 模型选型中文场景的取舍向量化模型的核心任务是把文本变成一组数字让语义相近的文本在向量空间里距离更近。选型时主要考虑三个维度中文效果、维度大小、运行环境。实测下来有几个方向可以用BGE 系列如 bge-large-zh-v1.5中文效果很能打但模型体积偏大CPU 环境下批量索引会有压力gte 系列如 gte-small-zh体积小、速度快效果和 BGE 略有一点差距但胜在轻量文本嵌入模型 API效果稳定但要走网络请求私有化部署场景不太合适Ollama 内置的嵌入模型如 nomic-embed-text、bge-m3胜在部署省事一条命令就能跑起来适合快速验证。我的建议是先跑通整体流程用 Ollama 里现成的嵌入模型起步。等确认整个链路没问题了再根据自己的实际数据量评估是否换更重的模型。毕竟对个人知识库来说嵌入模型的差距远不如切块策略和检索策略的影响大。2.4 LLM 推理方案本地模型优先llm_wiki 的定位是私有知识库所以默认推荐本地推理方案。我之前用的组合是 Ollama Qwen2.5 系列模型效果和资源占用平衡得不错。如果你的机器配置不高可以换更小的量化版本或者用 7B 模型的 Q4 量化版。本地推理的优势是显而易见的数据不出内网隐私安全有保障没有 API 调用费用不依赖外网连接。代价是首轮推理速度和生成质量跟云端大模型比有差距但用在知识库问答场景完全够用。配置里需要指定两样东西Embedding 模型和对话模型。把它们拆开配置是有讲究的——Embedding 模型只负责“转向量”对话模型只负责“读文本生成答案”两个任务对模型能力的要求完全不同没必要用一个重模型干两件事。3. 核心机制从“文档检索”到“生成答案”的关键细节这部分是 llm_wiki 的灵魂。同样一个知识库检索策略设计得好不好直接决定你是“拿到了可用的答案”还是“得到了一堆废话”。3.1 文档切块策略最容易被低估的环节切块就是把长文档拆成小块文本让每一块都能单独被向量化、检索。听起来很简单但切块的好坏直接影响检索质量。我一开始犯过错误按固定长度切块比如每 500 个字符切一块带 100 字符重叠。结果发现两个问题一个完整的技术方案被拦腰截断语义破碎检索时匹配到的片段经常是一段话开头没头没尾如果文档里还有代码块固定长度切块时经常会从代码中间切开检索时捞出来的是一半代码根本没法用。后来换成了按文档结构切块优先按 Markdown 标题层级H1、H2、H3作为天然边界一个标题下的内容作为一个逻辑块。如果某个标题下的内容还是太长比如超过 800 字再在该区间内按段落边界二次切分并且控制相邻块之间有适当重叠。实现时的大致逻辑是from bs4 import BeautifulSoup import re def split_markdown_by_heading(md_text, max_chunk_size800): # 先用正则把 Markdown 标题的位置和层级找出来 heading_pattern re.compile(r^(#{1,4})\s(.)$, re.MULTILINE) matches list(heading_pattern.finditer(md_text)) sections [] for i, match in enumerate(matches): start match.start() end matches[i 1].start() if i 1 len(matches) else len(md_text) sections.append(md_text[start:end].strip()) # 对超过 max_chunk_size 的 section 按段落边界二次切分 chunks [] for section in sections: if len(section) max_chunk_size: chunks.append(section) else: chunks.extend(split_by_paragraphs(section, max_chunk_size)) return chunks切块的“度”要靠实验来调。块太小检索时缺上下文块太大向量语义被稀释而且后续塞进 Prompt 时浪费 token。个人经验是400 到 800 字符是比较舒服的区间具体还要看你的文档风格。3.2 混合检索向量检索和关键词检索一个都不能少纯向量检索有个天然缺陷它在语义上“模糊”但在精确匹配上“迟钝”。比如你文档里写了一个 API 名称 “llm_wiki.search_embedding”问它时准确拼错了向量检索可能还能凭语义找到但如果你的文档里有一串代码time.sleep(30)、一个具体的报错信息ImportError: No module named xxx这时候关键词精确匹配反而更可靠。所以 llm_wiki 用了混合检索方案向量检索 BM25 关键词检索并行执行各自捞回一批候选结果然后合并去重。BM25 是经典的关键词匹配算法它的核心思路是一个词在文档中出现的次数越多文档越相关但同时这个词在全库中出现得越普遍它对相关性的贡献就越小。比如“部署”这种词到处都有它就不该被赋予过高的权重而“OOMKilled”这种只出现过几次的词一旦出现就应该是强信号。向量检索和 BM25 打分完成后还需要把两类分数归一化到同一个量纲再加权合并。常见做法是用reciprocal rank fusionRRF原理很简单给每个结果按排名分配一个加权分数排名越靠前分数越高这样两类检索结果可以公平竞争。def reciprocal_rank_fusion(vector_results, bm25_results, k60): fused_scores {} for rank, doc_id in enumerate(vector_results): fused_scores[doc_id] fused_scores.get(doc_id, 0) 1 / (k rank 1) for rank, doc_id in enumerate(bm25_results): fused_scores[doc_id] fused_scores.get(doc_id, 0) 1 / (k rank 1) return sorted(fused_scores.items(), keylambda x: x[1], reverseTrue)这个 RRF 公式虽然简单但实际效果出奇地稳定而且不用调权重也不存在“向量分数和关键词分数怎么比”的困扰。强烈推荐直接用。3.3 重排序为什么检索出来的内容还需要再筛一遍经过混合检索捞回的候选块可能还有二三十个但真正相关的可能就三五个。如果直接把全部候选块塞给大模型一方面浪费 token另一方面噪声太多大模型的注意力会被无关信息带偏答案质量反而下降。这时候需要一层重排序rerank来精筛。我用的方案是 bge-reranker 这类专门的重排序模型。它的工作方式和嵌入模型不同嵌入模型是对文本单独编码成向量重排序模型是把问题和一个待选文本拼接在一起训练目标就是直接输出“这个文本和这个问题相关性的分数”。所以在逻辑上重排序的结果应该比向量检索更准。实际跑下来也印证了这一点特别是当问题里有否定词、比较关系、条件限定的时候重排序的优势非常明显。重排序的设置需要注意一个细节耗时比向量检索高一个数量级。所以一般做法是先用向量 BM25 粗筛出 Top 20 到 30 条再交给重排序模型精选出 Top 3 到 5 条。这样既能保证质量又不至于让响应时间太离谱。3.4 Prompt 模板与引用追溯知识库问答和普通聊天有一个本质区别知识库问答要求答案必须“有依据”不能靠大模型编。我在 Prompt 模板里做了三个关键限制只允许基于上下文字段回答超出上下文范围的必须明确说“知识库中没有找到相关信息”每个结论都要标注来源用[来源: 文件名#小节标题]的格式上下文数量限制在 5 块以内避免信息过载。实际验证下来这个模板能明显减少幻觉。特别是第 1 点一开始我没加这个限制的时候模型有 20% 的概率会用自己训练时学到的知识来“补全”答案——尤其在网络技术、编程这类信息高度重叠的领域它编出来的答案甚至看起来比真实文档还流畅但它不是你的记录这就失去了私有知识库的意义。每个候选块在入库时都会记下来源文件的路径和所在的小节标题这样最终答案生成时能自然地带上引用。这一步对知识库使用者非常关键看到答案能直接跳回原文核对细节。4. 部署与配置实操从零跑通 llm_wiki讲完核心机制这部分是动手环节。按下面的顺序来多数环境半小时内能跑起来。4.1 环境准备与依赖安装我的部署环境是 Ubuntu 22.04 Python 3.10显卡是 RTX 3090。如果你只有 CPU也能跑只是索引大文档库时速度慢一些问答体验会受影响。需要先装好的基础组件Python 3.10Ollama用于本地大模型和嵌入模型推理GitPython 依赖主要集中在几个库pip install fastapi uvicorn pip install chromadb # 向量数据库轻量单机首选 pip install rank-bm25 # BM25 关键词检索 pip install sentence-transformers pip install pypdf python-docx # 文档解析用于支持 PDF/Word 导入向量数据库我用的 Chroma主要原因不是它能力最强而是它足够简单数据落盘就是一个本地目录备份、删除、重建都非常容易。如果你后续要支撑几十万的文档规模再考虑换成 Qdrant 或 Milvus 也不迟接口层级是类似的。4.2 项目启动配置项目配置文件config.yaml是最核心的部分关键项如下embedding: provider: ollama model: bge-m3 # 嵌入模型名称 llm: provider: ollama model: qwen2.5:14b # 对话模型 temperature: 0.2 # 知识库问答建议用低温度 max_tokens: 2048 vector_store: persist_dir: ./data/chroma # 向量数据持久化目录 retrieval: chunk_size: 600 # 切块大小 chunk_overlap: 80 # 相邻块重叠 top_k_hybrid: 25 # 混合检索粗筛条数 top_k_rerank: 5 # 重排序后保留条数 watcher: enable: true # 监听 docs 目录变化自动增量索引 interval: 30 # 扫描间隔秒几个参数的具体含义我说明一下temperature设置为 0.2 是刻意为之。知识库问答我们希望答案稳定、忠实于原文而不是像聊天机器人一样自由发挥。温度越低输出的随机性越小。如果设成 0.7 以上同样的提问可能两次得到意思不同、甚至互相矛盾的答案。chunk_overlap设置 80 字符是为了避免两个相邻块之间内容完全断裂。假如一个知识点恰好被切到两块边界处有重叠就能让前后块都保留一部分完整语义。4.3 首次索引与问答测试首次索引会遍历整个 docs 目录把每个文件切块、向量化、写入向量库。对几百篇文档的量级来说在有 GPU 的环境下几分钟就能完成纯 CPU 可能要等十几分钟。python -m llm_wiki.index --config config.yaml python -m llm_wiki.server --port 8080启动后用浏览器打开http://localhost:8080进入问答界面。我建议第一次测试先问一个你自己确定记录过的、带具体细节的问题比如“xx 服务的端口配置在哪个文件里”这样能快速确认整套链路是否通畅。如果你拿到答案之后能从引用链接直接跳转到对应的原文档片段说明链路是通的接下来就可以正式把文档导入进去。5. 常见问题与排查技巧实录下面是实战过程中踩过且比较有代表性的问题整理成速查表方便遇到同类问题时快速定位。现象可能原因排查方式答案和知识库内容明显矛盾检索阶段没召回正确片段打开检索调试模式直接查看送进大模型的上下文是什么明明有相关内容但答不出来切块把语义切碎了检查切块结果手动查看相关文档被切成什么样回答速度太慢检索召回量太大或重排序耗时高降低 top_k_hybrid 和 top_k_rerank同一个问题每次答得不一样温度参数偏高把 temperature 降到 0.2 以下新加的文档问答时找不到增量索引未触发检查 watcher 是否运行或手动执行一次全量索引中文文档检索效果差切块粒度不合适或嵌入模型不适合中文按标题重新切块换用 bge-m3 等中文本地化模型5.1 检索阶段“召回”为空或召回错误这是最影响体验的问题。出现“答非所问”时先不要怀疑大模型90% 的情况是检索没召回对的片段。我调试时的做法是打开检索的 debug 日志直接把系统最终挑选出的候选块原文打出来看一眼。如果召回结果确实不对优先排查三点问法和原文差异太大比如原文写的是“GC”而问的是“内存清理”此时向量检索应该能兜底如果兜不住考虑换更适合中文语义的嵌入模型切块有问题导致包含关键答案的片段被切得七零八落向量化之后语义被稀释了文档格式特殊比如大量表格、代码块纯文本解析会丢信息需要单独处理。5.2 上下文窗口超限大模型对输入长度有上限有时候候选块多、每个块又长拼起来就超了。解决办法有几个方向降低top_k_rerank让最终进入 Prompt 的块更少减小chunk_size让单块更短在 Prompt 模板里对不必要的内容做截断。我个人的经验值最终送入的上下文总量控制在模型窗口的四分之一以内生成质量比较稳定。塞得太满反而会稀释关键信息。5.3 本地模型的内存和显存占用问题Qwen2.5 14B 的 Q4 量化版在加载后大约占 9GB 显存加上嵌入模型和重排序模型总占用会到 10GB 以上。如果你的显卡只有 8GB有两条路可以走对话模型降到 7B 甚至 3B 的量化版牺牲一些生成质量把对话模型和嵌入模型分开部署嵌入和重排序这种轻量任务可以放 CPU只把对话模型放 GPU通过 Ollama 的OLLAMA_HOST环境变量控制不同模型的部署地址。一个细节Ollama 默认会把模型常驻显存如果你的知识库同时有几个人在用堆多个模型进程很容易爆显存。可以在 Ollama 配置里设置OLLAMA_KEEP_ALIVE5m让模型空闲几分钟后自动卸载换资源占用取平衡。5.4 增量更新与索引一致性llm_wiki 支持监听 docs 目录的文件变化。文件修改、新增、删除会对应触发重索引或删除索引。这个机制看起来简单但有一个坑有时候编辑器保存文件会先删后建或者原子替换容易触发误删再加的循环导致索引反复重建刷日志刷得飞起。我的处理方式是监听器不直接响应文件系统事件而是每 30 秒扫描一次目录比对文件的mtime和hash有变化才触发重索引而且每次重索引前加一个短暂延迟避免编辑器连续保存触发多次。def scan_for_changes(self): current self.snapshot_dir() for file_path in current: if file_path not in self.last_indexed or \ current[file_path][mtime] self.last_indexed[file_path][mtime]: self.reindex_file(file_path) for file_path in self.last_indexed: if file_path not in current: self.remove_from_index(file_path)这个“延时扫描比对”的方案虽然不够炫酷但胜在稳定实际用了很久没出过问题。6. 内容体系构建不只是放进去还要更好用工具链跑通之后最大的工作量转移到了内容建设上。llm_wiki 本身只负责索引和问答但它能不能发挥价值完全取决于你往里放了什么。6.1 文档写作的“面向问答”优化用了 llm_wiki 一段时间后我写笔记的习惯发生了变化。以前喜欢写大段大段的描述现在会有意识地多用“结论先行”的写法一段话开头直接抛结论后面再补细节和原因保留关键操作记录比如当时执行了什么命令、出了什么报错、怎么解决的这些具体信息在问答场景下价值极高给重要文档加上清晰的标题层级因为切块是按标题来的标题语义明确切出来的块质量就有保障。这其实是反过来塑造写作习惯的一件事。当你意识到写下的东西将来会被一个“读遍所有文档的助手”调用时你会不自觉地写得更结构化、更完整。6.2 文档质量比数量重要我发现很多做知识库的人有个误区以为文档越多越好。实际上对 RAG 系统来说堆一堆低质量的碎片化笔记不如放几篇结构完整、内容准确的文档。原因在于检索的精度取决于“有效信息密度”。一篇含含糊糊、大量重复、描述前后矛盾的文档即使被召回了也只会让大模型生成出含含糊糊的答案。所以我会定期清理 docs 目录里那些临时记录、过时内容、重复文档。这个维护动作不花多少时间但对最终问答效果的提升非常明显。6.3 团队场景下的权限与多人协作llm_wiki 默认是单用户工具但在团队场景下可以通过简单的机制扩展用 Git 仓库承载 docs 目录团队成员各自 clone、提交目录层面按子目录划分责任区。问答服务只读索引已同步的内容配合定时拉取更新就能实现轻量级的多人知识库。权限方面如果需要做到不同成员只能访问不同目录的内容当前版本的方案是在检索阶段加过滤条件给每个文档块打上标签比如所属团队、目录路径用户提问时根据其角色注入允许访问的路径前缀。这是目前比较通透且改动最小的做法毕竟 llm_wiki 这类工具的初衷是“知识共享”优先重度的细粒度权限管控还是交给企业级平台更合适。最后再分享一点个人体会折腾 llm_wiki 这段时间最大的收获不只是跑通了一个工具而是重新理解了“知识管理”这件事。以前我总想着怎么把知识库整理得尽善尽美——分类严谨、标签齐全、层级分明结果每次都死在半路上。llm_wiki 让我放下了这个执念内容回归到最简单的 Markdown 文件剩下的脏活累活让检索模型和语言模型去干。如果你也打算搭一套我的建议很简单先用最小配置把链路跑通丢几篇自己最常翻的文档进去然后踏踏实实用一周。你会很快感觉到它在哪些场景下真的帮到了你哪些场景下回答还在胡扯。顺着这个反馈去调切块、调检索、调 Prompt比一开始就追求完美架构要高效得多。毕竟知识库这种东西用起来才有价值放着的都是负担。