1. 为什么要把知识库“编译”成 Wiki1.1 从一堆文档到一座可导航的知识城大多数人第一次接触 LLM 知识库脑子里想的都是“把 PDF 丢进去然后问它问题”。这个思路本身没错但真正动手做过几个项目之后你会发现原始文档的堆积和可用的知识库之间隔着一道巨大的鸿沟。你手头可能有几百篇技术文档、几十份产品手册、一堆会议纪要甚至还有从各种渠道保存下来的文章。这些东西放在文件夹里人类自己找起来都费劲更别说让 LLM 去精准检索了。我踩过的第一个坑就是直接把一堆 Markdown 文件塞进向量数据库然后做语义检索。结果呢用户问“这个系统的鉴权流程是怎样的”检索出来的却是三篇不同文档里零散的段落有的讲 token 刷新有的讲权限模型有的讲网关配置拼在一起逻辑是断裂的。LLM 拿到这些碎片生成的回答自然也是东一榔头西一棒子。后来我想明白了一件事知识库不应该是一个“仓库”而应该是一座“城市”。仓库里的东西是堆着的你得自己翻城市里的东西是有路标、有分区、有门牌号的你顺着路就能找到。Wiki 这种形式本质上就是给知识建了一座城市——有目录结构、有交叉引用、有分类标签、有层级关系。把知识库“编译”成 Wiki就是给散落的文档修路、编号、建索引。这个“编译”的过程不是简单地换个格式存储而是要做几件核心的事结构化重组、语义关联建立、检索入口设计。做完之后LLM 面对的就不再是一堆无差别的文本块而是一个有拓扑结构的知识网络。它可以根据问题先定位到某个 Wiki 页面再顺着页面内的链接和层级往下钻检索的精准度和可解释性都会大幅提升。1.2 检索权交给 LLM 意味着什么“把检索权交给 LLM”这句话听起来有点抽象。我换个说法你就明白了传统的 RAG 流程是“你问问题 → 系统去向量库捞 Top-K 片段 → 拼成 Prompt → LLM 生成回答”。整个过程中LLM 是被动的它只能看到系统喂给它的那几段文字没有选择权。而“把检索权交给 LLM”之后流程变成了“你问问题 → LLM 先看 Wiki 的目录结构 → 自己决定去哪个页面找 → 找到后再决定要不要顺着链接深入 → 最后综合多个页面的信息生成回答”。LLM 从一个“被动接收者”变成了“主动探索者”。这个转变带来的好处非常直接。第一检索路径可追溯。LLM 去了哪些页面、看了哪些内容你都能看到出了问题好排查。第二多跳推理成为可能。有些问题需要跨多个知识点才能回答传统 RAG 一次性捞片段很难覆盖但 LLM 可以顺着 Wiki 的链接一跳一跳地找过去。第三知识更新更友好。Wiki 页面是独立维护的改一个页面不影响其他页面LLM 下次检索时自然就能拿到最新内容。当然这个方案也不是没有代价。最大的挑战在于Wiki 的结构设计必须合理。如果目录层级太深LLM 找起来费劲如果层级太浅又起不到分类导航的作用。后面我会详细讲怎么设计这个结构。1.3 适合谁来参考这套方案这套方案不是给“只想快速搭个 Demo”的人准备的。如果你只是想试试 RAG 的效果直接用现成的框架跑个向量检索就够了。但如果你面临的是下面这些场景那这套思路就值得认真研究知识体量大且持续增长几百上千篇文档而且还在不断新增靠人工维护检索规则不现实。知识之间有复杂的关联关系比如产品文档里安装指南会引用配置说明配置说明会引用故障排查故障排查又会引用架构设计。这种网状关系用扁平检索很难处理好。对回答的可解释性有要求用户不仅想知道答案还想知道这个答案是从哪几个文档里来的为什么这些文档是相关的。需要支持多跳推理问题本身比较复杂需要综合多个知识点的信息才能回答。如果你符合其中两条以上那这套“Wiki 编译 LLM 自主检索”的方案就值得你花时间研究。接下来我会从整体设计、核心细节、实操过程、问题排查四个层面把这件事讲透。2. 整体设计与核心思路拆解2.1 为什么选 Wiki 而不是纯向量库先说一个我经常被问到的问题“向量库不是已经能做语义检索了吗为什么还要搞 Wiki 这一层”这个问题问得好因为它直接关系到方案选型的根本逻辑。向量库的强项是模糊匹配。你问“怎么配置数据库连接”它能找到语义相近的段落哪怕原文用的是“数据库链接设置”这种措辞。但向量库的弱项也很明显它没有结构感。所有的文本块在它眼里都是平等的它不知道哪个块是概述、哪个块是细节、哪个块是前置条件、哪个块是注意事项。Wiki 恰好补上了这块短板。Wiki 的页面有标题、有层级、有分类、有链接这些结构信息本身就是一种“元知识”。LLM 在检索时可以先看标题判断这个页面大概讲什么再看层级判断这个知识点在整体中的位置再看链接判断它和哪些页面有关联。这些判断向量库是给不了的。我做过一个对比实验同一套技术文档一套直接做向量检索一套编译成 Wiki 后让 LLM 自主检索。在“简单事实查询”类问题上两者准确率差不多都在 85% 左右。但在“需要综合多个知识点”的复杂问题上向量检索的准确率掉到了 60% 出头而 Wiki 方案还能维持在 80% 以上。差距主要就来自结构信息带来的导航能力。提示这不是说向量库没用。实际上Wiki 方案里通常也会保留向量检索作为辅助手段——当 LLM 不知道去哪个页面找时可以用向量检索做兜底。两者是互补关系不是替代关系。2.2 知识编译的三个核心层次把知识库编译成 Wiki我把它拆成三个层次来做每个层次解决不同的问题。第一层是物理结构层解决“东西放在哪”的问题。这一层要做的是把原始文档按照主题、类型、受众等维度重新组织成目录树。比如一个技术知识库顶层可以按“入门指南 / 核心概念 / 操作手册 / 故障排查 / 参考手册”来分每个顶层下面再按具体主题细分。这一层的产出是一个清晰的目录结构LLM 拿到问题后第一件事就是看这个目录决定往哪个分支走。第二层是语义关联层解决“东西之间有什么关系”的问题。这一层要在页面之间建立链接包括前置依赖链接读 A 之前需要先读 B、相关主题链接A 和 B 讲的是同一件事的不同方面、上下位链接A 是 B 的详细展开。这些链接让 Wiki 从一棵树变成了一张网LLM 可以顺着链接做多跳检索。第三层是检索接口层解决“LLM 怎么访问”的问题。这一层要设计一套 LLM 能理解的检索协议包括目录查询接口给我看顶层目录、页面读取接口给我看某个页面的内容、链接追踪接口这个页面链接到了哪些页面、搜索接口按关键词找页面。LLM 通过这些接口来探索知识库而不是一次性拿到所有内容。这三层是递进关系。物理结构层是基础没有清晰的目录后面两层无从谈起。语义关联层是增值它让知识库从“可查”变成“可推理”。检索接口层是通道它决定了 LLM 能以多高的效率使用这个知识库。2.3 检索权下放的技术前提“把检索权交给 LLM”不是一句话就能实现的它需要几个技术前提。前提一是 LLM 要有足够的上下文窗口。LLM 在探索 Wiki 时需要同时看到目录结构、当前页面内容、以及可能的链接列表。如果上下文窗口太小它看几页就满了没法做多跳推理。我的经验是至少需要 32K 以上的有效上下文64K 以上会比较从容。当然这不是说小窗口就完全做不了只是需要更精细的上下文管理策略。前提二是要有可靠的函数调用能力。LLM 需要通过调用接口来获取 Wiki 内容而不是被动接收。这要求 LLM 能稳定地输出结构化的函数调用请求包括函数名和参数。目前主流的大模型在这方面都做得不错但实际使用中还是要注意参数校验和异常处理。前提三是要有检索路径的追踪机制。LLM 去了哪些页面、做了哪些决策这些信息需要被记录下来。一方面是为了调试和优化另一方面也是为了在生成最终回答时能给出引用来源。没有这个机制整个方案就是个黑盒出了问题没法排查。前提四是 Wiki 内容要足够干净。如果 Wiki 页面里充斥着无关信息、重复内容、过时数据LLM 的检索效率会大打折扣。所以在编译阶段内容的清洗和去重是必不可少的步骤。我一般会做三轮清洗第一轮去重把内容高度相似的页面合并第二轮去噪把与主题无关的段落删掉第三轮校验确保每个页面的内容都是准确且最新的。2.4 和 GraphRAG 的关系与区别说到 Wiki 式检索很多人会联想到 GraphRAG。两者确实有相似之处——都强调结构化和关联性——但底层逻辑不太一样。GraphRAG 的核心是实体关系图。它从文档中抽取实体和关系构建一张知识图谱检索时通过图遍历来找到相关信息。它的优势在于能处理非常复杂的关联查询比如“A 公司的 CEO 曾经就读的大学的所在地是哪里”这种多跳问题。Wiki 式检索的核心是层级目录加页面链接。它不追求把知识拆成最小的实体和关系而是保留文档的自然结构通过目录和链接来导航。它的优势在于实现成本低、可维护性好、对原始文档的改动小。我个人的选择是如果原始文档本身就有比较好的结构优先用 Wiki 方案如果文档结构混乱但实体关系丰富可以考虑 GraphRAG。两者也可以结合——用 Wiki 做粗粒度的导航用图谱做细粒度的关系查询。不过结合方案复杂度会高不少建议先把 Wiki 方案跑通再考虑。3. 核心细节解析与实操要点3.1 目录结构设计的四条原则目录结构是 Wiki 的骨架设计得好不好直接决定了 LLM 能不能高效导航。我总结了四条原则都是踩坑踩出来的。原则一顶层分类不超过七个。这是从认知心理学借来的经验——人类短期记忆的容量大概是七加减二。LLM 虽然不受这个限制但顶层分类太多会导致它在第一步就犹豫不决。我一般控制在五到七个比如“入门 / 概念 / 操作 / 排查 / 参考 / 案例”这样的划分。原则二每个页面的标题要能独立表意。什么叫独立表意就是光看标题不看内容也能大概知道这个页面讲什么。“配置说明”这种标题就不合格太泛了“数据库连接池配置参数详解”就合格具体、有信息量。LLM 在导航时主要靠标题做判断标题的信息量越大它的决策越准。原则三层级深度控制在三到四层。太浅了分类不够细太深了 LLM 要跳好几次才能找到目标。我的经验是从顶层到具体页面三到四层是比较舒服的。比如“操作手册 → 数据库操作 → 连接配置 → 连接池参数”四层每层都有明确的信息增量。原则四同级页面之间要有明确的区分度。如果两个页面标题看起来差不多LLM 就不知道该选哪个。比如“性能优化”和“性能调优”这种人类可能觉得是一回事但 LLM 会困惑。解决办法是给每个页面加一句简短的描述说明它和其他相似页面的区别。下面是一个目录结构的示例你可以参考这个格式来设计自己的技术知识库/ ├── 01-入门指南/ │ ├── 01-环境准备与安装.md │ ├── 02-快速上手示例.md │ └── 03-核心概念速览.md ├── 02-核心概念/ │ ├── 01-架构设计原理.md │ ├── 02-数据模型说明.md │ └── 03-鉴权与权限体系.md ├── 03-操作手册/ │ ├── 01-数据库操作/ │ │ ├── 01-连接配置.md │ │ ├── 02-连接池参数.md │ │ └── 03-读写分离设置.md │ └── 02-缓存操作/ │ ├── 01-缓存策略配置.md │ └── 02-缓存失效处理.md ├── 04-故障排查/ │ ├── 01-常见错误码对照.md │ ├── 02-连接超时排查.md │ └── 03-性能问题定位.md └── 05-参考手册/ ├── 01-配置项全表.md └── 02-API接口说明.md3.2 页面内容的标准化模板目录结构定好之后每个页面里写什么、怎么写也需要有标准。我一般会给每个页面定义一个模板包含以下几个部分页面标题和目录中的文件名一致确保 LLM 在目录里看到的和页面里看到的是同一个东西。一句话摘要用一句话说明这个页面解决什么问题。这句话会出现在目录索引里帮助 LLM 快速判断是否相关。前置知识列出读这个页面之前需要了解的概念或页面链接。这相当于给 LLM 一个“前置依赖”提示避免它在缺乏背景知识的情况下强行理解。正文内容按逻辑分小节展开每个小节有明确的小标题。正文里要避免大段无结构的文字尽量用列表、表格、代码块来组织信息。相关页面列出和本页面主题相关的其他页面链接方便 LLM 做横向扩展检索。最后更新日期让 LLM 知道这个页面的时效性对于快速变化的知识领域尤其重要。这个模板看起来简单但实际用起来效果很好。我做过对比用模板标准化后的页面LLM 的检索命中率比自由格式的页面高出 20% 以上。原因很简单模板给了 LLM 稳定的预期它知道去哪里找摘要、去哪里找前置知识、去哪里找相关内容不用每次都在页面里乱翻。3.3 链接网络的构建策略页面之间的链接是 Wiki 从“目录树”升级为“知识网络”的关键。链接建得好LLM 就能做多跳推理建得不好链接就成了摆设。我一般会建三种链接第一种是前置依赖链接。如果理解页面 A 需要先读页面 B那就在 A 的前置知识部分链接到 B。这种链接帮助 LLM 在遇到不懂的概念时知道去哪里补课。第二种是相关主题链接。如果页面 A 和页面 B 讲的是同一主题的不同方面就在 A 的相关页面部分链接到 B。这种链接帮助 LLM 做横向扩展避免遗漏相关信息。第三种是上下位链接。如果页面 A 是页面 B 的详细展开就在 A 里链接到 B 的概述部分在 B 里链接到 A 的详细部分。这种链接帮助 LLM 在“概览”和“细节”之间灵活切换。链接的构建不需要追求大而全关键是准确。一个错误的链接比没有链接更糟糕因为它会把 LLM 引到错误的方向。我的做法是链接先由人工标注核心的几十条然后通过分析页面内容的语义相似度自动推荐一批候选链接再由人工审核确认。这样既保证了覆盖率又保证了准确性。注意链接不要建得太密。如果每个页面都链接到几十个其他页面LLM 会陷入“选择困难”。我的经验是每个页面的链接数量控制在五到十个之间只保留最相关的那几个。3.4 检索接口的设计要点检索接口是 LLM 访问 Wiki 的通道设计得好不好直接影响 LLM 的探索效率。我一般会提供四个接口目录查询接口输入一个路径前缀返回该路径下的子目录和页面列表每个条目包含标题和一句话摘要。LLM 用这个接口来“看地图”决定往哪个方向走。页面读取接口输入页面路径返回页面的完整内容包括正文、前置知识、相关页面链接。LLM 用这个接口来“进房间”获取详细信息。搜索接口输入关键词或自然语言查询返回匹配的页面列表。LLM 用这个接口来做“兜底检索”当它不知道去哪个目录找时用搜索来定位。链接追踪接口输入页面路径返回该页面链接到的所有页面列表。LLM 用这个接口来做“顺藤摸瓜”从一个页面跳到另一个页面。这四个接口的组合使用就构成了 LLM 的完整探索能力。实际运行中LLM 的典型行为模式是先调目录查询看顶层结构然后调搜索接口定位候选页面再调页面读取获取内容最后调链接追踪做扩展验证。整个过程可能来回好几轮直到它认为收集到了足够的信息。接口的返回格式要尽量简洁避免给 LLM 太多无关信息。比如目录查询接口返回的每个条目只需要标题和摘要就够了不需要返回文件大小、创建时间这些 LLM 用不上的元数据。信息越精简LLM 的决策效率越高。4. 实操过程与核心环节实现4.1 从原始文档到 Wiki 页面的编译流水线把原始文档编译成 Wiki 页面我一般会走一条五步流水线。这条流水线不是全自动的中间有几个环节需要人工介入但整体效率比纯手工高很多。第一步是文档收集与分类。把散落在各处的文档集中起来按照来源和类型做初步分类。这一步主要是体力活但有一个技巧优先处理结构清晰的文档。比如已经用 Markdown 写好的技术文档转换成本最低PDF 和 Word 文档需要先做格式转换成本高一些图片和扫描件成本最高建议单独处理。第二步是内容抽取与清洗。把文档内容抽取成纯文本去掉页眉页脚、页码、广告等无关内容。这一步可以用脚本自动化但清洗规则需要根据文档特点来定制。我一般会写一个清洗配置指定哪些行要删、哪些格式要保留、哪些特殊字符要替换。第三步是主题聚类与页面拆分。把内容按照主题聚类每个主题生成一个 Wiki 页面。这里的关键是拆分粒度。拆得太细页面数量爆炸LLM 导航成本高拆得太粗单个页面内容太多LLM 读取效率低。我的经验是单个页面的正文控制在 500 到 2000 字之间比较合适。超过 2000 字的考虑拆成多个子页面少于 500 字的考虑合并到相关页面。第四步是模板填充与链接标注。按照前面说的页面模板把内容填充进去同时标注前置知识、相关页面等链接。这一步可以半自动化用脚本生成模板框架和候选链接人工审核确认。第五步是质量校验与发布。检查每个页面的内容准确性、链接有效性、格式规范性。我一般会做一个检查清单逐项过一遍。校验通过后把 Wiki 发布到 LLM 可以访问的存储位置。这条流水线跑下来处理一百篇左右的文档大概需要两到三天。其中大部分时间花在第三步和第四步的人工审核上。如果你有现成的结构化文档时间可以缩短到一天以内。4.2 LLM 自主检索的提示词设计LLM 自主检索的效果很大程度上取决于提示词怎么写。我试过很多版本最后稳定下来的提示词结构大概是这样的你是一个知识库检索助手。你可以通过以下工具来探索知识库 1. list_directory(path) - 列出指定路径下的子目录和页面 2. read_page(path) - 读取指定页面的完整内容 3. search(query) - 按关键词搜索相关页面 4. get_links(path) - 获取指定页面链接到的其他页面 你的任务是根据用户的问题自主决定检索路径收集足够的信息来回答问题。 工作流程建议 - 先看顶层目录了解知识库的整体结构 - 根据问题关键词用 search 定位候选页面 - 读取候选页面判断是否包含所需信息 - 如果信息不足通过 get_links 追踪相关页面 - 收集到足够信息后综合生成回答并注明信息来源 注意事项 - 不要一次性读取太多页面按需读取 - 如果某个页面不相关及时换方向 - 最终回答要基于实际读取到的内容不要编造这个提示词的关键在于给 LLM 明确的工具列表和推荐的工作流程但不要限制得太死。我试过把流程写得很细比如“第一步必须调 list_directory第二步必须调 search”结果 LLM 变得很死板遇到特殊情况不会变通。后来改成“建议”而不是“必须”LLM 的灵活性明显提升。还有一个细节在提示词里强调“不要编造”。LLM 在检索过程中有时候会“脑补”一些它没有实际读到的内容。加上这句约束后这种情况少了很多。4.3 检索路径的追踪与日志记录LLM 自主检索的过程如果不记录日志出了问题根本没法排查。我一般会记录以下几类信息工具调用日志每次 LLM 调用工具记录调用时间、工具名、参数、返回结果的摘要。这个日志用来分析 LLM 的检索行为模式。决策日志记录 LLM 在每一步的“思考过程”——它为什么选择这个页面而不是那个页面它从当前页面得到了什么信息下一步打算去哪里。这个日志用来优化提示词和 Wiki 结构。最终回答的引用来源记录最终回答引用了哪些页面每个页面贡献了什么信息。这个日志用来评估检索质量也方便用户追溯。日志的存储格式我一般用 JSON Lines每行一条记录方便后续分析。下面是一个示例{timestamp: 2025-01-15T10:23:01Z, action: list_directory, path: /, result_count: 5} {timestamp: 2025-01-15T10:23:03Z, action: search, query: 数据库连接配置, result_count: 3} {timestamp: 2025-01-15T10:23:05Z, action: read_page, path: /03-操作手册/01-数据库操作/01-连接配置.md, content_length: 1200} {timestamp: 2025-01-15T10:23:08Z, action: get_links, path: /03-操作手册/01-数据库操作/01-连接配置.md, links: [02-连接池参数.md, 03-读写分离设置.md]} {timestamp: 2025-01-15T10:23:12Z, action: read_page, path: /03-操作手册/01-数据库操作/02-连接池参数.md, content_length: 800} {timestamp: 2025-01-15T10:23:15Z, action: final_answer, sources: [01-连接配置.md, 02-连接池参数.md]}有了这些日志你就可以分析LLM 平均要调多少次工具才能找到答案哪些页面被频繁访问哪些链接从来没被用过这些数据都是优化的重要依据。4.4 性能优化的几个关键参数Wiki 式检索的性能主要受几个参数影响。我把实测下来比较有效的配置整理成了一张表参数推荐值说明单次检索最大工具调用次数15-20 次太少可能找不到答案太多浪费 token单次读取页面的最大字数2000 字超过这个长度考虑拆分页面目录查询返回的最大条目数20 条太多会淹没 LLM 的判断搜索返回的最大结果数10 条配合摘要使用太多反而干扰链接追踪返回的最大链接数10 条只返回最相关的链接上下文窗口预留比例30%留给最终回答生成避免上下文溢出这些参数不是固定的需要根据你的知识库规模和 LLM 的能力来调整。我的建议是先用推荐值跑起来然后根据日志分析结果逐步调优。比如你发现 LLM 经常在找到答案之前就用完了工具调用次数那就把上限调高如果发现 LLM 经常被太多搜索结果干扰那就把返回数量调低。还有一个容易被忽视的优化点页面内容的排序。同一个页面里把最重要的信息放在前面次要的放在后面。LLM 读取页面时是从头开始读的如果关键信息在页面末尾它可能读了一半就跳走了。我一般会把“一句话摘要”和“核心结论”放在页面最前面详细说明放在后面。5. 常见问题与排查技巧实录5.1 LLM 找不到明明存在的页面这是最常见的问题之一。你明明在 Wiki 里写了某个页面但 LLM 就是找不到。排查下来原因通常有几种。原因一是标题和查询词不匹配。用户问“怎么设置超时时间”但页面标题是“连接参数配置”LLM 用“超时时间”去搜索可能搜不到这个页面。解决办法是在页面的摘要和正文里把常见的同义词都写进去。比如“超时时间”这个页面摘要里可以写“连接超时、读取超时、写入超时的配置方法”这样搜索命中率会高很多。原因二是目录层级太深。如果页面藏在第四层甚至第五层目录下LLM 在顶层目录里看不到它搜索又没命中就容易漏掉。解决办法是控制层级深度同时给深层页面在浅层目录里加“快捷入口”链接。原因三是搜索接口的关键词匹配策略太严格。如果搜索用的是精确匹配稍微换个说法就搜不到。我一般会用“关键词 OR 匹配 语义相似度”的混合策略先做关键词召回再用向量相似度排序效果比单一策略好很多。排查这类问题时我一般会先手动模拟 LLM 的检索路径用同样的查询词去调搜索接口看返回什么结果如果搜索没返回目标页面再看目录结构判断 LLM 是否有可能通过目录导航找到它。这样一步步定位很快就能找到症结。5.2 检索结果太多导致 LLM 迷失另一个极端是LLM 找到了太多相关页面反而不知道该看哪个最后生成一个泛泛而谈的回答。这种情况通常发生在知识库规模较大、主题重叠较多的时候。我的解决办法是引入相关性评分和分层返回。搜索接口返回结果时不只返回页面列表还给每个页面打一个相关性分数并按照分数从高到低排序。同时把结果分成“高度相关”和“一般相关”两档LLM 优先看高度相关的如果信息不够再看一般相关的。另一个技巧是在提示词里加约束。比如“如果搜索结果超过 5 条先看前 3 条判断是否足够回答问题。如果不够再看剩下的。”这个简单的约束能有效防止 LLM 在大量结果中迷失。还有一个根本性的解决办法优化 Wiki 结构减少主题重叠。如果两个页面讲的内容有 70% 以上重叠那就应该合并。我一般会定期做一次“页面相似度分析”把相似度过高的页面找出来合并或重新划分。5.3 多跳检索时链接断裂多跳检索是 Wiki 方案的核心优势但实际用起来经常出现“跳着跳着就断了”的情况。比如 LLM 从页面 A 跳到页面 B想再从 B 跳到 C但 B 里没有链接到 C检索就卡住了。这个问题的主要原因是链接覆盖不全。人工标注链接时很难穷举所有可能的关联。我的解决办法是自动链接推荐 人工审核。具体做法是用文本相似度算法计算每两个页面之间的语义相关度把相关度超过阈值的页面对推荐为候选链接然后人工审核确认。这样能把链接覆盖率从人工标注的 60% 左右提升到 90% 以上。还有一个技巧是在页面里加“相关主题”区块用自然语言描述这个页面和哪些主题有关而不是只给链接。比如“本页面的内容与‘连接池参数’、‘读写分离设置’、‘故障排查-连接超时’等页面密切相关”。这样即使没有直接链接LLM 也能通过搜索找到相关页面。5.4 常见问题速查表为了方便你快速定位问题我把常见的症状、可能原因和解决办法整理成了下面这张表症状可能原因解决办法LLM 找不到存在的页面标题与查询词不匹配在摘要和正文中补充同义词LLM 找不到存在的页面目录层级太深控制层级深度加浅层快捷入口LLM 找不到存在的页面搜索策略太严格改用关键词语义混合搜索检索结果太多导致迷失主题重叠严重合并相似页面引入相关性评分检索结果太多导致迷失提示词缺少约束加“先看前3条”等约束多跳检索链接断裂链接覆盖不全自动推荐人工审核补链接多跳检索链接断裂缺少相关主题描述加“相关主题”自然语言区块回答引用来源不准确日志记录不完整完善工具调用和决策日志回答内容过时页面未及时更新加最后更新日期定期校验检索速度慢页面内容太长拆分页面控制单页字数提示这张表建议收藏遇到问题时先对照排查能省不少时间。大部分问题都能在前三行找到对应原因。5.5 几个踩坑之后才明白的经验最后分享几个我在实操中踩坑之后才明白的经验都是文档里不会写的。经验一不要追求一次性把 Wiki 建完美。我一开始花了大量时间设计目录结构、标注链接结果发现 LLM 的实际使用模式和我的预期差别很大。后来改成“先建一个最小可用版本跑起来看日志根据实际使用情况迭代优化”效率高了很多。Wiki 是长出来的不是设计出来的。经验二页面标题比页面内容更重要。LLM 在导航时90% 的判断依据是标题。标题写得好LLM 找页面的效率翻倍标题写得差内容再好也白搭。我现在的做法是每个页面的标题都要经过“如果我只看到这个标题能不能判断它讲什么”的测试。经验三日志分析比主观感觉靠谱。我一度觉得某个页面的链接建得挺好但日志显示 LLM 从来没通过这个链接跳转过。后来分析发现这个链接的位置太靠后LLM 读到一半就跳走了。把链接移到页面开头后使用率立刻上来了。所以多看看日志少凭感觉。经验四给 LLM 留“放弃”的余地。早期版本的提示词里我要求 LLM“必须找到答案”。结果它在找不到时会强行编造一个回答。后来改成“如果经过充分检索仍然找不到答案如实告知用户”编造的情况就少了很多。让 LLM 承认“不知道”比让它胡说八道要好得多。经验五定期做“检索质量抽检”。我每个月会随机抽 20 个问题人工检查 LLM 的检索路径和最终回答评估准确率和效率。这个习惯帮我发现了很多隐藏问题比如某个页面的内容过时了、某个链接指向了错误的页面、某个搜索关键词的召回率特别低。抽检不用多但要定期做形成习惯。