做RAG问答库这件事我踩过不少坑。网上教程看着简单真要把 LangChain 各环节串起来做一个能直接跑、能回答、还能给出处的 langchain-rag-chat 项目远不是写二十行代码能搞定的。所以我把这套东西整理成一个开箱即用的 RAG 问答库文档放进 data 目录、改一下配置文件就能把本地文档变成一个对话式知识库。这篇记录从需求拆解、技术选型到架构设计和实操排障的全过程适合刚开始接触 RAG 的开发者也适合想把 LangChain 项目真正落地成内部工具的人参考。1. 项目定位langchain-rag-chat 到底在解决什么问题很多 RAG 示例项目的问题在于“能演示但没法用”。演示版通常只有一个 Notebook 脚本加载几段英文文本问一句就完事。但你一旦换成自己的中文文档库换成长 PDF、带图表的简历、或者几十个分散的 Markdown 文件问题会一个接一个冒出来。langchain-rag-chat 要解决的是尽量把这些问题挡在项目结构之外加载器按文件格式分流、切分器针对中文优化、检索器内置多样性控制、问答服务通过 HTTP 接口暴露前端页面可以直接提问。拿到的就是一个不需要再拼装的工程雏形。1.1 RAG 知识库与结构知识库的边界与应用场景先说清楚一个经常被混淆的概念RAG 知识库不等于“知识库”。RAG 知识库处理的是非结构化文本比如产品文档、客服聊天记录、维基页面、技术手册。它的工作方式是把文本切块、向量化问问题时找到语义相近的片段再让大模型根据这些片段生成回答。它擅长“开放式理解”例如“我们的退款政策里有没有提到运费谁承担”即使这句话在文档里写得七零八落也能拼出答案。结构知识库则是另一套体系典型代表是关系型数据库、图数据库、业务规则引擎。它们要求数据有字段、有类型、有关系查询结果必须是确定性的。你问“上个月华东区的退款总额是多少”RAG 知识库给不了你但 SQL 可以精确给出。结构知识库适合财务报表、订单查询、合规校验这类对精度要求极高的场景不适合“帮我介绍一下这个系统有什么功能”这种模糊问题。那实际项目怎么选我的判断标准是三条数据形态是长文本还是结构化字段问题类型是模糊理解还是精确查询回答错误是不是不可接受。产品手册问答、内部制度检索、客服自动应答用 RAG指标查询、权限判断、库存盘点用结构知识库。两者也不互斥更成熟的架构是先 RAG 定位文档再从结构化库里取权威数据最后由大模型综合成答案。langchain-rag-chat 目前聚焦 RAG 侧但业务接入点留好了后续接 SQL 检索也不冲突。场景推荐方案原因客服 FAQ 知识库RAG 知识库答案在散落手册里需要语义理解财务精确报表结构知识库(SQL)必须是确定聚合结果产品操作手册问答RAG 知识库长文本、用户问题表达不确定风控规则命中判断结构知识库(规则引擎)判断路径必须可审计企业混合问答RAG 结构化查询先定位材料再取权威数据1.2 框架选型LangChain、Dify、CrewAI 怎么选很多人在博客和群里问“agent框架比如 LangChain、Dify、CrewAI 哪个好”这种问题其实没有标准答案只有适不适合。Dify 走的是低代码、可视化工作流路线业务人员拖拽节点可以快速搭出一个带知识库的对话应用上线很快但如果要精细控制检索逻辑、深度定制 prompt、或者和现有服务单元做底层集成它能动的空间就比较有限。CrewAI 核心是智能体编排擅长让多个大模型角色协作完成任务例如“一个角色检索资料、一个角色写方案、一个角色审稿”但 RAG 的检索能力和文档处理生态不是它的强项。LangChain 的特点是中层库属性很强它不逼着你用它的一整套封装组件可以单独拆出来用。我在这个项目里选 LangChain 的直接原因有三点第一文档加载、文本切分、向量存储这三层都有成熟的社区实现接入成本低第二它的 retriever 抽象让后续替换向量库、调整检索策略时不用重写业务代码第三LangChain 生态对 OpenAI、各类本地模型、Chroma、FAISS 都支持良好正好覆盖我需要验证的多种组合。代价是学习曲线陡一点API 版本变动快需要锁定官方版本。所以我的态度是想快速做产品验证去用 Dify想学原理、想深度定制、想把 RAG 作为服务提供给团队LangChain 更靠谱。1.3 “开箱即用”的四种含义我对开箱即用有四个验收标准缺一个都不能叫开箱即用。第一数据准备要简单。用户不需要写代码处理文件格式丢进 data 目录就行系统自动按扩展名选加载器。第二配置要实现单文件化。模型类型、切分大小、检索数量全部集中在 config.yaml改配置比改代码容易十倍。第三启动步骤要少于三条命令。构建索引一条启动服务一条。第四交互界面要能直接看结果。我加了 Web 页面避免使用者每次都要用 curl 去调接口。有人会觉得这些事“很基础”但就是这些基础环节决定了一个项目是停留在“GitHub Star 收藏夹”还是真正被人跑起来。2. 整体架构拆解一条 RAG 链路的关键环节RAG 的标准链路是文档加载、文本切分、向量化、向量存储、检索召回、生成回答。每段链路都有它的坑。我当初的第一版就是照着别人代码糊出来的以为只要“向量库 大模型”就能跑通结果问答效果惨不忍睹。后来把链路逐段拆开调试才明白后面出的问题往往根源在前面环节而不是模型不够强。2.1 文档加载与切分切得好不好直接决定检索上限加载这一步看似简单其实最容易漏。我支持了 txt、markdown、pdf 三类文件分别走 TextLoader 和 PyPDFLoader。PDF 又坑最多很多 PDF 是扫描件没有文本层加载出来是一堆空字符串还有排版分栏的文档读取顺序错乱语义会断。数据加载的质量上限决定了整个知识库回答质量的上限这条原则要时刻记住。切分就需要认真调参数了。我用的 RecursiveCharacterTextSplitter核心参数是 chunk_size 和 chunk_overlap。项目里默认 chunk_size500、chunk_overlap80这是从经验出发的起点chunk 太短容易把一段完整逻辑拦腰截断回答就少了关键细节chunk 太长一是 embedding 平均后语义不聚焦二是塞进 prompt 会占用大量 token。overlap 在这里起的是“缝合”作用相当于在相邻两块之间重复保留上一块末尾的上下文避免在句子中间硬切。用生活里的场景类比就像给一本厚厚的书做书签每一段都多保留前一页的最后几行方便你顺着思路接下去。这里有个特别容易踩的坑默认的 separators 是按英文习惯设计的。处理中文文档时我用的是[。\n, , , \n\n, \n, , ]保证尽可能在完整句子后断开而不是按英文句号或者空格去切。如果你发现自己知识库的回答“前言不搭后语”先检查切分出来的片段是不是大量以逗号收尾十有八九是分隔符没做中文化。2.2 向量化与向量存储embedding 是 RAG 的隐形瓶颈embedding 模型决定了“检索上限”。大家都喜欢讨论大模型但一个 RAG 系统里真正拉开体验差距的往往是 embedding 模型。如果 embedding 模型对中文理解不好你的文档切得再漂亮检索时也找不回正确答案后面的 LLM 再强也是无米之炊。我第一版直接用了通用的英文 embedding 模型跑中文文档结果搜索“售后政策”召回回来的都是无关段落后来换成对中文优化更好的模型效果立刻不一样。项目里默认配置是 OpenAI 的 text-embedding-3-small维度 1536成本低、质量稳定、适合快速验证。如果要求数据不能出内网可以切换到本地模型比如 BGE-M3 这类国产开源模型维度 1024中文效果很不错还支持多语言。选型时的判断依据是要不要离线部署、数据隐私等级、中文占比、以及跟检索模块的兼容性。向量存储我用的 Chroma主要理由是轻量、纯本地持久化、无需额外服务。数据构建时把向量写进 ./db 目录服务启动时再读出来不需要单开数据库进程。小到几 MB 的文档大到几百 MB 的语料Chroma 都扛得住。真正千万级以上的规模再考虑更重的向量数据库现阶段没必要让基础设施复杂化。embedding 方案维度适合场景备注text-embedding-3-small1536快速验证、通用场景API 调用成本低text-embedding-3-large3072对质量要求高的检索API 调用成本更高BGE-M31024中文为主、离线部署开源可本地跑其他中文 embedding各地不同特定领域文档需要实测比对2.3 检索与生成召回精度、多样性、引用溯源从向量库检索的时候单纯用 top-k 相似度有一个问题返回的 k 条结果可能内容高度相似比如十条里有六条都在讲同一段剩下有用信息被挤掉。这个问题叫“召回多样性不足”。我在这里用了 MMR 检索也就是最大边际相关性它会在“和问题相关”与“和已有结果不相似”之间做平衡让返回的段落覆盖面更广。Top-K 参数设多少也要看语料。项目默认 k5如果文档本身内容碎片化严重可以调到 8如果知识库都是长文章5 就够了。太小的 k 会让回答缺少依据太大的 k 会把不相关的内容塞进 prompt反而是噪音。这里没有绝对正确跑几轮测试看看效果再调。生成侧我做了三件事第一将检索到的片段连同来源 metadata 一起拼进 prompt来源信息形如“文件名 章节”让模型生成回答时能参考出处第二在 System Prompt 里明确约束“只能根据上下文回答上下文里没有就明确说不知道”这一句能大幅减少胡编乱造第三回答末尾要求注明来源方便用户对照原始文档验证。很多人觉得 RAG 有幻觉是大模型的问题其实多半是没把“仅凭上下文作答”这条约束写死。3. 实操搭建从空目录到第一次问答这章是动手部分。我按项目实际目录结构来讲解尽量把每个文件的作用说明白这样你不仅能跑通还能在跑通的基础上改造。3.1 环境准备Mac 与 Linux 的注意事项建议用 Python 3.11虚拟环境隔离依赖是个好习惯别图省事直接装进全局环境。Linux 上直接创建虚拟环境即可Mac 上有一点需要注意如果系统自带的是 Python 3.9 之类旧版本建议先用 Homebrew 装一个独立的 Python 3.11再基于它创建虚拟环境避免 Apple 自带的 Python 干扰依赖解析。# Linux / macOS python3.11 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip wheel pip install -r requirements.txtMac 的 Apple Silicon 芯片在安装一些基础依赖时基本没什么大问题但如果遇到个别包编译报错可以先把 Xcode Command Line Tools 更新到最新版本。这类问题通常不复杂卡住了先看编译日志别急着换 Python 版本。项目依赖集中在 requirements.txt 里langchain0.2 langchain-community langchain-openai langchain-chroma pypdf fastapi uvicorn python-dotenv chromadb如果使用 OpenAI 接口的模型在项目根目录创建一个 .env 文件把 API Key 填进去如果使用本地模型服务则在 config.yaml 里替换模型配置和 base_url。3.2 项目结构与核心代码实现项目结构如下langchain-rag-chat/ ├── app.py # FastAPI 服务 ├── config.yaml # 核心配置 ├── requirements.txt ├── data/ # 放原始文档 ├── db/ # 向量库持久化目录 ├── src/ │ ├── loader.py # 文档加载 │ ├── ingest.py # 构建索引 │ ├── retriever.py # 检索器 │ └── llm.py # 问答链 └── web/ └── index.html # 网页问答界面config.yaml 是所有参数的集中地data_dir: ./data vector_db_dir: ./db chunk_size: 500 chunk_overlap: 80 k: 5 embedding_provider: openai embedding_model: text-embedding-3-small llm_model: gpt-4o-mini temperature: 0.0loader.py 负责按扩展名加载不同格式from pathlib import Path from langchain_community.document_loaders import TextLoader, PyPDFLoader def load_documents(data_dir: str): docs [] for path in Path(data_dir).rglob(*): if path.suffix.lower() in (.txt, .md): loader TextLoader(str(path), encodingutf-8) elif path.suffix.lower() .pdf: loader PyPDFLoader(str(path)) else: continue docs.extend(loader.load()) return docsingest.py 负责把文档切块后写入向量库import yaml from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma from loader import load_documents with open(config.yaml) as f: config yaml.safe_load(f) docs load_documents(config[data_dir]) splitter RecursiveCharacterTextSplitter( chunk_sizeconfig[chunk_size], chunk_overlapconfig[chunk_overlap], separators[。\n, , , \n\n, \n, , ], ) chunks splitter.split_documents(docs) print(f文档切分完成共 {len(chunks)} 个片段) embeddings OpenAIEmbeddings(modelconfig[embedding_model]) vectorstore Chroma.from_documents( documentschunks, embeddingembeddings, persist_directoryconfig[vector_db_dir], ) print(向量索引构建完成)retriever.py 里使用 MMR 检索from langchain_chroma import Chroma from langchain_openai import OpenAIEmbeddings def get_retriever(config): embeddings OpenAIEmbeddings(modelconfig[embedding_model]) vectorstore Chroma( embedding_functionembeddings, persist_directoryconfig[vector_db_dir], ) return vectorstore.as_retriever( search_typemmr, search_kwargs{k: config[k]}, )llm.py 组装 prompt 和生成逻辑from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI SYSTEM_TEMPLATE ( 你是一个知识库问答助手。请只根据下面的上下文回答用户问题。 如果上下文中没有相关答案请回答知识库中没有找到相关信息。 回答末尾需要注明参考来源。 ) prompt_template ChatPromptTemplate.from_messages([ (system, SYSTEM_TEMPLATE), (human, 上下文\n{context}\n\n问题{question}), ]) def create_chain(config, retriever): llm ChatOpenAI(modelconfig[llm_model], temperatureconfig[temperature]) def run(question: str): docs retriever.invoke(question) context \n\n.join( f[来源: {doc.metadata.get(source, 未知)}]\n{doc.page_content} for doc in docs ) prompt prompt_template.invoke({context: context, question: question}) response llm.invoke(prompt) return response.content return runapp.py 提供 HTTP 接口from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel import yaml from src.retriever import get_retriever from src.llm import create_chain app FastAPI() app.add_middleware(CORSMiddleware, allow_origins[*], allow_methods[*], allow_headers[*]) with open(config.yaml) as f: config yaml.safe_load(f) chain create_chain(config, get_retriever(config)) class QueryBody(BaseModel): question: str app.get(/health) def health(): return {status: ok} app.post(/query) def query(body: QueryBody): answer chain(body.question) return {answer: answer}web/index.html 就是一个纯静态页面fetch 调用/query接口问题输入框和回答展示区就完成了。前端代码这里不展开核心逻辑就是当用户点击提问时发 POST 请求收到回答后渲染到页面上。3.3 启动与验证用一份真实文档做端到端测试构建向量索引前先确保文档已经在 data 目录里cp /path/to/your/manual.pdf data/ python src/ingest.py构建索引这一步会输出切分后的总片段数这个数字值得记下来。如果几十页文档最后只有几个 chunk说明加载或切分有严重问题如果几千个小到不行的片段说明 chunk_size 太小或者 separator 断得太碎。都正常的话就可以启动服务uvicorn app:app --reload验证接口用 curl 就行curl -X POST http://localhost:8000/query \ -H Content-Type: application/json \ -d {question: 这个系统支持哪些文档格式}我经常用这种方式在调试时验证检索质量先看回答再对比回答引用的来源是不是真的相关。如果回答引用的来源不对那问题不在生成层而在检索层需要回到切分和 embedding 去调整。4. 常见问题与排查技巧实录跑通只是开始调优才是真正让人头疼的部分。我把实际使用中碰到的高频问题和排查思路整理在这里。4.1 回答像在胡编RAG 检索质量瓶颈的排查顺序很多人看到 RAG 回答乱编第一反应是“换个更大的模型”。但更常见的病因在检索侧。按下面的顺序排查效率最高。先打印检索结果。把问题喂给 retriever看看 top-k 到底召回的是不是相关片段。这一步能快速区分是“没找对”还是“找对了但生成错了”。如果检索结果就不相关继续看切分。把召回片段打印出来后看看内容是不是在句子中间被截断逻辑是否完整。不完整就把 chunk_size 调大一点、规范 separator。再看 embedding 模型。拿几个相似语义的中文句子直接测相似度如果相近词的分也不高换中文优化模型。最后才看 prompt。检查有没有显式约束“只能根据上下文回答”没有就加。重排器是我的经验里效果最显著的增强手段。普通向量召回考虑的是语义粗略匹配而 CrossEncoder 这类重排模型会把“问题和段落”拼在一起精细打分。如果预算允许在向量召回 top-20 之后加一个重排阶段取 top-3回答质量会有肉眼可见的提升。这个项目里没有默认集成重排但 retriever 接口留好了二次处理的位置扩展并不难。4.2 问题排查速查表症状可能原因建议排查方向检索召回明显不相关文档未加载成功打印 docs 数量检查加载器是否识别格式回答上下文断裂切分时把语义切断调大 chunk_size加 overlap检查中文分隔符中文回答质量差embedding 对中文支持弱切换到中文优化模型多条结果内容重复只用相似度检索改成 MMR 检索模型回答超出文档范围缺少“仅根据上下文”约束加强 prompt 约束并降低温度引用来源乱写metadata 缺失或 prompt 未要求来源检查加载时是否保留 source加入来源指令构建索引很慢embedding API 并发不足批量处理或换本地模型4.3 RAG 知识库能存图片吗多模态数据的处理思路这是一个被反复问到的问题。坦白说传统 RAG 链路默认不支持图片。文档里的图片在切分阶段会被直接忽略图片中的图表、截图、表格信息全都会丢掉。如果你处理的文档包含大量图表RAG 回答几乎一定存在“信息盲区”。有三条路线可以处理图片按成本从低到高排序。第一条是 OCR 转文字。对扫描版 PDF 或者含文字的图片用 OCR 工具把文字提取出来再作为文本送入 RAG。优点是实现简单、兼容现有链路缺点是对流程图、趋势图这类非纯文字型图片无能为力提取出来的表格结构也容易乱。第二条是多模态模型生成描述。让视觉语言模型看一遍图片生成一段文本描述再把描述存进知识库。适合“这张架构图的整体设计思路是什么”这类问题缺点是需要多一次模型调用且描述质量决定后续检索效果。第三条是图片向量化。用多模态 embedding 模型把图片直接映射为向量支持“找一张体现用户登录流程的图”这种跨模态检索工程复杂度最高一般项目不用一上来就做。对这个项目我给的落地建议很直接如果你的语料以技术手册为主第一优先做 OCR把图片里的文字抢救出来如果图片主要是架构图、流程图训练集又不规则跑一轮多模态模型描述也能覆盖大部分需求。图片本身存储这个需求脱离“怎么把图片内容变可检索”去聊没有意义。4.4 在 Mac 上搭建 RAG 知识库的实操要点Mac 上跑这套流程整体顺利但有几个实操注意点值得记录一下。第一Python 版本管理。用 Homebrew 安装 Python 3.11不要依赖系统自带的 Python。第二虚拟环境是必须的你想在这个项目里反复换 langchain 版本如果没有虚拟环境隔离依赖冲突会把人逼疯。第三本地模型跑 embedding 的话CPU 推理速度基本够用尤其是 BGE-M3 这类小模型在 M 系列芯片上速度并不差但如果你想在本地跑大语言模型先把内存大小想清楚几十 GB 参数的模型很容易把 16GB 内存吃满建议在 Mac 上用 API 方式调模型服务而不是硬扛本地推理。另一个常见的困惑是“为什么我装了依赖import 还报错”。这大概率是当前虚拟环境没生效或者 pip 装到了全局。启动任何脚本前先which python确认路径指向.venv能省下很多排查时间。结语一点个人体会项目跑通之后我最大的体会是RAG 工程里 80% 的时间花在数据清洗、切分调整和检索调优上真正调用大模型生成回答反而是最省心的一步。很多人以为“开箱即用”就是什么都调好了实际上它应该是“给你一个稳定的起点”后面的效果还需要基于你自己的语料去调。从一个小的文档集开始先验证链路能通再一点点扩展数据量是性价比最高的做法。最后再分享一个小技巧每次调整切分参数或者更换 embedding 模型后保存一个固定的测试集里面放三五条你希望知识库能准确回答的问题。每次改动跑一遍测试集比对回答质量而不是凭感觉看单个结果。这样你的优化才有方向也更容易知道是哪一环在拖后腿。langchain-rag-chat 这个项目后面要扩展的方向我自己列了三个多轮对话记忆、重排器引入、按文档类型动态切分策略。任何一个做扎实都比再加一堆花哨功能更实用。
