RAG 这个词这两年在圈子里被聊得很多但真正动手在自己机器上跑通一套完整链路的人其实没想象中那么多。大部分人停留在“知道是检索增强生成”的层面一旦要落地就会卡在文档切分怎么切、向量库选哪个、检索召回不准怎么办这些具体问题上。我前后折腾过几套不同规模的本地 RAG 方案从个人笔记检索到团队内部知识库都试过踩的坑不算少。这篇就把 RAG 的原理拆开讲清楚再把本地化落地的完整流程、参数选择、排查技巧一次性摊开来说适合想自己动手搭一套、又不想被各种框架绕晕的朋友参考。核心关键词 RAG、向量检索、文档切分、本地部署、召回优化会贯穿全文读完你至少能独立跑通一套能用的本地知识问答系统。1. 先想清楚 RAG 到底在解决什么问题1.1 大模型的两个硬伤与 RAG 的定位要理解 RAG得先理解它为什么存在。大语言模型有两个绕不过去的硬伤一是知识有截止时间训练数据之后发生的事情它不知道二是它不知道自己不知道遇到没见过的内容会一本正经地编。这两个问题在业务场景里是致命的你不可能让一个客服机器人对着用户胡编产品参数。常见的补救思路有两条微调和 RAG。微调是把新知识灌进模型参数里成本高、周期长而且知识一更新就得重训非常笨重。RAG 走的是另一条路——不改模型而是在模型回答之前先从外部知识库里把相关资料检索出来塞进提示词里让模型“看着资料回答”。打个比方微调像是让学生把整本书背下来RAG 像是开卷考试考前把可能用到的章节翻到桌上。开卷的好处显而易见资料随时能换、能增、能删模型本身不用动。所以 RAG 的本质是一个“检索 生成”的两段式架构。检索负责从海量文档里找到和问题最相关的片段生成负责把这些片段组织成通顺、准确的回答。它的价值不在于让模型变聪明而在于让模型的回答有据可查、可溯源、可更新。这也是为什么企业知识库、文档问答、客服助手这类场景特别偏爱 RAG——答案能指回原文用户信任度完全不一样。1.2 一套 RAG 系统的完整数据流很多人一上来就写代码结果跑到一半发现不知道哪一环出了问题。我建议先把整条链路在脑子里过一遍。一套标准的 RAG 系统分两个阶段离线索引和在线查询。离线索引阶段做三件事把原始文档PDF、Word、网页、Markdown 都行解析成纯文本把长文本切成一个个语义相对完整的小块chunk把每个小块通过嵌入模型转成向量存进向量数据库。这个阶段是一次性的文档更新时增量做就行。在线查询阶段也做三件事用户提问后把问题用同一个嵌入模型转成向量在向量库里做相似度搜索召回 Top-K 个最相关的 chunk把这些 chunk 拼进提示词模板连同问题一起发给大模型生成最终答案。这条链路里任何一个环节出问题都会导致最终回答拉胯。文档解析烂了后面全白搭切分切得稀碎检索出来的片段没有上下文嵌入模型选错语义相似度算不准召回数量 K 设得不合理要么漏信息要么塞一堆噪声。后面几节我会逐个环节拆开讲把每个环节的取舍逻辑和实操细节说透。1.3 本地化部署的动机与边界为什么强调“本地化”原因无非几个数据敏感文档不能出内网成本可控不想按 token 付费可控性强模型、嵌入、向量库全在自己手里出问题能查。本地化意味着你要自己扛起整条链路的算力模型得能跑在自己的机器上。这里要先泼盆冷水本地化不是万能的。如果你的机器只有集成显卡、内存 16G跑 7B 级别的模型做生成还行但嵌入模型和向量检索也会吃资源整体体验会比较勉强。我的经验是生成模型至少要有 8G 以上显存量化后 7B 模型能跑嵌入模型用小尺寸的比如 300M 以内的向量库用轻量的本地方案这样一套下来在消费级机器上能跑得动。如果硬件实在有限也可以把生成环节放到有算力的地方检索和索引留在本地做成混合架构这个后面会提。2. 文档解析与切分决定成败的隐形环节2.1 文档解析的坑比想象中多大部分人把注意力放在模型和向量库上结果栽在最不起眼的文档解析。PDF 是最典型的例子扫描版 PDF 没有文字层直接提取出来是空的得先做 OCR双栏排版的 PDF 提取出来文字顺序会乱左右栏内容交错在一起表格提取更是灾难行列结构丢失后变成一堆数字语义完全变了。我的处理原则是分类型对待。纯文本类Markdown、TXT、网页正文直接读最省心。Word 用对应的解析库提取段落注意保留标题层级因为标题对后续切分的语义完整性很重要。PDF 要先用工具判断有没有文字层没有就走 OCR有的话提取后还要做一次版面清理把页眉页脚、页码这些噪声去掉。表格单独处理能转成 Markdown 表格就转转不了就整块保留并加一句说明别让它被切碎。提示解析完的文本一定要人工抽查几段。我见过提取出来全是乱码还硬着头皮往下跑的后面检索效果差到怀疑人生回头才发现是解析阶段就烂了。2.2 切分策略固定长度还是语义切分切分是 RAG 里最容易被低估的环节。切太大一个 chunk 里混了好几个主题检索出来噪声多还浪费上下文窗口切太小一句话被拦腰截断语义不完整模型拿到手也拼不出意思。最朴素的做法是固定长度切分比如每 500 个字符一刀块之间留 50 字符重叠。重叠的作用是防止关键信息正好卡在切口上被切断前后两块都能沾到一点。这个方案简单粗暴对格式规整的文档够用但对结构复杂的文档就不行了。更讲究的是按语义结构切。Markdown 按标题层级切每个二级标题下的内容作为一个块超长再按段落细分代码文档按函数或类切问答类文档按一问一答切。这种切法能保证每个 chunk 语义自洽检索质量明显更好。我实测下来结构化切分比固定长度切分的召回准确率能高出一截代价是要针对不同文档类型写不同的切分逻辑。具体参数上chunk 大小我一般控制在 300 到 800 字符之间中文文档偏小值因为中文信息密度高。重叠比例取 chunk 大小的 10% 到 20%。这些不是死规定得根据你的文档特点和检索效果调。有个简单的判断方法随便抽几个 chunk 读一遍如果读起来像一段完整的话说明切得合适如果读起来莫名其妙那就是切坏了。2.3 元数据被忽视的检索增强利器每个 chunk 除了文本内容还应该带上元数据来源文件名、所属章节标题、页码、更新时间。这些信息在检索时能派上大用场。比如用户问“某产品的退款政策”你可以先用元数据过滤出产品文档再在里面做向量检索召回精度立刻提升。生成阶段把来源信息一起给模型模型回答时能注明出处用户一看就知道答案从哪来信任感完全不同。元数据的另一个用处是做增量更新。文档改了你通过元数据里的文件路径和更新时间就能定位到哪些 chunk 需要重建索引不用全量重跑。文档量大的时候这个优化能省下大量时间。3. 嵌入模型与向量库的选型逻辑3.1 嵌入模型怎么选才不踩雷嵌入模型负责把文本转成向量它的质量直接决定检索准不准。选型时看几个维度语言支持中文场景必须选中文或多语言效果好的、向量维度维度高表达能力强但存储和计算成本高、模型大小本地跑要考虑显存和速度、是否支持长文本有些模型对超过一定长度的输入会截断。本地化场景下我倾向于选参数量在 1 亿到 3 亿之间的多语言嵌入模型量化后几百兆CPU 也能跑速度可以接受。太大的模型虽然效果好一点但推理慢索引几万条文档时等待时间会让人抓狂。这里有个容易忽略的点嵌入模型和生成模型是两回事别想着用生成模型兼职做嵌入效果通常不如专门的嵌入模型而且慢。还有一个实操细节查询向量和文档向量必须用同一个嵌入模型生成。我见过有人索引时用一个模型、查询时换了另一个结果相似度算出来全是乱的排查了半天才发现是模型不一致。这个错误很低级但真的常见务必在代码里把模型路径写死别让两处配置漂移。3.2 向量库的本地化选择向量库的选择取决于数据规模和部署环境。数据量小几万条以内、单机部署用轻量级的本地向量库就够了它把向量存成文件加载进内存做暴力搜索简单可靠不需要额外服务。数据量上到几十万条暴力搜索会变慢这时候需要支持近似最近邻ANN索引的库用 HNSW 之类的算法把搜索复杂度降下来。选型时别只看性能还要看运维成本。有些向量库要单独起服务、配集群对个人项目来说太重了。我的建议是起步阶段用嵌入式方案数据量涨上来再迁移。迁移成本主要在重建索引只要你的索引脚本写得好换个库重跑一遍就行不算大事。存储方面向量本身占的空间不小。一个 768 维的向量用 float32 存是 3KB 左右十万条 chunk 就是 300MB加上原文和元数据整体在 GB 级别。规划磁盘时要把这部分算进去别到时候空间不够。3.3 相似度度量与 Top-K 的取舍向量检索的核心是算相似度常用的是余弦相似度和内积。余弦相似度只看方向不看长度对文本向量更合适因为文本长度差异不该影响语义相似判断。大部分嵌入模型训练时就是按余弦相似度优化的所以检索时保持一致就行。Top-K 是召回多少个 chunk 给生成模型。K 太小可能漏掉关键信息K 太大塞进一堆不相关的内容既浪费上下文窗口又干扰模型判断。我的经验是 K 取 3 到 5 起步根据效果调。如果发现答案经常缺信息适当加大 K如果答案经常被无关内容带偏就减小 K 或者加一个相似度阈值低于阈值的直接丢掉。这里有个进阶技巧召回之后加一步重排序。先用向量检索粗召回 20 条再用一个小的重排序模型对这 20 条精排取前 5 条给生成模型。重排序模型能捕捉查询和文档之间更细粒度的相关性实测对最终答案质量提升明显代价是多一次模型推理。本地化场景下重排序模型选小尺寸的几百兆跑起来不费劲。4. 本地化实操从零跑通一条链路4.1 环境准备与依赖安装先把环境搭起来。Python 是主流选择建议用虚拟环境隔离依赖避免版本冲突。核心依赖包括文档解析库处理 PDF、Word 等、嵌入模型推理库、向量库、以及调用本地生成模型的客户端。python -m venv rag_env source rag_env/bin/activate pip install pypdf python-docx sentence-transformers faiss-cpu上面这组是 CPU 环境的最小依赖。如果你有 GPU把 faiss-cpu 换成对应的 GPU 版本sentence-transformers 会自动用 GPU 加速嵌入计算。生成模型这边本地跑一般用支持量化推理的框架把模型权重下载到本地目录通过本地接口调用不依赖任何外部服务。注意依赖版本要锁死尤其是嵌入模型库和向量库版本不匹配时向量格式可能对不上报错信息还很隐晦。建议用 requirements.txt 固定版本号。4.2 索引构建的完整脚本索引构建是整个流程的地基我把它拆成解析、切分、嵌入、入库四步写成一条流水线。下面是一个可参考的骨架实际使用时按你的文档类型调整解析部分。from sentence_transformers import SentenceTransformer import faiss import numpy as np import json # 1. 加载嵌入模型本地路径 model SentenceTransformer(./models/embedding-model) # 2. 读取并切分文档这里用简化示例实际按文档类型处理 def load_and_split(path, chunk_size500, overlap80): with open(path, r, encodingutf-8) as f: text f.read() chunks [] start 0 while start len(text): end start chunk_size chunks.append(text[start:end]) start end - overlap return chunks chunks load_and_split(./docs/sample.md) # 3. 生成向量 embeddings model.encode(chunks, normalize_embeddingsTrue) embeddings np.array(embeddings).astype(float32) # 4. 建索引并保存 index faiss.IndexFlatIP(embeddings.shape[1]) # 内积配合归一化等价于余弦 index.add(embeddings) faiss.write_index(index, ./index/vector.index) # 5. 原文和元数据单独存 with open(./index/chunks.json, w, encodingutf-8) as f: json.dump([{id: i, text: c} for i, c in enumerate(chunks)], f, ensure_asciiFalse)这段代码里有两个关键点值得说。一是normalize_embeddingsTrue把向量归一化后内积就等于余弦相似度检索时用 IndexFlatIP 即可省去额外转换。二是原文和向量分开存向量库只负责相似度搜索返回的是 id再通过 id 去 chunks.json 里取原文。这样设计的好处是向量库可以随时换原文存储不受影响。4.3 查询与生成的串联查询阶段把用户问题转成向量检索出 Top-K拼提示词调本地生成模型。提示词模板的设计很关键直接影响回答质量。def retrieve(query, top_k4): q_vec model.encode([query], normalize_embeddingsTrue).astype(float32) scores, ids index.search(q_vec, top_k) with open(./index/chunks.json, r, encodingutf-8) as f: chunks json.load(f) return [(chunks[i][text], float(s)) for i, s in zip(ids[0], scores[0])] def build_prompt(query, contexts): ctx_text \n\n.join([f[片段{i1}] {c} for i, (c, _) in enumerate(contexts)]) return f你是一个严谨的问答助手。请仅根据下面提供的资料回答问题。 如果资料中没有相关信息直接回答资料中未提及不要编造。 资料 {ctx_text} 问题{query} 回答提示词里那句“仅根据资料回答、没有就说未提及”非常重要。不加这句模型很容易用自己的先验知识补充导致答案和资料对不上。加了之后回答的可控性明显提升。生成模型通过本地接口调用把 build_prompt 的结果传进去拿到返回文本即可。4.4 参数调优的实测记录参数不是拍脑袋定的我记录了一组实测数据供参考。测试集是 200 条内部文档问答评估指标是答案是否包含正确信息。chunk 大小重叠Top-K召回命中率备注30050372%切太碎上下文不足50080485%综合表现最稳800120481%部分块混入无关内容50080883%噪声增多提升有限从数据看chunk 500、重叠 80、Top-K 4 是这组文档的甜点区。但这不是通用答案你的文档结构、问题类型不同最优参数会漂移。建议自己搭一个小测试集几十条就够把参数网格跑一遍用数据说话比凭感觉靠谱得多。5. 检索效果差按这个顺序排查5.1 常见问题速查表RAG 系统跑起来容易跑好难。下面这张表是我踩坑后整理的排查顺序从高频到低频排列。现象可能原因排查动作答案完全跑题检索没召回相关内容打印召回的 chunk 看是否相关答案缺关键信息Top-K 太小或切分切断信息加大 K检查切分边界答案夹带无关内容召回噪声多加相似度阈值或重排序回答编造资料外内容提示词约束不够强化“仅根据资料”指令检索结果时好时坏嵌入模型与查询不一致核对两处模型路径中文检索效果差嵌入模型中文能力弱换多语言或中文优化模型排查的核心方法是把中间结果打出来看。很多人只看最终答案猜来猜去。正确做法是在检索后打印召回的 chunk 原文和相似度分数一眼就能看出是检索的问题还是生成的问题。检索召回的相关 chunk 里明明有答案模型却没答对那是提示词或生成模型的问题召回的 chunk 本身就不相关那是切分或嵌入的问题。定位到环节再对症下药。5.2 几个容易被忽略的实操心得第一个心得查询改写能显著提升召回。用户的问题往往口语化、指代多直接拿去检索效果一般。可以先用生成模型把问题改写成更完整、更书面化的检索式再去做向量检索。比如“那个退款咋弄”改写成“产品的退款流程和申请条件是什么”召回质量立刻不一样。这一步多一次模型调用但收益很大。第二个心得混合检索比纯向量检索稳。向量检索擅长语义匹配但对精确的关键词、编号、专有名词不敏感。加一路关键词检索比如 BM25两路结果融合能覆盖向量检索漏掉的情况。实测在包含大量产品型号、条款编号的文档上混合检索的召回率比纯向量高出一截。第三个心得定期重建索引。文档会更新嵌入模型也可能升级索引放久了会和实际文档脱节。我一般设一个周期任务检测文档变更后增量重建保证检索库和源文档一致。这个习惯能避免很多“明明文档里有却搜不到”的诡异问题。5.3 硬件吃紧时的降级方案不是每个人都有大显存的机器。硬件有限时可以这样降级嵌入模型选最小的多语言版本量化后几百兆CPU 推理也能接受向量库用内存版数据量控制在几万条生成模型用量化版本7B 模型量化到 4bit 后 8G 显存能跑再不行就用更小的模型或者把生成环节放到有算力的地方检索和索引留在本地。这种混合架构在数据敏感场景里很实用——敏感文档不出本地只有脱敏后的检索片段参与生成。降级的代价是效果和速度要有心理预期。我的建议是先把链路跑通再根据实际瓶颈逐步升级硬件或换更大的模型别一上来就追求顶配容易在环境配置上耗光热情。6. 从能跑到好用几个进阶方向链路跑通只是起点真正拉开差距的是细节打磨。第一个方向是查询理解除了前面说的查询改写还可以做意图分类不同类型的问题走不同的检索策略比如事实型问题走精确检索开放型问题走宽召回。第二个方向是上下文压缩召回的 chunk 里往往只有一两句话真正相关把无关部分裁掉再给模型既省窗口又减噪声。第三个方向是答案溯源把生成答案里引用的片段标出来用户点击能跳回原文这个功能在知识库场景里体验提升非常明显。还有一个值得投入的方向是评估体系。没有评估就没有优化方向。搭一个小规模的测试集覆盖典型问题和边界情况每次改动后跑一遍看指标是涨是跌。这套东西前期花点时间后期调参、换模型、改切分策略时能帮你省下大量试错成本。我见过太多人凭感觉调 RAG改了半天不知道到底有没有变好有了评估集一切用数据说话。这套本地 RAG 方案我在几台不同配置的机器上都部署过最深的体会是模型和框架的选择固然重要但真正决定效果的往往是文档解析、切分策略、提示词约束这些“脏活累活”。把这些基础环节做扎实哪怕用中等尺寸的模型效果也能打得过配置豪华但细节粗糙的方案。后续如果文档量继续涨我会优先考虑把向量库换成支持 ANN 索引的方案再引入重排序一步步来不追求一步到位。