你有没有过这种体验：翻了大半天的团队 Wiki，好不容易找到一篇接口文档，对着代码一看，页面里写的参数名早改了三个版本。反过来，代码里明明用注释和命名讲清楚了核心业务逻辑，但你在 Wiki 里搜破头都搜不到——因为注释是给读代码的人看的，不是给搜索引擎看的。
这种“Wiki 归 Wiki、代码归代码”的状态，我这两年见得太多。更麻烦的是，自从团队开始用 AI 辅助写代码之后，这个缺口反而被放大了：模型能生成看起来很合理的代码，但它并不知道你们组织内部的规范和上下文，因为它没看过你们自己的 Wiki，也没读过你们自己的仓库。于是我就开始琢磨，能不能在本地搭一个“知识助手”，把 Wiki 文档和代码仓库这两套本来各说各话的东西接进同一个系统，让它可以回答“这个接口现在到底该传什么参数”“某个模块在代码里是怎么落地的”这类问题。
下面这篇文章，就是我落地这个本地知识助手的完整思路和实操记录。适合遇到同样问题的开发团队、技术负责人，也适合那些维护个人知识库又长期和代码打交道的独立开发者。我会尽量把“为什么要这么做”和“具体怎么做”都讲清楚，踩过的坑也会一并写出来。
1. 先看看病根：Wiki 和代码脱节，到底坏在哪
想搭建一套解决方案，首先得知道问题真正出在哪里。我知道很多人一上来就急着找工具、跑模型，但如果不把“脱节”这件事拆透，后面的系统大概率也只是做个花架子，解决不了根子上的问题。
1.1 文档漂移：Wiki 里的真相可能只有六成
做开发的人应该都听过“文档漂移”这个词，翻译成大白话就是：文档写出来的那一刻是最准确的，之后就开始慢慢“变质”。代码每天都在变，接口加了一个字段、删了一个参数、换了一种鉴权方式，而 Wiki 文档往往是项目大版本更新时才有人记得去改。我见过不少项目，Wiki 里写的是“订单状态通过 status 字段区分，0 待支付，1 已支付”，但代码里早就换成了 orderState，枚举也不再是数字，而是字符串。结果新人翻文档写得头头是道，一调代码全是不一致。
漂移是怎么产生的？核心原因是文档和代码的生命周期完全不同步。代码有编译器管着，写错了跑不起来；文档没人管，只要写得差不多就能发出去。再加上团队的 KPI 通常不考核“文档准确率”，维护文档这件事就成了一种良心活。时间一长，Wiki 就变成了一座信息折旧率极高的仓库。
更隐蔽的问题是，Wiki 里的信息往往是“结论”，而不是“过程”。它告诉你最终是这样做，但不告诉你代码里为什么要这样设计。你拿着 Wiki 去读代码，遇到一个反直觉的实现，你根本不知道该信文档还是该信代码，最后只能硬着头皮读源码。
1.2 注释和命名：代码里藏着大量“可搜索的沉默”
反过来，代码本身其实是知识密度非常高的载体。变量命名、函数名、注释、提交信息，这些里面承载着大量业务语义。举个例子，一个团队内部的接口文档可能从来没写过“这个模块是为了兼容旧版客户端的推送协议才保留的”，但代码注释里很可能写了一句“DO NOT REMOVE: legacy push protocol for old clients”。
问题在于，这些信息没法被 Wiki 的搜索框检索到。你不可能让 Wiki 去索引 Git 仓库里的每个字符，也不太可能把注释全部手工搬到文档里。于是这些“隐藏在代码里的隐性知识”就成了团队里的暗知识：老员工知道，新员工不知道；写代码的时候能看见，查资料的时候看不见。
我见过最可惜的情况是：一个模块的可维护性其实很好，代码规范、注释齐全，但因为没有文档化，接手的同事硬是靠臆想重写了三遍，最后还是踩了当年已经踩过的坑。这不是成员水平问题，是知识检索通道断了。
1.3 引入 AI 写代码之后，缺口反而更大了
团队开始用 AI 辅助写代码后，问题又变了一个维度。AI 模型非常擅长根据通用编程知识生成代码，但它天然“不知道”你们的私有知识——比如项目的目录约定、特殊的异常处理规范、内部统一的加密方式。
这造成了一个很尴尬的现象：生成式 AI 提高了每个人的编码速度，同时也提高了产生不一致代码的速度。它写的代码从“编译能过、语法规范”的角度看没毛病，但它不知道你们团队规定某些场景必须走统一的基础库，而不是自己再封装一把工具类。
所以我一直在想，如果有一个系统，能把 Wiki 里的“组织记忆”和代码库里的“事实真相”一起喂给模型，让 AI 在回答问题时先查自己家的文档和源码，再给出建议，那这个缺口就补上了。这就是我想做的本地知识助手的核心动机。它的本质不是做一个聊天机器人，而是给团队装一颗会引用自家资料的检索增强大脑。
2. 我建议的解法：本地检索增强知识助手是怎么工作的
在介绍具体方案之前，我得先把这套系统的运行逻辑讲清楚，否则直接给步骤容易变成空中楼阁。简单来说，知识助手做的事情可以分为三块，这也是业界常说的 RAG（检索增强生成）范式。
2.1 为什么优先选本地方案，而不是直接上云端服务
关于“本地”这两个字，可能有人会觉得是自己家里的个人电脑里跑一个东西。其实，我说的“本地”更多是指相对企业公共云端服务而言，部署在你自己可控环境里的方案。它可以是一台办公网内的服务器，也可以是你自己的开发机，关键点是：数据和检索过程不出你的边界。
我选择本地化，主要基于三点考虑。第一是隐私和合规压力，团队 Wiki 里面有不少内部业务描述和未公开的技术设计，直接传到外部服务上，哪怕服务商承诺不拿数据训练模型，我心里也不踏实。第二是可定制性，本地部署我可以随意调整检索引擎、切换模型、改 Prompt，不受外部平台限制。第三是从长远看成本，在活跃度不高的团队里，本地部署一台推理服务器，比按调用量付费的方案省钱得多。
当然，本地方案也不是没有代价，最大的代价就是你得自己伺候基础设施。这篇文章里我会把这块的复杂度尽量降下来，用一套比较省心的组合去搭。
2.2 核心链路拆解：从 Wiki 到向量，再到回答
知识助手的数据流是这样的：首先把 Wiki 页面和代码仓库里的文件都解析成纯文本；然后把文本切分成一个个有限长度的段落，这个动作叫分块；接着用嵌入模型把每一段转成一个向量。向量可以理解成这段文本在多维空间里的坐标，含义相近的文本坐标也相近。
当用户提问时，系统把用户的问题转成向量，然后去向量数据库里找最相近的一批段落。注意，这一步找回来的是候选素材，模型还不能直接照抄。系统会把用户问题、候选段落、一些指令模板拼在一起，送给本地大语言模型，让模型基于这些素材生成有依据的回答，并且在回答里带上引用来源。
这个过程就是典型的 RAG。它和“把全部知识塞进模型参数”的微调路线不同，RAG 不需要重新训练模型，也不需要把 Wiki 内容背进模型脑子里。对于文档持续更新的团队场景，RAG 的实时性和可维护性都更好。Wiki 一改，重新跑一次索引，回答就跟着变了。我个人非常推荐这种方案，因为它把“知识维护”和“模型生成”解耦了。
2.3 技术选型：我用的这套组合是怎么定下来的
确定做本地知识助手之后，最纠结的就是技术选型。我在调研阶段列了三个候选方案，最后定下的组合如下：
- 本地模型推理用 Ollama，模型优先选 Qwen 系列或者 Llama 3 的中小尺寸版本，纯 CPU 机器也能跑，但强烈建议有 GPU。
- 向量存储用 Chroma，轻量级，不需要单独部署服务端，对团队规模不大的场景完全够用。如果数据量大到百万级，可以换 Qdrant 或 Milvus。
- 编排框架用 LlamaIndex 和 LangChain 二选一。我个人更习惯先用 LlamaIndex 做文档链路，因为它对“连接私有数据”这件事封装得更直接。
- 解析工具按照源数据类型灵活组合：Wiki 导出的 HTML 用 BeautifulSoup，Markdown 用常见的解析器，代码文件用 tree-sitter 做结构化切分。
选这套组合的原则有三个：能用最少的代码跑通、组件之间兼容性成熟、出问题时社区资料多。不建议刚开始就上重量级框架，先把链路跑通再说优化。
3. 实操记录：把团队 Wiki 和代码仓库接进知识助手
理论讲完，下面进入动手环节。我会按步骤呈现我实际搭建这套系统时的完整路径，包括每一步我在想什么、为什么这么做。
3.1 第一步：Wiki 导出与解析
Wiki 数据的导出方式和你用的平台强相关。常见的方案是，如果你用的是云文档或者协作平台，一般支持导出为 Markdown、HTML 或者 PDF。我的经验是优先导出 HTML 或者 Markdown，因为 PDF 解析起来很痛苦，表格和代码块很容易错乱。
拿到导出的文件之后，清洗这块非常关键。Wiki 页面里往往有导航菜单、工具栏、版权声明这些无关内容，需要用 BeautifulSoup 按标签把这些区块剔除。我一般会先写一个小脚本，把所有 HTML 文件扫描一遍，提取正文区和标题层级。
清洗之后的文本还面临一个典型问题：同一篇文档里既有表格又有代码又有长篇说明，它们的密度完全不同。如果整篇文本不分块就送进模型，效果会非常差，因为上下文窗口塞不下。所以需要做分块，这部分我在第 4 节里详细展开。
3.2 第二步：代码仓库的索引策略
处理代码文件比处理 Wiki 要谨慎得多。最简单的做法是直接 git clone 整个仓库，然后把所有 .py、.java、.ts、.go 等源码文件路径收集起来。但这样做有几个问题：依赖目录里的第三方库噪音太大，构建产物和缓存文件不该进索引，还有.git的历史提交也不该一股脑全索引。
我的做法是先写一个 ignore 清单，把 node_modules、vendor、build、dist 这些目录全部过滤掉，只保留一级项目源码。在解析阶段，特别注意要保留文件路径信息——比如src/services/order_service.py这个路径本身就是一种知识，模型回答问题时能引用到具体位置，比单纯给一段代码有用得多。
另外，代码文件的索引要把注释保留，但不要把注释单独剥离出去。代码片段和它上面紧挨着的注释必须属于同一个分块，否则解释性上下文就丢了。这是代码类知识库和纯文档类知识库特别不一样的地方。
3.3 第三步：分块、向量化与检索链路
分块这里先给结论，后面详细说：纯文本和代码分块策略都要“宁短勿长”，我通常把块大小控制在 300 到 600 个词之间，块与块之间重叠 50 个词左右，保证上下文连续性。
分块完成之后，选择嵌入模型。负责把文本变向量的模型叫 embedding 模型，常见的本地选择有 BGE 系列和智源的 embedding 模型。它们不需要很强的推理能力，只需要准确编码语义。选模型的时候注意看语言支持，如果团队资料以中文为主，一定要选中文效果好的模型。
向量数据入库之后，检索链路里还有两个小细节值得注意。第一是召回数量，我一般从库里取前 8 到 10 条候选片段；第二是相似度阈值，低于 0.45 的片段基本就是噪音，可以直接丢弃。这个阈值要实际体验后才能调，太低会混入无关内容，太高又会漏答案。
3.4 第四步：接入本地模型完成问答
本地大语言模型的接入相对简单。Ollama 启动之后，通过它的 HTTP API 就能调用本地模型。我建议初始阶段不要贪大，先选自己硬件跑得动的 7B 到 14B 参数模型。硬件条件是 GPU 显存越多越好，13B 量化模型全精度推理大概需要 20GB 以上的显存，8GB 可能只能跑得很吃力。没有独立显卡的话，也可以考虑用大内存机器纯 CPU 推理，但速度会明显慢。
模型接入之后，Prompt 设计是个容易被忽略的环节。你在把检索到的片段拼进 Prompt 时，必须明确告诉模型：请只基于以下参考资料回答，不要自行发挥；如果资料里没有相关内容，直接说明不知道。否则模型会用自己的预训练知识脑补，那就失去“知识助手”的意义了。我在实践中还要求模型在回答末尾列出引用的文件路径或 Wiki 页面标题，这样用户能直接回溯原文核实。
4. 落地过程中最难缠的几个问题
方案看起来简单，真正跑起来之后，我踩了不少坑。挑几个最典型的说一说，希望你能少走弯路。
4.1 分块策略对答案质量的影响有多大
分块我单独拿出来讲，是因为它绝对是最影响回答质量的一个环节。我一开始用的是 1000 个字符的大块，结果模型回答经常七拼八凑，甚至把两段完全不相干的话揉在一起。问题根源在于：一个分块里塞了太多不同主题的信息，向量表示被模糊成了“四不像”，检索时匹配的准确率自然降低。
后来我调整成了语义感知的分块方式：先按 Markdown 标题和代码的顶层函数作为天然分割点，再检查每个块的长度，超了就递归切小。重叠设置成了 50 词。改完之后，检索命中的答案明显更“聚焦”了。这个经验尤其适用于代码：最好按函数、类、方法为最小单元去切，也就是所谓 tree-sitter 能做的事情。把函数签名、函数注释和函数体放在同一个块里，检索到它时模型才能给出既懂语义又懂结构的回答。
4.2 增量同步：知识助手不能二次“落伍”
知识助理最讽刺的风险，是自己变成一份新的过期文档。Wiki 和代码每时每刻都在更新，如果索引不跟着变，那助手回答的内容照样会过时，甚至比 Wiki 更危险，因为模型生成答案的语气太自信了，用户不容易产生怀疑。
我处理增量更新的办法是定时任务加监听钩子。最简单粗暴的方案是每天凌晨跑一次完整的索引，适合数据量小的团队。更高效的做法是钩住代码仓库的 push 事件和 Wiki 的变更事件，只更新变动的文件。对普通团队来说，先做定时全量更新就够了。
这里要特别注意一个问题：文档更新和代码更新经常不同步。比如代码接口改了，Wiki 还没改。助手如果只索引最新代码，回答时给出的答案和旧 Wiki 冲突，反而会引发更多疑问。我的建议是不要在知识助手里做“裁决”，而是把“来源”展示清楚。回答里明确标注这段结论来自代码文件，那段来自 Wiki 页面，谁对谁错让人来判断，比让系统强行合并更安全。
4.3 权限与安全：知识扩散的边界问题
本地知识助手让检索变得太容易了，这是双刃剑。原来一个新人要泡在 Wiki 里翻半天才能凑齐的上下文，现在一条提问就全出来了。但这意味着权限必须提前设计好，否则极易造成敏感信息扩散。
我踩过的坑是：一开始没有做任何权限过滤，任何能访问系统的人都能问出财务模块的实现细节。后来我做了文档级别的元数据过滤，给每个 Wiki 页面和代码目录打上访问级别标签，检索时在向量数据库端先按用户权限过滤候选片段。这个方案需要注意的是，向量检索是在语义空间完成的，必须在召回前就过滤，否则敏感片段已经被捞出来了，召回后才拦截意义就不大了。
4.4 调整问答质量的具体手法
如果搭建完发现回答质量不行，先不要急着换大模型。绝大多数问题出在检索而不是生成环节。我自己调优的顺序是这样的：首先怀疑分块大小，其次检查召回阈值，再次看 Prompt 是否给足了约束条件，最后才考虑换更强的模型。
还有一个很实用的小技巧，叫做“查询改写”。用户提问有时候很口语化，比如“那个订单状态的字段叫什么来着”，直接拿这个去向量检索效果一般。可以先让本地小模型把用户问题改写成适合检索的关键词集合，比如“订单状态字段定义”，再用改写结果去库里检索。这个小改动不需要额外硬件，就能显著提升命中率。我试下来，检索 Top1 的相关性提升非常明显。
另外一个问题是多个大段的参考资料顺序。模型对资料顺序是有偏好的，通常放在越靠前的资料越容易被引用。我的做法是把相关度高的候选片段放在前面，把边缘信息放后面，配合 Prompt 里强调“优先采用靠前的资料”，能让答案的逻辑更清晰。
5. 从工具到团队基础设施的最后一公里
系统跑通只是开始，真正的价值在于让它融入团队的日常研发流程。这里分享几个推进方向和我的个人体会。
我后来做的第一件事，是让知识助手具备“自动关联”能力。不是只回答问题，而是当 Wiki 里某篇文档被创建或更新时，助手去代码库里找相关的接口实现，自动生成一段“关联代码位置”的附录，附在文档结尾。这样文档维护者能第一时间发现代码和文档是否同步。
第二件事是把它接到代码评审场景里。让模型在审查代码变更时，自动去 Wiki 里查和这段代码对应的设计文档，然后把“这份变更是否偏离了当初的设计”作为评审意见输出。哪怕只做到“把相关设计文档找出来贴在 MR 里”，也能大大减少评审者翻文档的时间。
我个人的体会是，搭建这个系统的过程，本质上是在帮团队把“组织记忆”沉淀成一种可被检索、可被对话、可被验证的基础设施。知识助手不是来替代人做判断的，它的真正价值是帮人把判断所需要的信息在几秒钟内找齐。
当初我做完最小版本，第一次问它“支付回调接口现在的签名算法是什么”，它答完带了源码路径，我顺着路径点过去，看到代码真的和它说的一样时。那一刻我确信，把 Wiki 和代码接进同一套系统，这条路是通的。
所以如果你也正在被文档和代码互相矛盾的问题困扰，别急着再写一份“最终版”文档了。花一两天时间，先搭一个最小化的本地知识助手，让它可以回答几个你和团队天天都在问的问题，然后顺着使用中暴露出来的问题慢慢迭代。相信我，这一步走通之后，你会开始重新审视手里每一份文档的价值。
