LLM wiki 对比 RAG：实测用 wiki 替代检索反而更慢

把 LLM wiki 当成 RAG 的另一种做法，是一个常见误解。Vellum Labs 用一个真实代码库做了对照实验，结论有些反直觉：在小型代码库上，wiki 作为检索替代品比不检索更慢、更贵，正确答案数量却一样。

三个概念，别混为一谈

RAG（检索增强生成） 在提问时用检索器找出文档库里最相关的片段，塞进 prompt，模型基于这些片段作答。文档库是源文件的副本，切碎后原地不动，下一次提问仍从同一个库开始，不会有任何写回。

Agentic retrieval（代理式检索） 是当下编程代理实际采用的变体：没有嵌入索引，代理反复执行 grep、打开文件、阅读，直到能回答为止。检索器就是带 shell 工具的模型本身。实测中"不用 wiki"的一侧指的就是这种模式，作者没有跑向量数据库版本的 RAG。

LLM wiki 则是一个由代理自己写入和维护的 markdown 文件夹：每个概念、决策或模块一页，每条论断都标注来源（file:line、changelog 版本或带日期的对话），用 [[wikilinks]] 互相引用，并附带一个代理最先读取的索引。源文件放在旁边保持不变。当页面无法回答问题时，代理会去读源文件，并把学到的东西写回页面，让下一个问题不必再读源文件。

一句话概括区别：RAG 检索已被写下的内容，wiki 还记录下被决定的事情。 其余差异都是这条前提的推论。

Agentic retrieval 与向量 RAG 的取舍：向量 RAG 依赖嵌入索引与相似度排序，适合语料规模大、查询语义模糊的场景，但索引本身需要构建与维护，且切片边界会丢失跨文件上下文。代理式检索（grep、打开文件、逐层阅读）不建索引，靠模型自己决定读什么、何时停，优势是语义准确、引用可追溯，代价是每问一次都要重新遍历文件，成本随问题数线性累加。在小型代码库上，文件少、跳转浅，代理式检索的遍历成本很低，反而比维护索引更划算；而当仓库达到数十万行时，代理可能读几十个文件才能收敛，单题成本迅速上升，此时预建索引或 wiki 的摊销价值才显现。理解这一点，才能理解文中为何在 1,176 行规模上"不用 wiki"能赢。

实验设置与结果

测试对象是 http://pallets/itsdangerous——Flask session 底层的签名库，8 个模块共 1,176 行 Python，292 行 CHANGES.rst，7 页文档。使用 Claude Code 2.1.286 默认模型，每次以 claude -p 无头模式在全新会话中运行，成本取自 CLI 的 total_cost_usd。

四个问题是开发者集成该库时真会问的：密钥轮换后旧 token 是否还能验证、salt 参数的真实作用、JWS 支持为何被移除、时间戳在 TimestampSigner 中的编码方式及格式变更时间。

不用 wiki：代理直接读源码

问题	耗时	轮次	成本	正确
密钥轮换	33 秒	6	$0.62	是
salt	28 秒	3	$0.45	是
JWS 移除	28 秒	4	$0.38	是
时间戳格式	35 秒	5	$0.47	是
合计	2 分 4 秒	18	$1.93	4 / 4

每个答案都对照过被引用的文件，四个全对，且引用行确实存在。

构建 wiki

初始化加构建共耗时 7 分 51 秒、花费 $4.23，产出 17 个页面、6,331 词、86 个 [[链接]]（0 断链、0 孤儿页）、110 处 file:line 引用（0 指向不存在的行）。作者提醒：同一提交上的同一提示词，两天前产出的是 21 页、8,441 词、$4.08——构建不是确定性的，若把页面数当质量指标，应运行检查工具而非凭记忆。

[[wikilinks]] 与引用审计：wikilinks 是一种页面间双向链接语法，源自早期 wiki 系统，被 Obsidian、Logseq 等工具沿用。它的价值不只是导航，更在于可校验：如果页面 A 链接到不存在的页面 B，就产生"断链"；如果某页没有任何页面链接进来，就是"孤儿页"。文中提到 17 页、86 个链接、0 断链、0 孤儿页，正是用这些指标衡量 wiki 的结构健康度。与之配套的是 file:line 引用格式，即精确到行号的源文件坐标，使每一条论断都能被程序回归验证——文中特意核对 110 处引用是否指向真实存在的行。这种可机器校验的引用链，是 wiki 相对普通笔记的关键工程属性，也是其查询时不得不回源验证、从而变慢的直接原因。

通过 wiki 回答同样四个问题

问题	耗时	轮次	成本	动作
密钥轮换	57 秒	6	$0.82	页面缺少每密钥验证成本，读源码后写回两个页面
salt	66 秒	6	$0.64	从 wiki 作答，对照文档和源码确认
JWS 移除	25 秒	5	$0.50	从决策页作答，无需改动
时间戳格式	43 秒	6	$0.63	从决策页作答，无需改动
合计	3 分 11 秒	23	$2.59	4 / 4 正确
写回后重问第 1 题	28 秒	5	$0.59	从 wiki 作答，无改动

数字说明了什么

在 1,200 行的代码库上，wiki 是一个比不用 RAG 更差的 RAG。第一轮每题慢 55%、贵 34%。即便写回之后，重复提问的成本与冷读源码基本持平（28 秒 vs 33 秒，$0.59 vs $0.62），因为查询命令回答前仍要对照源文件验证引用。检索节省的开销永远无法回本 $4.23 的构建成本。就这个库的规模而言，不存在盈亏平衡点。

