说实话团队里沉淀了两三年的 Wiki真到了要用的时候经常还是得靠人肉翻目录。直到我把 RAG 捡起来搭了一套问答机器人之后才发现Wiki 和 RAG 这俩东西天生就是一对一个负责“存知识”一个负责“找答案”。这篇就聊清楚一个很实用的问题——怎么把自家 Wiki 变成大模型的“答案来源”顺便把本地零基础可复现的 RAG 知识库教程、踩坑经验和进阶方向都写明白。无论你是想给团队搭个知识助手还是单纯想搞懂 RAG 检索增强这个热门词这篇文章都值得看完。1. RAG 为什么绕不开 Wiki1.1 RAG 到底是什么样的存在RAGRetrieval-Augmented Generation检索增强生成说白了就是给大模型加一个“先查资料再回答”的环节。模型不再凭记忆硬答而是先去你的知识库里检索相关内容把检索结果作为上下文一起送给大模型再由模型组织语言生成答案。这个思路特别好理解就像闭卷考试和开卷考试的区别。纯靠模型参数里的知识回答是闭卷碰到新内容、私有内容就懵RAG 是开卷拿到问题先翻资料抄到关键段落再回答。它的核心价值就是让模型“基于你的资料来答”而不是“基于训练数据里那点印象来答”。实际做下来你会发现RAG 这个方案之所以能火不是因为技术多高深而是它解决了企业落地 LLM 最头疼的三个问题知识时效性模型训练完就冻结了但业务每天在变、私有知识文档里的真正干货模型根本没见过、幻觉控制有了真实资料做锚点胡编概率大幅下降。1.2 Wiki 才不是简单的文档集合很多团队对 Wiki 的态度是“先放着以后再说”文档越堆越多质量参差不齐最后变成没人看的电子垃圾。但如果你要把 RAG 落地Wiki 恰恰是最理想的知识底座原因不是它“有个网页”而是它自带三样 RAG 特别需要的东西。第一是结构化。一个正经 Wiki 通常有分类、有层级、有标题体系这些结构在 RAG 做文本切分的时候是天然的导航。比如我实操中常见的情况产品 Wiki 里一个页面讲完功能说明、架构图、配置参数正常去切分很容易把不同主题的内容切进同一个 block导致检索语义混乱。但 Wiki 的标题、子页面、目录树能帮我们按语义边界去切效果完全不同。第二是版本和更新记录。企业知识最大的坑是“旧文档没人清”RAG 检索到的答案是过期内容比搜不到还麻烦。Wiki 的版本历史和负责人机制至少让你能追到“这段内容谁写的、什么时候改的”对于给知识库做质量治理非常关键。第三是互链关系。Wiki 页面之间的链接其实就是隐性的图谱关系类似“A 方案依赖 B 模块”这种信息纯靠向量检索很难体现但未来做 GraphRAG图增强检索的时候这些链接可以直接变成图谱里的边。1.3 为什么不直接微调模型我自己碰到过不少朋友问既然大模型是公开的我用这些文档微调一个专用模型不是更“原生”吗说实话微调和 RAG 不是对立的但对绝大多数团队RAG 的性价比远高于微调。微调等于把知识揉进模型参数里要的是算力、训练数据清洗、评测回归而且每次文档一更新就得重新跑一轮。RAG 是知识外挂文档变了只需要重新入库几秒钟同步完。更实际的一点是微调模型出错了很难定位是数据问题还是参数问题但 RAG 出错了你能直接把检索到的上下文拎出来看——AI 的回答到底依据了什么清清楚楚。从成本角度算笔账微调一次至少算力费和人工成本几千块起步还得养着评估流程RAG 方案只要有一个向量库加一个模型接口就能跑几百块就能撑起一个小团队的内部问答。真正专业落地的时候很多团队是 RAG 打底等某些核心场景跑熟了再考虑微调双轨并行。2. 一个能用的 RAG 流程由哪些环节组成2.1 六段式全景拆解网上讲 RAG 的教程一大堆但太多是只给个代码 Demo跑通了就以为完事了。我梳理了一套能用在生产环境的流程一共六个环节文档接入、文本解析与切分、向量化入库、检索召回、重排融合、生成回答。文档接入最容易被忽略。企业里的知识源年代久远有的是 Word 和 PDF有的是 Confluence 导出的 HTML还有大量 Markdown 散落在 GitLab。用 LangChain 里的加载器也好自己写解析脚本也好这一步的目标只有一个把所有格式统一转成“干净文本”。所谓“干净”就是去掉页眉页脚、导航重复内容、图片占位符只保留正文语义。我踩过最大的坑是 PDF 里的表格解析完往往变成一串乱序文字。后来用了专门的表格抽取工具如 unstructured 的表格模式才稍微体面一点但仍要人工抽检。2.2 文本切分第一个瓶颈所在切分Chunking是 RAG 效果最容易翻车、也最少被人认真对待的环节。切太大一个 chunk 里混着多个主题检索时语义被稀释切太小单个 chunk 承载不了完整上下文就算检索到了也答不全。说到底chunk 的粒度要匹配“你希望模型看到多大的上下文”。我常用的初始参数是 chunk_size512字符级别中文场景我会按 500-800 个字尝试、overlap50。overlap 的作用是保留上下文接缝避免把一个完整段落拦腰截断后丢失关键信息。按语义边界切更好比如按 Markdown 标题、段落、列表来切这就要用到 LangChain 的 MarkdownHeaderTextSplitterWiki 文档用它效果明显好于暴力按长度切。经验数据分享一下同一批文档纯按长度切 hit rate检索命中率大概 70%换成语义边界切能到 85% 以上。为什么因为暴力切分产出的 chunk 很多是“半句话”向量化之后语义本身就残缺召回自然差。2.3 嵌入模型和向量库怎么选向量化这一步是把文本变成一串数字向量让语义相似的内容在向量空间里靠得近。这里的模型选择直接决定检索质量。商用闭源接口方便但按量付费且数据要出内网很多企业直接 pass。本地部署是更可控的路子中文场景我用过的开源模型里BGE 系列bge-large-zh对中文的支持明显比通用模型强多语言场景可以考虑 nomic-embed-text胜在体积小、CPU 也能跑。向量库的选择更看数据规模。起步阶段百万向量以下Chroma 和 FAISS 都够用Chroma 胜在带持久化和简单过滤器FAISS 只解决检索本身适合玩原型。数据量上来了、需要分布式多副本了才轮到 Milvus 这类重家伙。别一上来就上大件运维成本会吃掉你所有开发精力。2.4 检索策略向量召回不够还得混合检索纯向量检索有个通病就是它天生对专有名词、型号、缩写不敏感。比如团队 Wiki 里全是“VLLM-RAG 模块”这种内部黑话你问“VLLM 的 RAG 流程是什么”向量检索经常找不准因为这个词组在语料里的分布比较稀疏向量表达不稳定。我用的方案是混合检索BM25 关键词检索和向量检索并行两者结果做加权融合。BM25 擅长精确匹配术语向量擅长语义相似互补之后 hit rate 会再涨 5-10 个点。配合 RRFReciprocal Rank Fusion做结果融合代码不复杂效果却非常可观。另外 top_k 别贪多取 4-6 个就够太多会把不相关内容塞进上下文反而干扰生成。3. 零基础可复制的本地 RAG 知识库实操3.1 技术栈选型与整体思路下面这套实操是我建议新手第一次跑的顺序完全本地、零 API 费用数据不出内网。技术栈很简单Ollama 负责跑生成模型和嵌入模型Chroma 做向量库LangChain 负责流程编排数据源就用你自己的 Wiki 导出的 Markdown 或 HTML。为什么选 Ollama它对 Llama、Qwen 等开源模型的封装非常干净一条命令下载模型、一条命令起服务还带 OpenAI 兼容接口后续切换模型成本极低。嵌入模型我用的是 nomic-embed-text体积不到 300MB普通笔记本 CPU 都能跑中文效果中规中矩但够用。想要更好的中文语义可以换 bge-m3代价是资源占用更高。整个架构一句话说清楚把 Wiki 文档切块后向量化存入 Chroma用户提问时先用问题去向量库搜出最相关的几个文本块连同问题一起送进 Ollama 里的生成模型让它基于这些资料写出答案。3.2 本地部署完整步骤先装 Ollama直接到官网下载安装包装完在终端里拉模型。生成模型我用 qwen2.5:7b-instruct中文问答能力在开源模型里算是能打的档位嵌入模型拉 nomic-embed-text。两条命令ollama pull qwen2.5:7b-instruct ollama pull nomic-embed-text然后建 Python 环境和依赖我用 conda 隔离conda create -n rag-wiki python3.11 conda activate rag-wiki pip install langchain langchain-community chromadb ollama接下来是完整的入库代码逻辑是遍历 Wiki 导出的 Markdown 文件按文档结构切块向量化后写入本地 Chromafrom langchain_community.document_loaders import DirectoryLoader from langchain.text_splitter import MarkdownHeaderTextSplitter from langchain_community.embeddings import OllamaEmbeddings from langchain_community.vectorstores import Chroma # 1. 加载 Wiki 导出的 Markdown 文件 loader DirectoryLoader(./wiki_export/, glob**/*.md) docs loader.load() # 2. 按标题层级做语义切分 headers_to_split_on [ (#, H1), (##, H2), (###, H3), ] splitter MarkdownHeaderTextSplitter(headers_to_split_on, strip_headersFalse) chunks [] for doc in docs: chunks.extend(splitter.split_text(doc.page_content)) # 3. 向量化并入 Chroma本地持久化到 ./chroma_db embeddings OllamaEmbeddings(modelnomic-embed-text, base_urlhttp://localhost:11434) vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./chroma_db ) vectorstore.persist()然后写问答接口这里的关键是检索出 top_k 个相关块后拼进提示词再让模型回答from langchain_community.llms import Ollama from langchain_core.prompts import ChatPromptTemplate llm Ollama(modelqwen2.5:7b-instruct, base_urlhttp://localhost:11434) prompt ChatPromptTemplate.from_messages([ (system, 你是一个知识库助手只能基于提供的内容回答不要编造。如果资料中没有答案就明确说不知道。), (human, 资料{context}\\n\\n问题{question}) ]) def ask(question, k4): related vectorstore.similarity_search_with_score(question, kk) context \\n\\n.join([doc.page_content for doc, score in related]) chain prompt | llm return chain.invoke({context: context, question: question}) print(ask(VLLM-RAG 模块的部署流程是什么))3.3 参数选择背后的计算逻辑你可能想问chunk_size 和 top_k 到底怎么定我用实际数据说明。我的 Wiki 文档平均一个标题块约 800 字那就把 chunk_size 设为 800、overlap 设 80。如果文档更长我会用递归字符切分器兜底。这个策略本质是让 chunk 大小尽量贴合语义块的自然长度。top_k4 是我试出来的平衡点。取 2 时经常漏掉关键资料取 8 时模型容易受无关内容干扰、回答发散。从成本看也合理假设每个 chunk 800 字4 个 chunk 约 3200 字加上问题本身对 7B 模型的上下文窗口来说非常轻松响应速度也能控制在 3 秒左右。成本方面简单算一下本地跑 Ollama 完全不花 API 费用只耗电。一台 32GB 内存的 MacBook Pro 或者带 8GB 显存的 GPU 机器就能流畅跑 7B 模型。对比调用商用接口动辄按 token 计费团队内部随便刷问题没有心理负担这一条就值回所有折腾时间。4. 本地 RAG 常见问题排查实录4.1 Hit rate 低问题大概率出在这几处Hit rate检索命中率是我衡量 RAG 系统健康度的第一指标它代表“该搜到的资料有没有被搜出来”。如果 hit rate 低于 80%先别急着调模型按下面的顺序排查现象可能原因解决方案检索结果完全不相关嵌入模型和文档语言不匹配中文文档换 bge 系列模型别用纯英文模型相关文档排在后面chunk 太大语义被稀释调小 chunk_size按标题切分专有名词搜不到向量检索对术语不敏感加 BM25 混合检索提高精确匹配权重问题太宽泛导致结果杂top_k 过大降到 4或加相似度阈值过滤旧文档覆盖了新文档知识库里同一份内容多版本并存入库前做版本清理只保留有效版本4.2 生成质量不对按顺序排查检索没问题但答案不对这类问题通常在生成环节。我先给一个原则RAG 输出质量的上限由检索决定下限由提示词兜着。提示词里必须写清楚“只能基于提供的内容回答不许编造资料里没有就直说不知道”。别小看这句话它能砍掉大半幻觉输出。如果模型还是答偏检查是不是上下文太长、把弱相关内容也塞进去了。我的做法是给每个检索结果带上来源路径提示词里要求“引用来源”既能约束模型不乱说也方便用户回溯查证。效果很明显——回答里敢写来源了整个系统的可信度立刻不一样。4.3 知识库里的图片和表格怎么处理“RAG 知识库能存储图片嘛”这个问题我被问过很多次。纯文本向量库当然存不了图片语义但实际业务里的图片大多是截图和流程图它们承载的信息其实在文字标注里。我的做法是先把图片 OCR 导出文字再把说明文字一起入库。这样检索到的是图片周边文字模型能理解上下文。至于表格是个人就能被坑。PDF 表格解析出来经常乱序直接把表格文本塞进向量库检索时模型根本无法理解行列逻辑。我现在的方案是优先找原始文件Excel、CSV按行转成描述性句子比如“模块 A 的版本号是 1.2.0”再入库。实在只有 PDF 里的表就单独抽出来人工清洗一次比在 RAG 流程里想办法更快。4.4 部署运维的隐藏坑本地部署最大的坑在资源开销。第一次跑 Ollama 时如果发现回答特别慢大概率是 CPU 跑模型扛不住。7B 模型量化版大概需要 4-5GB 内存且明显吃 CPU 算力数据量大时嵌入的计算也卡。建议先在小批量文档上试跑确认全链路通了再全量入库。另一个坑是持久化目录。Chroma 的 persist_directory 如果在运行中被中断可能导致向量数据损坏。我的习惯是写个定时任务定期备份这个目录。并发问题上Ollama 默认单请求几个人同时用就会排队要加并发就得在服务端套一层负载均衡这块我在小型团队内部就直接忽略——排队就排队反正比翻 Wiki 快。5. 基础 RAG 不够用时怎么往前走5.1 GraphRAG把“关系”卷回来基础 RAG 处理“单点知识”没问题比如“XX 模块的配置项有哪些”。但碰上需要跨文档推理的问题——“哪些模块依赖 VLLM-RAG 服务”它就开始拉胯因为答案分散在不同文档里向量召回很难把多处信息拼起来。GraphRAG 的思路是额外建立一个知识图谱先抽取出文档里的实体人、系统、模块、术语和关系“A 依赖 B”“A 属于 C”把检索从“找文本块”升级成“沿着图谱路径找答案”。实际操作比基础 RAG 重很多但效果好而且 Wiki 天然适合做这件事页面互链就是现成的边。5.2 Ontology RAG给领域知识上“枷锁”Ontology本体RAG 是给知识库定义一套领域规则比如“在医疗场景里症状、疾病、药物、检查这四者有固定的关系模式”。检索和生成的时候都受这套本体约束答案更规范、更不易乱跑。这听起来学术味很浓但落地价值很明显如果你团队的 Wiki 里大量内容是固定格式故障单、需求单、周报本体能帮模型理解“某个字段填什么”防止生成出结构不对的东西。成本也高需要人工梳理本体结构适合知识库覆盖面窄但严谨性要求高的场景。5.3 Agentic RAG让模型自己决定查什么Agentic RAG 是我觉得最有意思的方向。它不再是“一次检索一次生成”的直线流程而是让模型Agent自己规划先查哪个库、结果不够再换什么关键词、是否需要多轮检索融合。本质上是把 RAG 从工具变成“思考过程”。举例说用户问“本周线上事故报告里支付模块相关的有哪几篇”基础 RAG 大概率检索不到因为“本周”“支付模块”这些限定词在向量空间里很难精确表达。Agent 会把问题拆解成“事故报告列表 支付模块过滤”先调检索工具再自己判断结果是否满足条件不满足就换个策略再试一轮。5.4 和 Wiki 长期共存的建议不管走到哪一步架构升级都别忘记 Wiki 本身的质量治理。RAG 的上限取决于知识库的质量这个事实再怎么强调都不过分。我最后给三条实用建议一是定期清理过期页面别让旧版本干扰检索二是每个页面控制篇幅长文要拆子页面方便语义切分三是给关键页面加负责人保证内容可追溯。最后再分享一个小技巧做完整套本地知识库问答之后我最大的体会是不要一上来就追 GraphRAG 这类高级玩法先把“文本切分 混合检索 top_k 调优”这套基本功做到位hit rate 过 85% 再考虑进阶。我自己就是在基础环节打磨了两周效果稳定后才逐步加入 Agent 和图谱能力的。如果你正在做类似的事建议先拿 100 篇最常被搜索的 Wiki 页面做实验集把这 100 篇的检索质量调到满意再铺开到全量文档——这个节奏能让你少走很多弯路。
本地 RAG 知识库实战：把团队 Wiki 变成大模型问答助手
说实话团队里沉淀了两三年的 Wiki真到了要用的时候经常还是得靠人肉翻目录。直到我把 RAG 捡起来搭了一套问答机器人之后才发现Wiki 和 RAG 这俩东西天生就是一对一个负责“存知识”一个负责“找答案”。这篇就聊清楚一个很实用的问题——怎么把自家 Wiki 变成大模型的“答案来源”顺便把本地零基础可复现的 RAG 知识库教程、踩坑经验和进阶方向都写明白。无论你是想给团队搭个知识助手还是单纯想搞懂 RAG 检索增强这个热门词这篇文章都值得看完。1. RAG 为什么绕不开 Wiki1.1 RAG 到底是什么样的存在RAGRetrieval-Augmented Generation检索增强生成说白了就是给大模型加一个“先查资料再回答”的环节。模型不再凭记忆硬答而是先去你的知识库里检索相关内容把检索结果作为上下文一起送给大模型再由模型组织语言生成答案。这个思路特别好理解就像闭卷考试和开卷考试的区别。纯靠模型参数里的知识回答是闭卷碰到新内容、私有内容就懵RAG 是开卷拿到问题先翻资料抄到关键段落再回答。它的核心价值就是让模型“基于你的资料来答”而不是“基于训练数据里那点印象来答”。实际做下来你会发现RAG 这个方案之所以能火不是因为技术多高深而是它解决了企业落地 LLM 最头疼的三个问题知识时效性模型训练完就冻结了但业务每天在变、私有知识文档里的真正干货模型根本没见过、幻觉控制有了真实资料做锚点胡编概率大幅下降。1.2 Wiki 才不是简单的文档集合很多团队对 Wiki 的态度是“先放着以后再说”文档越堆越多质量参差不齐最后变成没人看的电子垃圾。但如果你要把 RAG 落地Wiki 恰恰是最理想的知识底座原因不是它“有个网页”而是它自带三样 RAG 特别需要的东西。第一是结构化。一个正经 Wiki 通常有分类、有层级、有标题体系这些结构在 RAG 做文本切分的时候是天然的导航。比如我实操中常见的情况产品 Wiki 里一个页面讲完功能说明、架构图、配置参数正常去切分很容易把不同主题的内容切进同一个 block导致检索语义混乱。但 Wiki 的标题、子页面、目录树能帮我们按语义边界去切效果完全不同。第二是版本和更新记录。企业知识最大的坑是“旧文档没人清”RAG 检索到的答案是过期内容比搜不到还麻烦。Wiki 的版本历史和负责人机制至少让你能追到“这段内容谁写的、什么时候改的”对于给知识库做质量治理非常关键。第三是互链关系。Wiki 页面之间的链接其实就是隐性的图谱关系类似“A 方案依赖 B 模块”这种信息纯靠向量检索很难体现但未来做 GraphRAG图增强检索的时候这些链接可以直接变成图谱里的边。1.3 为什么不直接微调模型我自己碰到过不少朋友问既然大模型是公开的我用这些文档微调一个专用模型不是更“原生”吗说实话微调和 RAG 不是对立的但对绝大多数团队RAG 的性价比远高于微调。微调等于把知识揉进模型参数里要的是算力、训练数据清洗、评测回归而且每次文档一更新就得重新跑一轮。RAG 是知识外挂文档变了只需要重新入库几秒钟同步完。更实际的一点是微调模型出错了很难定位是数据问题还是参数问题但 RAG 出错了你能直接把检索到的上下文拎出来看——AI 的回答到底依据了什么清清楚楚。从成本角度算笔账微调一次至少算力费和人工成本几千块起步还得养着评估流程RAG 方案只要有一个向量库加一个模型接口就能跑几百块就能撑起一个小团队的内部问答。真正专业落地的时候很多团队是 RAG 打底等某些核心场景跑熟了再考虑微调双轨并行。2. 一个能用的 RAG 流程由哪些环节组成2.1 六段式全景拆解网上讲 RAG 的教程一大堆但太多是只给个代码 Demo跑通了就以为完事了。我梳理了一套能用在生产环境的流程一共六个环节文档接入、文本解析与切分、向量化入库、检索召回、重排融合、生成回答。文档接入最容易被忽略。企业里的知识源年代久远有的是 Word 和 PDF有的是 Confluence 导出的 HTML还有大量 Markdown 散落在 GitLab。用 LangChain 里的加载器也好自己写解析脚本也好这一步的目标只有一个把所有格式统一转成“干净文本”。所谓“干净”就是去掉页眉页脚、导航重复内容、图片占位符只保留正文语义。我踩过最大的坑是 PDF 里的表格解析完往往变成一串乱序文字。后来用了专门的表格抽取工具如 unstructured 的表格模式才稍微体面一点但仍要人工抽检。2.2 文本切分第一个瓶颈所在切分Chunking是 RAG 效果最容易翻车、也最少被人认真对待的环节。切太大一个 chunk 里混着多个主题检索时语义被稀释切太小单个 chunk 承载不了完整上下文就算检索到了也答不全。说到底chunk 的粒度要匹配“你希望模型看到多大的上下文”。我常用的初始参数是 chunk_size512字符级别中文场景我会按 500-800 个字尝试、overlap50。overlap 的作用是保留上下文接缝避免把一个完整段落拦腰截断后丢失关键信息。按语义边界切更好比如按 Markdown 标题、段落、列表来切这就要用到 LangChain 的 MarkdownHeaderTextSplitterWiki 文档用它效果明显好于暴力按长度切。经验数据分享一下同一批文档纯按长度切 hit rate检索命中率大概 70%换成语义边界切能到 85% 以上。为什么因为暴力切分产出的 chunk 很多是“半句话”向量化之后语义本身就残缺召回自然差。2.3 嵌入模型和向量库怎么选向量化这一步是把文本变成一串数字向量让语义相似的内容在向量空间里靠得近。这里的模型选择直接决定检索质量。商用闭源接口方便但按量付费且数据要出内网很多企业直接 pass。本地部署是更可控的路子中文场景我用过的开源模型里BGE 系列bge-large-zh对中文的支持明显比通用模型强多语言场景可以考虑 nomic-embed-text胜在体积小、CPU 也能跑。向量库的选择更看数据规模。起步阶段百万向量以下Chroma 和 FAISS 都够用Chroma 胜在带持久化和简单过滤器FAISS 只解决检索本身适合玩原型。数据量上来了、需要分布式多副本了才轮到 Milvus 这类重家伙。别一上来就上大件运维成本会吃掉你所有开发精力。2.4 检索策略向量召回不够还得混合检索纯向量检索有个通病就是它天生对专有名词、型号、缩写不敏感。比如团队 Wiki 里全是“VLLM-RAG 模块”这种内部黑话你问“VLLM 的 RAG 流程是什么”向量检索经常找不准因为这个词组在语料里的分布比较稀疏向量表达不稳定。我用的方案是混合检索BM25 关键词检索和向量检索并行两者结果做加权融合。BM25 擅长精确匹配术语向量擅长语义相似互补之后 hit rate 会再涨 5-10 个点。配合 RRFReciprocal Rank Fusion做结果融合代码不复杂效果却非常可观。另外 top_k 别贪多取 4-6 个就够太多会把不相关内容塞进上下文反而干扰生成。3. 零基础可复制的本地 RAG 知识库实操3.1 技术栈选型与整体思路下面这套实操是我建议新手第一次跑的顺序完全本地、零 API 费用数据不出内网。技术栈很简单Ollama 负责跑生成模型和嵌入模型Chroma 做向量库LangChain 负责流程编排数据源就用你自己的 Wiki 导出的 Markdown 或 HTML。为什么选 Ollama它对 Llama、Qwen 等开源模型的封装非常干净一条命令下载模型、一条命令起服务还带 OpenAI 兼容接口后续切换模型成本极低。嵌入模型我用的是 nomic-embed-text体积不到 300MB普通笔记本 CPU 都能跑中文效果中规中矩但够用。想要更好的中文语义可以换 bge-m3代价是资源占用更高。整个架构一句话说清楚把 Wiki 文档切块后向量化存入 Chroma用户提问时先用问题去向量库搜出最相关的几个文本块连同问题一起送进 Ollama 里的生成模型让它基于这些资料写出答案。3.2 本地部署完整步骤先装 Ollama直接到官网下载安装包装完在终端里拉模型。生成模型我用 qwen2.5:7b-instruct中文问答能力在开源模型里算是能打的档位嵌入模型拉 nomic-embed-text。两条命令ollama pull qwen2.5:7b-instruct ollama pull nomic-embed-text然后建 Python 环境和依赖我用 conda 隔离conda create -n rag-wiki python3.11 conda activate rag-wiki pip install langchain langchain-community chromadb ollama接下来是完整的入库代码逻辑是遍历 Wiki 导出的 Markdown 文件按文档结构切块向量化后写入本地 Chromafrom langchain_community.document_loaders import DirectoryLoader from langchain.text_splitter import MarkdownHeaderTextSplitter from langchain_community.embeddings import OllamaEmbeddings from langchain_community.vectorstores import Chroma # 1. 加载 Wiki 导出的 Markdown 文件 loader DirectoryLoader(./wiki_export/, glob**/*.md) docs loader.load() # 2. 按标题层级做语义切分 headers_to_split_on [ (#, H1), (##, H2), (###, H3), ] splitter MarkdownHeaderTextSplitter(headers_to_split_on, strip_headersFalse) chunks [] for doc in docs: chunks.extend(splitter.split_text(doc.page_content)) # 3. 向量化并入 Chroma本地持久化到 ./chroma_db embeddings OllamaEmbeddings(modelnomic-embed-text, base_urlhttp://localhost:11434) vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directory./chroma_db ) vectorstore.persist()然后写问答接口这里的关键是检索出 top_k 个相关块后拼进提示词再让模型回答from langchain_community.llms import Ollama from langchain_core.prompts import ChatPromptTemplate llm Ollama(modelqwen2.5:7b-instruct, base_urlhttp://localhost:11434) prompt ChatPromptTemplate.from_messages([ (system, 你是一个知识库助手只能基于提供的内容回答不要编造。如果资料中没有答案就明确说不知道。), (human, 资料{context}\\n\\n问题{question}) ]) def ask(question, k4): related vectorstore.similarity_search_with_score(question, kk) context \\n\\n.join([doc.page_content for doc, score in related]) chain prompt | llm return chain.invoke({context: context, question: question}) print(ask(VLLM-RAG 模块的部署流程是什么))3.3 参数选择背后的计算逻辑你可能想问chunk_size 和 top_k 到底怎么定我用实际数据说明。我的 Wiki 文档平均一个标题块约 800 字那就把 chunk_size 设为 800、overlap 设 80。如果文档更长我会用递归字符切分器兜底。这个策略本质是让 chunk 大小尽量贴合语义块的自然长度。top_k4 是我试出来的平衡点。取 2 时经常漏掉关键资料取 8 时模型容易受无关内容干扰、回答发散。从成本看也合理假设每个 chunk 800 字4 个 chunk 约 3200 字加上问题本身对 7B 模型的上下文窗口来说非常轻松响应速度也能控制在 3 秒左右。成本方面简单算一下本地跑 Ollama 完全不花 API 费用只耗电。一台 32GB 内存的 MacBook Pro 或者带 8GB 显存的 GPU 机器就能流畅跑 7B 模型。对比调用商用接口动辄按 token 计费团队内部随便刷问题没有心理负担这一条就值回所有折腾时间。4. 本地 RAG 常见问题排查实录4.1 Hit rate 低问题大概率出在这几处Hit rate检索命中率是我衡量 RAG 系统健康度的第一指标它代表“该搜到的资料有没有被搜出来”。如果 hit rate 低于 80%先别急着调模型按下面的顺序排查现象可能原因解决方案检索结果完全不相关嵌入模型和文档语言不匹配中文文档换 bge 系列模型别用纯英文模型相关文档排在后面chunk 太大语义被稀释调小 chunk_size按标题切分专有名词搜不到向量检索对术语不敏感加 BM25 混合检索提高精确匹配权重问题太宽泛导致结果杂top_k 过大降到 4或加相似度阈值过滤旧文档覆盖了新文档知识库里同一份内容多版本并存入库前做版本清理只保留有效版本4.2 生成质量不对按顺序排查检索没问题但答案不对这类问题通常在生成环节。我先给一个原则RAG 输出质量的上限由检索决定下限由提示词兜着。提示词里必须写清楚“只能基于提供的内容回答不许编造资料里没有就直说不知道”。别小看这句话它能砍掉大半幻觉输出。如果模型还是答偏检查是不是上下文太长、把弱相关内容也塞进去了。我的做法是给每个检索结果带上来源路径提示词里要求“引用来源”既能约束模型不乱说也方便用户回溯查证。效果很明显——回答里敢写来源了整个系统的可信度立刻不一样。4.3 知识库里的图片和表格怎么处理“RAG 知识库能存储图片嘛”这个问题我被问过很多次。纯文本向量库当然存不了图片语义但实际业务里的图片大多是截图和流程图它们承载的信息其实在文字标注里。我的做法是先把图片 OCR 导出文字再把说明文字一起入库。这样检索到的是图片周边文字模型能理解上下文。至于表格是个人就能被坑。PDF 表格解析出来经常乱序直接把表格文本塞进向量库检索时模型根本无法理解行列逻辑。我现在的方案是优先找原始文件Excel、CSV按行转成描述性句子比如“模块 A 的版本号是 1.2.0”再入库。实在只有 PDF 里的表就单独抽出来人工清洗一次比在 RAG 流程里想办法更快。4.4 部署运维的隐藏坑本地部署最大的坑在资源开销。第一次跑 Ollama 时如果发现回答特别慢大概率是 CPU 跑模型扛不住。7B 模型量化版大概需要 4-5GB 内存且明显吃 CPU 算力数据量大时嵌入的计算也卡。建议先在小批量文档上试跑确认全链路通了再全量入库。另一个坑是持久化目录。Chroma 的 persist_directory 如果在运行中被中断可能导致向量数据损坏。我的习惯是写个定时任务定期备份这个目录。并发问题上Ollama 默认单请求几个人同时用就会排队要加并发就得在服务端套一层负载均衡这块我在小型团队内部就直接忽略——排队就排队反正比翻 Wiki 快。5. 基础 RAG 不够用时怎么往前走5.1 GraphRAG把“关系”卷回来基础 RAG 处理“单点知识”没问题比如“XX 模块的配置项有哪些”。但碰上需要跨文档推理的问题——“哪些模块依赖 VLLM-RAG 服务”它就开始拉胯因为答案分散在不同文档里向量召回很难把多处信息拼起来。GraphRAG 的思路是额外建立一个知识图谱先抽取出文档里的实体人、系统、模块、术语和关系“A 依赖 B”“A 属于 C”把检索从“找文本块”升级成“沿着图谱路径找答案”。实际操作比基础 RAG 重很多但效果好而且 Wiki 天然适合做这件事页面互链就是现成的边。5.2 Ontology RAG给领域知识上“枷锁”Ontology本体RAG 是给知识库定义一套领域规则比如“在医疗场景里症状、疾病、药物、检查这四者有固定的关系模式”。检索和生成的时候都受这套本体约束答案更规范、更不易乱跑。这听起来学术味很浓但落地价值很明显如果你团队的 Wiki 里大量内容是固定格式故障单、需求单、周报本体能帮模型理解“某个字段填什么”防止生成出结构不对的东西。成本也高需要人工梳理本体结构适合知识库覆盖面窄但严谨性要求高的场景。5.3 Agentic RAG让模型自己决定查什么Agentic RAG 是我觉得最有意思的方向。它不再是“一次检索一次生成”的直线流程而是让模型Agent自己规划先查哪个库、结果不够再换什么关键词、是否需要多轮检索融合。本质上是把 RAG 从工具变成“思考过程”。举例说用户问“本周线上事故报告里支付模块相关的有哪几篇”基础 RAG 大概率检索不到因为“本周”“支付模块”这些限定词在向量空间里很难精确表达。Agent 会把问题拆解成“事故报告列表 支付模块过滤”先调检索工具再自己判断结果是否满足条件不满足就换个策略再试一轮。5.4 和 Wiki 长期共存的建议不管走到哪一步架构升级都别忘记 Wiki 本身的质量治理。RAG 的上限取决于知识库的质量这个事实再怎么强调都不过分。我最后给三条实用建议一是定期清理过期页面别让旧版本干扰检索二是每个页面控制篇幅长文要拆子页面方便语义切分三是给关键页面加负责人保证内容可追溯。最后再分享一个小技巧做完整套本地知识库问答之后我最大的体会是不要一上来就追 GraphRAG 这类高级玩法先把“文本切分 混合检索 top_k 调优”这套基本功做到位hit rate 过 85% 再考虑进阶。我自己就是在基础环节打磨了两周效果稳定后才逐步加入 Agent 和图谱能力的。如果你正在做类似的事建议先拿 100 篇最常被搜索的 Wiki 页面做实验集把这 100 篇的检索质量调到满意再铺开到全量文档——这个节奏能让你少走很多弯路。