团队内部的 Wiki 已经写了三百多篇，覆盖了从技术方案、故障复盘到新人手册的所有内容。但每次有人问起“之前那个服务到底是怎么搭的”，最先回答的往往不是文档本身，而是“你去 Wiki 搜一下”。然后呢？要么搜不到，要么搜出来一长串标题看起来都对、打开又都不对。这个场景我太熟了，知识明明沉淀了下来，却因为散落、割裂、语义不匹配而无法被真正用起来。所以我启动了“RAG 找答案，Wiki 长知识”这个项目：让 Wiki 继续负责知识的生产与沉淀，让 RAG（检索增强生成）负责把人精准地带到答案面前。
这篇文章会围绕整套方案的三个核心问题展开：Wiki 侧怎么设计才能“长知识”，RAG 侧怎么拆解才能“找答案”，以及二者如何通过评估闭环形成正向循环。内容上会从原理、选型讲到可复现的最小落地代码，也会把我踩过的命中率不稳、知识割裂、维护失效这些坑如实写出来。无论你是刚开始搭个人知识库，还是想给团队 Wiki 加上问答能力，这套思路都值得参考。
1. 为什么把 RAG 和 Wiki 放在一起
1.1 知识库的痛点：沉淀了却找不到
传统 Wiki 的优势在于有目录、有分类、有编辑历史，适合“人来写、人来读”。但人的问题往往是线性口语化的，例如“支付回调一直报签名错误怎么办”“新来的后端应该先看哪几个模块”。这些问题不会按目录结构发起，更不会直接对应某一个页面的标题。你让同事去 Wiki 检索，本质上是让他自己完成“问题翻译成关键词，关键词映射到页面，页面里寻找段落”的全过程。这个过程的成功率很低，尤其是当 Wiki 有上百个页面时。
我在项目初期做过一次统计，把团队群聊里三个月内的技术问题捞出来，对照 Wiki 去人工找答案，平均一个问题需要打开三个页面才能定位到有效段落。有些答案甚至藏在一篇周报的附录里，标题完全看不出关联。这就是典型的“知识割裂”问题：内容就在那里，但搜索链路断掉了，人和知识之间隔着一道隐形的墙。
RAG 的定位恰恰是来补这道墙。它不替代 Wiki，也不替代搜索框，而是把“用户问题”转化为“向量相似度检索 + 上下文重排 + 大模型生成”，让答案以直接可读的方式呈现。本质上，RAG 是给 Wiki 加了一个“语义接口层”，负责把旧知识与新问题做匹配。
1.2 Wiki 负责长知识，RAG 负责找答案
这个标题里有两个动作：长知识和找答案。我在实践里把两种能力拆得非常清楚。Wiki 是唯一的内容源，负责事实维护、版本管理和作者沉淀；RAG 是唯一的问答入口，负责召回相关片段、组织证据、生成回答。这个分工意味着所有文档依然由人写、按规范写，RAG 只做“读取视角的增强”，不直接写入内容。
这个选择帮我避开了很多坑。比如有人会直接用向量数据库当作知识库，把一堆碎片文档丢进去就不管了。短期能跑通 demo，但长期看，文档里的错误、过期信息和重复内容会全部算入索引，最后模型一本正经地把旧答案讲出来。而 Wiki 作为源端，天然有版本、有作者、有审阅机制。一套符合规范的 Wiki，本身就是一个高质量的训练集和检索集。RAG 的检索质量上限，由 Wiki 内容质量决定。
所以我把项目定位成“双引擎”。Wiki 引擎负责知识和权威性，RAG 引擎负责匹配和表达。两者结合，既保留 Wiki 的可追溯性，又享受大模型的自然语言交互能力。
1.3 从浅层到深层：RAG 的三种进阶路径
做这个项目之前，我还顺手梳理了一遍 RAG 当前的技术路线。最基础的是直接向量检索，也就是对文档切片做 embedding，再用问题 embedding 去余弦相似度检索。这种路径适合页面结构清晰、答案集中在某个段落的场景。但在我们的技术 Wiki 里，很多答案需要跨多个页面才能拼出来，比如“服务A 报错，如何根据日志定位到服务B 配置”，这时候单靠向量召回会漏掉关键上下文。
第二阶段是 GraphRAG。它先把 Wiki 里的文档抽取成实体和关系图，再通过社区检测或路径遍历找到和问题相关的子图，最后把子图内容拼给模型生成答案。GraphRAG 对“知识割裂”的改善非常明显，因为知识被组织成了网络，而不是彼此孤立的碎片。热词里出现的 ontology RAG，本质是在图之上再加一层可控的 schema，比如定义“服务、配置、故障、影响范围”等类型和关系，让抽取过程更有约束。对于团队 Wiki 这种内容种类相对固定的场景，本体先行的路线比纯 GraphRAG 更稳。
第三阶段是 Agentic RAG。模型不再只做一次“检索-生成”，而是可以自主决定查哪些页面、先查什么后查什么、以及是否需要根据检索不足去追问。这个阶段的副作用是会引入更多推理开销，但也极大提升了复杂问题的覆盖率。我的项目先实现了标准 RAG，然后逐步叠加图谱和 Agent 决策，整个过程是渐进式的。
2. Wiki 层设计：让知识先“长好”
2.1 选型：为什么用 Markdown + Git 而不是传统在线文档
第一版方案我直接把线上的 Confluence 页面导出成 PDF 丢进 RAG，结果非常糟糕。PDF 切分困难，标题层级丢失，表格跨页后上下文断裂，检索命中率低到没法用。后来我把 Wiki 迁到了 Markdown + Git 的体系，这是整个项目里最关键的决策。
Markdown 的好处是纯文本可解析，标题结构、列表、代码块都有明确标记，切片工具可以直接根据 Markdown 语法做结构化切分。Git 则提供了版本、分支、历史记录，每次更新都清清楚楚。RAG 索引更新也简单：git pull之后对比变更文件，只更新增量部分，而不是全量重建。还顺手解决了多人协作的冲突问题，大家提交 PR 而不是在线直接改。
如果你已经在用 Confluence 或飞书这类平台，也不必推翻重来。可以让 Wiki 编辑继续发生在原平台，但另起一个自动导出的同步仓库，专门作为 RAG 的“饲料源”。关键在于导出的格式要可解析，纯 HTML 或 PDF 都是坑，先转成结构化的 Markdown 再进索引。这个方案既尊重原有编辑习惯，又能享受 RAG 带来的检索能力。
2.2 页面结构与双向链接：给 RAG 提供“上下文”
Wiki 里最强的武器是双链，也就是页面之间互相引用，例如在故障复盘页里写[[支付服务]]，系统就知道两个页面存在语义关联。对 RAG 来说，这种关联非常有价值。切片后，一个 chunk 里如果出现了双链文本，可以顺带把目标页面的标题或摘要一起拉进上下文，让模型知道“支付服务”和“故障复盘”之间的关系。
我在规范里要求每个页面遵循固定骨架：标题、TL;DR、背景说明、关键流程/配置、常见问题、变更记录。这个骨架不是给读者看的，是给切片看的。固定结构意味着文本切分可以按标题定位，检索阶段命中哪个段落，模型就知道这段属于“背景”还是“常见问题”。例如用户问“签名错误怎么处理”，如果命中某个页面的“常见问题”部分，信息密度远高于命中“背景介绍”部分。
双链还帮我解决了“长知识”的问题。写新文档时，作者必须思考它和现有文档之间的关系，把该加的链接加上。这个过程本身就是知识图谱的人工版本，后续做 GraphRAG 时，双链可以作为初始 seed，让图谱抽取的起点比纯文本高好几个量级。
2.3 写作规范与元信息设计：为 RAG 埋好“钩子”
除了正文骨架，我还要求每篇文档顶部写 YAML front matter，包含title、tags、source、updated、related等字段。这些元信息不展示给读者，但对 RAG 的过滤和排序极有帮助。比如检索阶段，如果问题里带有“支付”相关词，可以把tags: [支付]作为硬过滤条件，避免召回无关页面；updated字段则用于时间衰减排序，让新文档比旧文档更容易被召回。
这里要特别说明一个误区：很多人以为 RAG 只要“所有内容向量化”就够了，实际上元信息是检索质量的关键杠杆。纯向量检索在长尾问题上经常把“相关但错误”的页面召回前几名，加一层基于标签或标题的规则过滤，能直接砍掉 30% 的噪声。
内容分类上，我统一用“指南、案例、故障、概念”四类。指南类适合回答“怎么做”，案例类适合回答“有没有先例”，故障类适合回答“报错怎么办”，概念类适合回答“是什么”。这样不管是人工搜索还是 RAG 召回，都能快速判断答案类型是否匹配。这也是从传统 Wiki 升级到 LLM Wiki 的核心：不只是让人能读，还要让机器好读。
3. RAG 层拆解：找答案的完整链路
3.1 标准 RAG 流程
整条链路可以概括为九个环节：读取 Wiki 源文件、清洗文本、按结构切分、生成向量、写入向量库、用户问题改写、向量召回、重排过滤、拼装上下文并让大模型生成答案。前期我经常跳过清洗和问题改写，后来这两个环节被证明比模型选择还重要。
清洗的目的不是删空格，而是去掉 Markdown 语法噪声、注释、空列表项，保留真正的业务信息。问题改写的价值在于把口语问题转成更适合检索的表达，例如“上次微信支付那个报错你们怎么弄的”会被改写成“微信支付报错处理方案”。改写后的查询与文档标题的匹配度会高得多。
向量库选择上，Chroma 适合起步，Milvus 适合规模化。考虑到我们的 Wiki 只有几百篇文档，Chroma 足够，部署简单，还支持按 metadata 过滤。真正的核心其实不在向量库，而在文本切分和召回策略。
3.2 切分策略：决定命中率的第一道坎
很多人以为切分就是把文档按 500 字截断，这是最大的错误。直接按固定长度切分，会把“问题描述”和“解决方案”切成两段，检索时只命中一半，生成的答案自然断章取义。我最终采用的是 Markdown 标题结构切分：先按##一级标题切出章节，再对过长的章节按 400 到 600 字切块，块与块之间保留 50 字重叠。
为什么是 400 到 600 字？这是中文场景里一个比较合理的折中。切太短，单块信息量不足，模型拿不到完整背景；切太长，向量表的语义会变得模糊，而且超出很多 embedding 模型的有效长度。选择重叠是为了避免关键句子正好落在两个块的交界处，丢失上下文。重叠量通常取 10% 到 15%。
切分还有个容易踩的坑：代码块。Wiki 里技术文档大量包含配置文件、API 示例、日志片段。这些代码块不适合和正文混在一起切。我会在切分时把代码块单独提取，作为独立 chunk 存储，同时记录其所属页面标题。这样当用户问“配置文件里timeout怎么写”的时候，能精准命中代码块本身。
3.3 向量化与混合检索：从 30% 到 85% 的调优过程
embedding 模型的选型在中文 Wiki 场景里非常关键。我试过通用英文模型，对中文长尾问题命中率很低，后来换成面向中文的模型，命中率显著提升。重点不是简单比较模型的 benchmark 分数，而是拿自己的 Wiki 数据做测试。在本地部署时，我优先选能在 CPU 上跑的轻量模型，推理耗时要控制在百毫秒级，否则问答体验会变得非常差。
但纯向量检索仍然不够。我的实战经验是混合检索：BM25 关键词检索与向量检索并存，再用重排模型（cross-encoder 类）对两路结果统一打分，选出最相关的 top 5。BM25 擅长精确匹配，例如问题里有“502 bad gateway”，向量搜索经常识别不出这种强关键词，BM25 却能直接命中。向量搜索擅长语义匹配，例如“签收失败”和“回调异常”能建立关联。二者互补上报后，命中率能从单路的 30% 左右拉升到 85% 上下。
重排这一步很重要，不建议省。向量检索拿回的前 20 个片段里，往往有大量“表面相似、实质无关”的内容。用一个专门训练的重排模型把粗排结果精排一遍，效果提升非常明显。重排模型通常比 embedding 大，但对单条查询来说推理成本可接受。
3.4 生成阶段与本地部署经验
生成阶段涉及两件事：模型选型和提示词设计。我用过云端 API，也用过本地模型。考虑到团队文档安全，最终以本地私有化部署为主，开源模型选择上优先中文能力稳定、上下文窗口适中的一代模型。跑推理我用 Ollama 做统一管理，它对模型拉取和接口暴露很友好，一行命令就能起一个 OpenAI 兼容接口供 RAG 程序调用。如果你也图省事，不对着复杂配置折腾，这个方案值得优先试。
提示词设计上，我参考了很多线上项目的教训，最终形成一套“铁律”：告诉模型只能根据上下文回答，不知道就说不知道；要求提供答案时列出依据来源，例如“根据支付服务常见问题，第 2 条”；如果上下文内容不足以回答问题，明确提示需要补充知识库。这么做不是为了漂亮，而是为了治理大模型幻觉问题。知识库问答如果随时编造一个看似正确的答案，会摧毁用户对系统的信任。
另外，很多人问“RAG 知识库能存储图片吗”。我的答案是：最好不要存图片本身，而是存储图片对应的说明文字和图片路径。用户问“架构长什么样”，模型返回一段描述，同时附上图片地址，由前端展示。这样既避免向量模型处理图片的复杂性，又能保护排版逻辑。
4. 实操：一个可复用的“Wiki + 本地 RAG”最小方案
4.1 数据准备：把现有 Wiki 整理成统一目录
我建议先把 Wiki 仓库结构做成这样：
wiki/ 01-guides/ payment-service.md order-service.md 02-incidents/ 2025-01-15-payment-timeout.md 03-concepts/ distributed-tx.md 04-faq/ payment-sign-error.md每个文件都遵循统一的 YAML front matter 和页面骨架。目录约定本身就能帮 RAG 做粗过滤，例如问题里出现“故障”“超时”时，优先在02-incidents下检索。这不是硬规则，而是给向量检索额外的先验信号。
如果你手上已经有一堆零散文档，不要直接全量进索引。先做一次清洗，把过时内容标记出来，没有维护价值的删除。RAG 对垃圾输入的容错率远远低于人的容错率。一个人看三篇废话文档可以自动忽略，但模型可能会把废话当成证据。劣质文档对 RAG 的伤害比重写一遍文档的功夫要大得多。
4.2 核心代码：Python 实现最小 RAG 流程
我不刻意依赖重框架，而是用一套轻量代码把链路跑通。这里给你一个可直接参考的伪代码级实现，主要环节都有。文件读取和切分用结构化方式，向量化通过本地模型接口完成，向量库用便于整体替换的简单实现。以下片段基于 LangChain 风格组装，但核心逻辑可以自行替换。
import os from langchain_community.document_loaders import DirectoryLoader, TextLoader from langchain.text_splitter import MarkdownHeaderTextSplitter from langchain_community.embeddings import OllamaEmbeddings from langchain_community.vectorstores import Chroma # 1. 读取 Wiki 目录 loader = DirectoryLoader("wiki", glob="**/*.md", loader_cls=TextLoader) docs = loader.load() # 2. 按 Markdown 标题结构切分，长章节再按字符切 headers_to_split_on = [("##", "Section")] markdown_splitter = MarkdownHeaderTextSplitter(headers_to_split_on) chunks = [] for doc in docs: splits = markdown_splitter.split_text(doc.page_content) for split in splits: # 递归细分过长的 chunk，这里设置 500 字，overlap 50 if len(split.page_content) > 500: sub_chunks = split.split_text_by_char(500, overlap=50) chunks.extend(sub_chunks) else: chunks.append(split) # 3. 本地化向量化并写入 Chroma embeddings = OllamaEmbeddings(model="your_chinese_embed_model") vectorstore = Chroma.from_documents(chunks, embeddings, persist_directory="./wiki_db") vectorstore.persist()关键的几处细节：切分顺序是先按标题、再按长度，不是反过来；embedding 模型需要和生成模型分离，因为输入输出类型不同；向量库持久化目录要纳入 Git 忽略，不要提交。实际生产环境里，切分和索引通常放成一个定时脚本，当 Wiki 仓库更新后自动重建增量索引。
检索和生成的代码如下：
# 4. 混合检索 + 重排 from langchain_community.retrievers import BM25Retriever, EnsembleRetriever from langchain_community.cross_encoders import HuggingFaceCrossEncoder from langchain.retrievers import ContextualCompressionRetriever from langchain.retrievers.document_compressors import CrossEncoderReranker bm25 = BM25Retriever.from_texts([c.page_content for c in chunks]) bm25.k = 20 vector_retriever = vectorstore.as_retriever(search_kwargs={"k": 20}) ensemble = EnsembleRetriever(retrievers=[bm25, vector_retriever], weights=[0.3, 0.7]) reranker = CrossEncoderReranker(model=HuggingFaceCrossEncoder(model_name="bge-reranker-base")) compression_retriever = ContextualCompressionRetriever( base_compressor=reranker, base_retriever=ensemble ) # 5. 组装上下文并调用本地 LLM from langchain_community.llms import Ollama from langchain_core.prompts import ChatPromptTemplate llm = Ollama(model="qwen2.5:7b", temperature=0.1) prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个严谨的知识库助手。只能依据上下文内容回答，禁止编造。若上下文不足，回复‘知识库中暂无相关记录’。回答时列出依据来源。"), ("human", "上下文：\n{context}\n\n问题：{question}") ])这里我将 temperature 调低到 0.1，目的是让模型输出更稳定、更贴上下文。agentic 扩展可以在compression_retriever之后增加多轮检索控制，例如先检索一次，发现置信度低时再改写问题重试。如果用 AgentScope 2.0 这类框架，可以直接把 RAG 包装成 Service，上层调度逻辑会更省事。
4.3 让 Wiki 反过来成为 RAG 的“监督题库”
这是我特别想强调的一环。Wiki 不只喂给 RAG，还能变成评估 RAG 的“考卷”。具体做法是从 Wiki 的 FAQ 页面和“常见问题”段落中，成对提取“问题-答案”。这些内容本身就是作者维护过的、经过验证的问答对，天然适合作为金标测试集。
我写了一个简单的脚本，从每个 FAQ 页面里提取标题和正文，自动生成测试集。然后跑一遍 RAG 系统，记录每个问题是否找到正确来源、生成答案是否正确。一个粗糙的评估指标是 hit rate，也就是“正确答案对应的文档是否出现在召回 top 5 里”的比例。另一个指标是完全命中率，要求生成答案的关键句子和标准答案接近。前者帮助定位检索问题，后者帮助定位生成问题。热词里的 “rag hit rate” 说的就是前者。
有了这套评估集，后续做优化就有据可依了。改切分参数、换 embedding 模型、调整重排权重，都能先用同一批测试集测一遍，而不是靠感觉判断“好像准了一点”。这也是“RAG 找答案，Wiki 长知识”能持续运转的机制：Wiki 提供了题目，RAG 负责答题，我们一起批改并不断迭代。
5. 常见问题、瓶颈与避坑记录
5.1 为什么检索命中率时高时低？
我在这个项目里被命中率波动折磨过很久。同一套代码，上周命中率 80%，下周变成 60%。排查下来是无处不在的“内容变更”：Wiki 每多一篇新文档，旧文档的向量空间就会被稀释，相关片段的相对位置会发生变化。如果只增量更新而不重建或做归一化，旧问题的排名就会飘。解决办法是建立固定时间窗口的索引重建，并在评估集上跑回归。
另一个常见原因是查询太短。用户只输入一个词，比如“支付”，向量召回会分散到所有涉及支付的页面，无法聚焦。这个问题我在入口层加了问题改写组件：先根据问题长度和关键词密度，自动补充上下文，例如“支付”改写成“支付服务部署、配置和故障排查”。改写后检索范围立刻收窄。
5.2 知识割裂问题的真正解法：GraphRAG 与本体 RAG
如果你发现单个问题需要拼凑多个页面的知识，而对每个页面单独召回的效果很差，这就不是切分能解决的，而是要升级到图谱化。GraphRAG 的基本思路是先对 Wiki 全部文档做实体抽取，例如“订单服务”“签名算法”“QPS 上限”，再抽取实体之间的关系，例如“订单服务依赖签名算法”，最后构建知识图谱。查询时不是找文本块，而是找图谱子图。
本体 RAG 比 GraphRAG 更强调 schema 统一。我在自己的 Wiki 中定义了几类核心实体：服务、组件、故障、配置项、版本号；关系则包括“依赖”“导致”“配置为”“修复于”。使用这套 schema 后，抽取出来的图结构非常干净，查询时也更容易推理。比如用户问“订单服务超时会导致支付服务失败吗”，模型先定位“订单服务”和“支付服务”两个节点，再沿着“依赖”边找到关联链路，最终给出“会，因为支付服务调用了订单服务的接口，且未设置超时熔断”这样的答案。
GraphRAG 和本体 RAG 也有代价，就是构建和更新图谱并不轻松。我的建议是：先用标准 RAG 跑起来，积累用户的真实问题；当发现超过三分之一的复杂问题需要跨文档回答，再逐步引入图谱。不要一上来就追求重型架构。
5.3 RAG 的瓶颈不在模型，而在评估闭环
这句话是我从项目里悟出来的。很多人觉得 RAG 的体验不够好，是因为模型不行，但我实测发现，真正拖后腿的是缺少持续维护和反馈机制。模型可以换，向量库可以换，但如果你不知道问题出在召回还是生成，换了也是白换。所以一定要把“评估集构建”当作和“知识库建设”同等重要的工作，甚至在项目第一天就开始收集问题日志。
具体做法是给线上问答系统加一个“没有命中”的反馈接口。当用户对答案点击“没用”或连续追问时，把该轮检索的 top5 片段、模型回答一起记录下来。每周做一次错误分析，把高频失败问题补充进金标测试集，然后反向调整 Wiki 结构和切分参数。没有这个闭环，RAG 就是一次性的玩具；有了它，才会越来越像团队真正可依赖的智能助手。
5.4 关于后续扩展：从标准 RAG 到 Agentic RAG
最后聊一下下一步方向。标准 RAG 适合回答“知识点型”的问题，但面对“帮我分析这个故障影响哪些服务”这种复合型问题，一次检索并不够。Agentic RAG 的思路是让模型拥有工具调用能力，先决定应该搜索哪个页面，再根据第一轮检索结果决定是否补充搜索。这个过程中可以调用 Wiki 的标签接口、全文搜索接口，甚至提问用户澄清。我的经验是复合类型问题的答案质量在 Agentic 模式下有明显提升，但推理耗时和出错概率也同步上升，需要加入最大检索轮数和置信度终结条件。
另一个值得关注的方向是各类 RAG as Service 平台，它们把检索、重排、评估都组件化，对中小团队很友好。不过我不建议直接把核心问答依赖在某个封闭平台上，因为 Wiki 知识是私有资产，保持数据自主可控远比省那一点开发成本重要。架构上比较好的折中是把知识图谱、向量库、模型全部封装成内部服务，对外只暴露标准 API，这样未来任何组件都可以平滑替换。
说到底，“RAG 找答案，Wiki 长知识”不是一个一次性项目，而是一套需要持续喂养、定期评估的知识基础设施。Wiki 和 RAG 不是替代关系，而是相互成就：Wiki 给 RAG 提供了可以信赖的知识源，RAG 让 Wiki 里的内容真正流动了起来。如果你现在正被团队知识散落、重复提问、文档失效这些问题困扰，与其继续指望大家“多去搜一搜”，不如用这套方法把答案主动送到问题和人面前。根据我这几个月的实测，这种“被送到”的体验，才是知识库真正发挥价值的时候。