作者诚实指出两个未测量的反向因素：1,200 行时整库能塞进上下文窗口，而在 20 万行、50 个文件的大仓上，"直接读源码"的单题成本会增长而 wiki 不会，交叉点应该存在但位置未知；此外无头运行没人等结果，而 wiki 答案因带有决策页的框架而更易读。

为什么小仓没有盈亏平衡点：wiki 的成本结构是"一次性构建 + 每次查询仍要验证"，而直接读源码是"每次查询纯遍历"。设构建成本为 C，单题验证开销为 v，单题冷读开销为 r，只有当 v 明显小于 r、且问题数量足够多，累计节省 (r−v)×n 才可能覆盖 C。本实验中 v 与 r 几乎相等（$0.59 vs $0.62），差距被引用验证吃掉，于是 (r−v)≈0，无论问多少次都回不了本。只有当仓库大到 r 随问题规模显著膨胀、而 wiki 页面能稳定提供答案并减少回源时，v 才会被压低，交叉点才出现。作者标注"交叉点位置未知"，正是因为 r 的增长曲线取决于仓库结构与提问分布，无法从单一实验外推。

第五个问题：wiki 是唯一选项

真正的分水岭在一个代码评审后出现的决策上——这个决策不在 src/、不在 CHANGES.rst、不在任何文档里。作者模拟团队在评审中决定：应用密钥列表最多保留三把，每 30 天丢弃最旧的一把，因为 wiki 显示被拒 token 每把密钥需一次 MAC。他们否决了无界列表和单密钥硬切换两个方案。

一侧	耗时	成本	回答
不用 wiki	53 秒	$0.51	"源文件无法回答前两部分"，正确解释了库把密钥数量和节奏留给调用方
capture	34 秒	$0.57	决策页新增政策、两个被否决方案、成本推理，还写出一条作者未明说的推论：max_age 应保持在 60 天以内
wiki 查询	22 秒	$0.47	三把密钥、每 30 天丢弃、原因、两个被否决方案、60 天推论，全部有引用

这不是性能差异，而是能回答与无法回答之间的差异。RAG 和代理式检索只能检索有人写下来的东西，而评审决策没人会写下来，除非工具把它变成一行命令。

什么时候用哪个

用 RAG 或普通代理式检索： 答案在源文件里且源文件稳定（API 文档、库自身代码、规范）；语料大且以读为主，索引胜过反复阅读；没人需要改变知识，只需找到它。

用 LLM wiki： 知识一部分在源文件、一部分在人脑、评审、事故和聊天记录里；你在多个会话中反复问代理同一个项目，希望第二次从第一次结束的地方开始；你需要审计链，每条论断有引用，每次变更进 log.md，一切入 git。

两者都用： 语料大时，wiki 管决策与综合，检索管原材料。wiki 的 raw/ 目录正是 RAG 会索引的文档库，两者不争夺源文件。

不要把 wiki 当检索缓存。 上面的实测就是理由：如果只想要更快的答案，wiki 会额外带来构建成本和验证成本，却换不回原本没有的东西。

几个意料之外的发现

查询命令的时间花在验证环节。 四个 wiki 答案中有三个写了"对照 CHANGES.rst 验证"或"对照 signer.py 确认"，即便页面已有答案。对一个以引用为卖点的工具，这是正确行为，也是它在小仓上永远比读源码贵的原因。想要速度，需要一个信任页面的命令，并且你得知道自己要的是这个。

capture 在"易变"与"固定"之间选了前者。 工具允许代理决定是把对话关键行复制进 raw/conversations/ 还是仅摘要。同一决策两天前选了固定，这次选了摘要并标注"来自对话，已摘要（无转录）"。作者随后把它定为规则（模板 1.0.4）：命名了被否决方案、记录了反转、或被要求"固定此条"的 capture 一律固定。此条命名了两个被否决方案，按现行规则应固定，但作者尚未重跑。

同一提示词、同一提交，今天 17 页明天 21 页。 构建是一次采样，不是一个定值。

如何复现

整个循环除插件安装外就是三条命令加一个循环：克隆仓库后，分别以无头模式运行"不用 wiki"提问、初始化并构建 wiki、再通过 /llm-wiki:query 提问，成本由 CLI 报告，耗时用 date 包裹调用测量。

关键提示：每个问题都要在全新会话中运行（不要用 --continue），否则第二个问题会继承第一个问题的阅读结果，让后跑的那一侧数字更好看。若打算引用页面数，构建请跑两次。

所用模板和插件为 MIT 许可，托管在 http://github.com/vellumlabs/llm-wiki-kit。

无头模式与会话隔离：claude -p 是 Claude Code 的无头（headless）调用方式，即不进入交互式终端，直接传入提示并返回结果，适合脚本化、批量、可测量成本与耗时的场景。文中特别强调每个问题都要在全新会话中运行、不要使用 --continue，原因在于会话延续会保留此前读过的文件内容与推理上下文，等于给后跑的一侧"预加载"了知识，使其耗时和成本被人为压低，从而污染对照实验。此外，成本取自 CLI 报告的 total_cost_usd，耗时用 date 包裹调用测量，这套测量方法的可复现性依赖于模型版本、提示词、仓库提交三者固定。作者提示同一提交两次构建会得到不同页数，因此若要用页面数作为指标，应当重复运行并借助检查工具而非单次结果下结论。