团队内部的 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_clsTextLoader) 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, overlap50) chunks.extend(sub_chunks) else: chunks.append(split) # 3. 本地化向量化并写入 Chroma embeddings OllamaEmbeddings(modelyour_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(modelHuggingFaceCrossEncoder(model_namebge-reranker-base)) compression_retriever ContextualCompressionRetriever( base_compressorreranker, base_retrieverensemble ) # 5. 组装上下文并调用本地 LLM from langchain_community.llms import Ollama from langchain_core.prompts import ChatPromptTemplate llm Ollama(modelqwen2.5:7b, temperature0.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 里的内容真正流动了起来。如果你现在正被团队知识散落、重复提问、文档失效这些问题困扰与其继续指望大家“多去搜一搜”不如用这套方法把答案主动送到问题和人面前。根据我这几个月的实测这种“被送到”的体验才是知识库真正发挥价值的时候。 
长河君 · 2026/10/1 23:24:10 · 阅读 1.2k Wiki长知识，RAG找答案：团队知识库精准问答实践
团队内部的 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_clsTextLoader) 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, overlap50) chunks.extend(sub_chunks) else: chunks.append(split) # 3. 本地化向量化并写入 Chroma embeddings OllamaEmbeddings(modelyour_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(modelHuggingFaceCrossEncoder(model_namebge-reranker-base)) compression_retriever ContextualCompressionRetriever( base_compressorreranker, base_retrieverensemble ) # 5. 组装上下文并调用本地 LLM from langchain_community.llms import Ollama from langchain_core.prompts import ChatPromptTemplate llm Ollama(modelqwen2.5:7b, temperature0.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 里的内容真正流动了起来。如果你现在正被团队知识散落、重复提问、文档失效这些问题困扰与其继续指望大家“多去搜一搜”不如用这套方法把答案主动送到问题和人面前。根据我这几个月的实测这种“被送到”的体验才是知识库真正发挥价值的时候。