RAG落地踩坑实录从Demo到生产的差距有多大如果前 11 篇教你的是怎么做那这一篇要讲的是做的时候会怎么死。我把一个企业RAG知识库从 Demo 推到生产用了三个多月。这三个月里踩的坑比前面十篇文章加起来还多。挑三个最痛的希望能帮你省点医药费。大家好我是黒漂技术佬。教训一“先做个 Demo 看看效果” → 三个月后还在做 Demo这是我犯的第一个也是最贵的错误。刚接触 RAG 的时候我用 LangChain Chroma OpenAI API一天就跑通了 Demo。老板问能上线吗我说“再优化一下两周吧。”然后两周变一个月一个月变三个月。原因是Demo 和生产的差距不在核心链路上而在边界条件上。Demo 能处理生产必须处理1 份干净的 PDF200 份格式各异的文档PDF/Word/飞书/扫描件用户规规矩矩地问“就上次那个啥来着……”所有数据公开可见不同部门看不同文档一个人用100 个人同时用出错了重跑就行有监控、有告警、有回滚Python 脚本部署容器、日志、备份我踩的具体坑坑 1.1LangChain 的 API 变动堪比川剧变脸2024 年下半年开始LangChain 经历了一次大规模 API 重构。从from langchain.vectorstores import Chroma变成了from langchain_chroma import Chroma从RetrievalQA变成了create_retrieval_chain回调机制、内存管理、输出解析器的写法全变了。一个月前写的 Demo 代码更新依赖后直接跑不起来。StackOverflow 上的答案 70% 已经过期。教训如果你的生产系统依赖 LangChain锁定版本锁定版本锁定版本# requirements.txtlangchain0.2.0 langchain-community0.2.0 langchain-chroma0.1.1正确的路径第 1 周用 APIDeepSeek SiliconFlow跑通 Demo验证可行性 第 2-3 周替换为本地部署bge Embedding Milvus切掉外部依赖 第 4-5 周加权限、安全、监控、限流 第 6 周内部灰度测试收反馈 第 7-8 周修 Bug、优化检索、优化 Prompt 第 9 周全量上线核心原则MVP 不是最简 Demo而是能解决一个真实问题的最小版本。教训二Prompt 优化靠玄学 → 浪费了整整一周我们上线的第一个版本回答质量波动很大。同一个问题有时候答得像专家有时候像个智障。我翻了各种教程试了角色设定、“思维链Chain of Thought”、“Few-shot 示例”、“让 LLM 自己反思”……Prompt 越写越长效果却没有显著提升。后来冷静下来我做了一件很简单的事把 100 个错误回答打出来逐条分析归类。结果发现根因分析100 个错误回答 ──────────────────────────────────── 64% 检索根本就没搜到相关内容不是 Prompt 的锅 22% 检索搜到了但 LLM 没用上上下文太长被截断了 9% 文档本身信息不完整或矛盾 5% LLM 理解错了结论我花了一周调 Prompt结果只覆盖了 5% 的问题。真正的大头在检索和文档质量。正确的调优顺序1. 先看检索质量70% 的问题在这 → 调整 chunk_size、chunk_overlap → 加 Query 改写 → 上混合检索 2. 再看上下文管理15% 的问题在这 → Top-K 不是越大越好用 Reranker 精简 → 给最相关的文档块放前面 3. 最后才调 Prompt5% 的问题 → 系统指令清晰 → 强制标注引用来源 → 设定不知道就说不知道教训三文档更新不同步 → 用户发现一个 Bug 我掉一层皮我们的第一批知识库有 150 份文档。HR 更新了《员工手册》但知识库里还是旧版。有员工按 AI 的回答请了 10 天年假结果 HR 说新制度改成 7 天了。这就尴尬了。文档管理的三个层次层次做法延迟手动改了文档→手动重新上传→触发重建忘了就永远不同步半自动CMS 改了文档→Webhook通知→自动重建5~10 分钟全自动文档托管在 Git/Confluence→定时同步→增量更新接近实时我们最终的方案——基于 Git 的文档管理公司所有文档 → Git 仓库Markdown 格式 │ │ git push 触发 Webhook ▼ 文档同步服务 ├── 检测变更的文件git diff ├── 删除旧版 chunks ├── 重新解析、分块、Embedding 变更的文件 └── 增量更新 Milvus# 增量更新逻辑defsync_updated_docs(changed_files:list):forfile_pathinchanged_files:# 1. 删除旧版本的所有 chunksvectorstore.delete(filter{source:file_path})# 2. 重新解析、分块new_chunkspipeline.process(file_path)# 3. 插入新 chunksvectorstore.insert(new_chunks)# 4. 做一次健康检查搜几个典型问题看回答是否正常run_health_check()增量更新的好处150 份文档里只更新了 1 份不需要全量重跑。全量重跑一次可能要几个小时增量更新几秒钟搞定。其他小坑速览PDF 里有扫描件混在文字页里同一个 PDF第 1-5 页是文字第 6 页突然是扫描的表格。解析器需要按页检测是否需要 OCR。Embedding 模型的中文分词不靠谱“会长”名词协会的会长和会长动词会变长在 BERT 的分词里经常被当成同一个词导致歧义句的检索完全跑偏。用户会复制粘贴大段文字当问题有人会把整封邮件贴进提问框。这种问题不能做 Query 改写也不能原样 Embedding——要先做问题提取用 LLM 把大段文字中的核心问题抽出来。LLM API 超时需要降级大模型 API 有概率性超时尤其是高峰时段。必须做重试1次和降级返回系统繁忙请稍后重试不能直接报错让用户看到堆栈。最后的总结从 Demo 到生产的桥梁不是技术是耐心做企业 RAG 知识库这件事技术上没有哪一步是特别难的。真正难的是把 100 件小事都做对。文档的格式处理、权限的细粒度控制、检索的持续优化、用户的反馈闭环、文档的增量更新——每一项单拎出来都不难加在一起就变成了真正的产品。我是黒漂技术佬。这个系列的最后一篇我会聊聊更前沿的方向——AI Agent RAG企业知识库的下一步进化在哪里。
RAG落地踩坑实录：从Demo到生产的差距有多大？
RAG落地踩坑实录从Demo到生产的差距有多大如果前 11 篇教你的是怎么做那这一篇要讲的是做的时候会怎么死。我把一个企业RAG知识库从 Demo 推到生产用了三个多月。这三个月里踩的坑比前面十篇文章加起来还多。挑三个最痛的希望能帮你省点医药费。大家好我是黒漂技术佬。教训一“先做个 Demo 看看效果” → 三个月后还在做 Demo这是我犯的第一个也是最贵的错误。刚接触 RAG 的时候我用 LangChain Chroma OpenAI API一天就跑通了 Demo。老板问能上线吗我说“再优化一下两周吧。”然后两周变一个月一个月变三个月。原因是Demo 和生产的差距不在核心链路上而在边界条件上。Demo 能处理生产必须处理1 份干净的 PDF200 份格式各异的文档PDF/Word/飞书/扫描件用户规规矩矩地问“就上次那个啥来着……”所有数据公开可见不同部门看不同文档一个人用100 个人同时用出错了重跑就行有监控、有告警、有回滚Python 脚本部署容器、日志、备份我踩的具体坑坑 1.1LangChain 的 API 变动堪比川剧变脸2024 年下半年开始LangChain 经历了一次大规模 API 重构。从from langchain.vectorstores import Chroma变成了from langchain_chroma import Chroma从RetrievalQA变成了create_retrieval_chain回调机制、内存管理、输出解析器的写法全变了。一个月前写的 Demo 代码更新依赖后直接跑不起来。StackOverflow 上的答案 70% 已经过期。教训如果你的生产系统依赖 LangChain锁定版本锁定版本锁定版本# requirements.txtlangchain0.2.0 langchain-community0.2.0 langchain-chroma0.1.1正确的路径第 1 周用 APIDeepSeek SiliconFlow跑通 Demo验证可行性 第 2-3 周替换为本地部署bge Embedding Milvus切掉外部依赖 第 4-5 周加权限、安全、监控、限流 第 6 周内部灰度测试收反馈 第 7-8 周修 Bug、优化检索、优化 Prompt 第 9 周全量上线核心原则MVP 不是最简 Demo而是能解决一个真实问题的最小版本。教训二Prompt 优化靠玄学 → 浪费了整整一周我们上线的第一个版本回答质量波动很大。同一个问题有时候答得像专家有时候像个智障。我翻了各种教程试了角色设定、“思维链Chain of Thought”、“Few-shot 示例”、“让 LLM 自己反思”……Prompt 越写越长效果却没有显著提升。后来冷静下来我做了一件很简单的事把 100 个错误回答打出来逐条分析归类。结果发现根因分析100 个错误回答 ──────────────────────────────────── 64% 检索根本就没搜到相关内容不是 Prompt 的锅 22% 检索搜到了但 LLM 没用上上下文太长被截断了 9% 文档本身信息不完整或矛盾 5% LLM 理解错了结论我花了一周调 Prompt结果只覆盖了 5% 的问题。真正的大头在检索和文档质量。正确的调优顺序1. 先看检索质量70% 的问题在这 → 调整 chunk_size、chunk_overlap → 加 Query 改写 → 上混合检索 2. 再看上下文管理15% 的问题在这 → Top-K 不是越大越好用 Reranker 精简 → 给最相关的文档块放前面 3. 最后才调 Prompt5% 的问题 → 系统指令清晰 → 强制标注引用来源 → 设定不知道就说不知道教训三文档更新不同步 → 用户发现一个 Bug 我掉一层皮我们的第一批知识库有 150 份文档。HR 更新了《员工手册》但知识库里还是旧版。有员工按 AI 的回答请了 10 天年假结果 HR 说新制度改成 7 天了。这就尴尬了。文档管理的三个层次层次做法延迟手动改了文档→手动重新上传→触发重建忘了就永远不同步半自动CMS 改了文档→Webhook通知→自动重建5~10 分钟全自动文档托管在 Git/Confluence→定时同步→增量更新接近实时我们最终的方案——基于 Git 的文档管理公司所有文档 → Git 仓库Markdown 格式 │ │ git push 触发 Webhook ▼ 文档同步服务 ├── 检测变更的文件git diff ├── 删除旧版 chunks ├── 重新解析、分块、Embedding 变更的文件 └── 增量更新 Milvus# 增量更新逻辑defsync_updated_docs(changed_files:list):forfile_pathinchanged_files:# 1. 删除旧版本的所有 chunksvectorstore.delete(filter{source:file_path})# 2. 重新解析、分块new_chunkspipeline.process(file_path)# 3. 插入新 chunksvectorstore.insert(new_chunks)# 4. 做一次健康检查搜几个典型问题看回答是否正常run_health_check()增量更新的好处150 份文档里只更新了 1 份不需要全量重跑。全量重跑一次可能要几个小时增量更新几秒钟搞定。其他小坑速览PDF 里有扫描件混在文字页里同一个 PDF第 1-5 页是文字第 6 页突然是扫描的表格。解析器需要按页检测是否需要 OCR。Embedding 模型的中文分词不靠谱“会长”名词协会的会长和会长动词会变长在 BERT 的分词里经常被当成同一个词导致歧义句的检索完全跑偏。用户会复制粘贴大段文字当问题有人会把整封邮件贴进提问框。这种问题不能做 Query 改写也不能原样 Embedding——要先做问题提取用 LLM 把大段文字中的核心问题抽出来。LLM API 超时需要降级大模型 API 有概率性超时尤其是高峰时段。必须做重试1次和降级返回系统繁忙请稍后重试不能直接报错让用户看到堆栈。最后的总结从 Demo 到生产的桥梁不是技术是耐心做企业 RAG 知识库这件事技术上没有哪一步是特别难的。真正难的是把 100 件小事都做对。文档的格式处理、权限的细粒度控制、检索的持续优化、用户的反馈闭环、文档的增量更新——每一项单拎出来都不难加在一起就变成了真正的产品。我是黒漂技术佬。这个系列的最后一篇我会聊聊更前沿的方向——AI Agent RAG企业知识库的下一步进化在哪里。
