用LangChain搭建开箱即用的RAG知识库问答系统实战

前阵子我们团队整理了一套内部技术文档，零零散散小一百篇，散落在共享盘、语雀和Notion里。新人入职要翻一天，老人回答重复问题翻到崩溃。我花了一个周末，用 LangChain 拼了一个开箱即用的 RAG 问答库，起名 langchain-rag-chat，现在团队问答效率高了不少。这篇文章把这个项目的完整实现拆给你看，从选型到踩坑，能直接抄作业。

这个项目只做一件事：把一批本地文档变成可对话的知识库。你扔进去 PDF、 Markdown、TXT，它替你完成切分、向量化、检索、生成，最后暴露一个 HTTP 接口，前端随便接就能用。适合已经熟悉 Python 基础、想快速落地 RAG 问答案例的开发者，也适合要给团队搭内部知识库的工程同学。

1. 项目定位：RAG 问答库到底解决了什么问题

1.1 大模型幻觉之外，还有数据实时性和权限问题

先说一个常见误区：很多人以为知识库问答就是把文档塞给大模型。实际上直接塞文本进去既不现实也不安全——你没法把几百兆的文档全塞进上下文窗口，也不能让模型背诵公司内部资料。RAG 的价值在于“按需检索”：用户提问时，先从库里检索最相关的几段文本，再让模型基于这些文本作答。这样生成内容有凭有据，模型不会凭空编造，文档更新后也不需要重新训练模型，改库就行。

RAG 同时解决了私有数据隔离的问题。基础模型只见过公开语料，公司内部文档、产品手册、个人笔记这些数据如果直接进模型上下文，就有泄露风险；而 RAG 模式下只有当前问题命中的片段会被传出去，控制面清晰很多。

1.2 为什么“开箱即用”是关键

LangChain 社区里 RAG 教程不少，但绝大多数要么只讲单机 Jupyter 演示，要么一步跳进 LangGraph、Agent 这些复杂框架，新手直接劝退。我把目标定成“开箱即用”，意思是三条命令以内能跑起来，接口、配置、向量库初始化全给默认值，但默认值不是拍脑袋定的，背后都有取舍逻辑。

• 向量库使用嵌入式方案，不依赖额外服务
• 文本切分参数按通用中英文文档调过一版
• 模型层面做了接口抽象，换模型只改配置

这套设计思路是“先跑通，再调优”。你可以先用默认配置把整个链路拉通，看到检索结果和生成效果之后，再按自己的文档类型逐项优化。

1.3 适用场景画像

我实测下来，这个项目最适合三类内容：技术文档、培训材料、产品 FAQ，特点是结构清晰、事实密度高、答案能从片段中直接定位。不适合的场景也有——需要强实时性的数据查询、需要复杂多轮推理的问答、对数字准确性要求极高的场景，纯靠 RAG 不够，得叠加外部工具或人工校验。

2. 技术选型：LangChain 生态里怎么拼出最省心的组合

2.1 为什么用 LangChain 而不是从零手写

有人觉得 LangChain 重、抽象多，自己写 loader、splitter、retriever 也就几百行。这话有道理，但我选择 LangChain 的原因是生态兼容性。文档加载器覆盖几十种格式，向量库接口统一，换库不用改业务代码，模型调用也能平滑切换。手写方案前期看着简单，后期每加一种文档格式、换一个向量库，都要自己造轮子。

另外 LangChain 的表达方式直观，尤其是新版 LCEL 语法，用管道符组合组件，代码读起来跟流程图一样，协作成本低。对团队项目来说，可维护性比省几个依赖更重要。

2.2 向量库选型：Chroma、FAISS、Milvus 怎么选

“开箱即用”限制了我選向量库的思路。

我最后选了 Chroma，原因是它默认就能落盘，自动持久化，索引存储在本地目录，重启不丢数据。FAISS 性能更好但持久化要自己管，Milvus 功能最全但对“开箱即用”目标来说太重了。如果你后续数据量超过百万级或需要多机部署，再迁移到 Milvus 也不迟，因为上层代码已经被 LangChain 抽象好了。

2.3 Embedding 模型：中文场景的选型思路

Embedding 模型直接决定检索质量，英语文档用 OpenAI 的 text-embedding-ada-002 没问题，但中文场景我建议优先考虑国产开源模型，比如 bge-m3、m3e-base。实测下来，这些模型在中文语义匹配上的效果比通用英文模型好一截，而且本地部署无需外部 API 调用，数据链路更短。

如果你的团队用的是兼容 OpenAI 协议的大模型接口，Embedding 也可以走同一套协议，配置上只改模型名和请求地址就行。我的建议是：中文文档为主，选 bge-m3；中英混合且 API 调用成本可接受，用 OpenAI 或国产商业接口；对数据敏感就全部本地。

2.4 大模型接入：兼容层设计

项目里我封装了一个统一的 LLM 调用层，底层用 LangChain 的 ChatOpenAI 对接所有兼容 OpenAI 协议的接口。这么做的好处是，不管后面换 GPT、通义、DeepSeek，还是切到 Ollama 跑的 Qwen2.5，只需要改环境变量里的模型名和 base_url，业务代码零改动。Ollama 本地部署往往能省下不少 API 费用，对实验环境和中小团队尤其友好。

3. 核心实现：从文档加载到问答响应的完整链路

3.1 文档加载与预处理

LangChain 提供了统一接口，我把本地文件夹加载统一封装成load_documents方法，支持 PDF、Markdown、TXT 三种格式。

from langchain_community.document_loaders import DirectoryLoader, TextLoader, PyPDFLoader def load_documents(docs_dir: str): loaders = { ".md": DirectoryLoader(docs_dir, glob="**/*.md", loader_cls=TextLoader, loader_kwargs={"encoding": "utf-8"}), ".txt": DirectoryLoader(docs_dir, glob="**/*.txt", loader_cls=TextLoader, loader_kwargs={"encoding": "utf-8"}), ".pdf": DirectoryLoader(docs_dir, glob="**/*.pdf", loader_cls=PyPDFLoader), } docs = [] for ext, loader in loaders.items(): docs.extend(loader.load()) return docs

这里有一个容易踩的坑：TextLoader默认编码是 UTF-8，但不少中文老文档是 GBK 编码，直接加载会报UnicodeDecodeError。我加了一层异常处理，检测到解码失败就自动尝试 GBK 编码，避免整个流程中断。

预处理阶段还有一件事要做——过滤无意义内容。PDF 转换出来的文本经常带页码、页眉、页脚，这些碎片进向量库只会污染检索结果。我在加载后做了一步正则清洗，把页码、连续的重复分隔符、孤立 URL 都去掉，这一步对后续效果影响很大。

3.2 文本切分：chunk_size 和 overlap 的门道

切分是整个 RAG 链路里最容易被低估的环节。切太大，检索粒度粗，容易把不相关的信息带进上下文；切太小，语义不完整，检索召回的片段前言不搭后语。

我用的RecursiveCharacterTextSplitter，它按字符递归切分，先按段落切、再按句子切、最后按字符切，能尽量保留语义边界。

from langchain.text_splitter import RecursiveCharacterTextSplitter text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50, separators=["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""], ) split_docs = text_splitter.split_documents(docs)

chunk_size=500、chunk_overlap=50是我在多个中英文混合文档上试出来的平衡点。chunk_size 取 500 是因为这个长度大约能涵盖 3～5 个完整段落，既保留了上下文，又不至于让向量检索的精度下降。overlap 取 50 是为了防止一句话被从中间截断——如果一句话跨了两个 chunk，检索时关键词被切开，召回质量会明显下降。

这个参数没有绝对最优，跟文档类型强相关。技术文档如果段落本来就清晰，chunk_size 可以放大到 800；问答对形式的文档，按“一问一答”切一个 chunk 效果最好。建议你搭好链路后，根据实际检索效果反推调整。

3.3 向量化与 Chroma 存储

加载和切分完成后，需要把文本块向量化并写入向量库。核心代码不长：

from langchain_community.vectorstores import Chroma from langchain_community.embeddings import HuggingFaceEmbeddings embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-m3") vectorstore = Chroma.from_documents( documents=split_docs, embedding=embeddings, persist_directory="./data/chroma_db", ) vectorstore.persist()

这里有两个关键点。第一，persist_directory参数指定了向量库落盘路径，第二次启动时如果目录已存在，Chroma会直接加载已有索引，不需要重新向量化，节省大量启动时间。第二，embedding 模型和向量库的匹配关系要固定，如果中途换了 embedding 模型，旧的索引向量和新向量不在同一语义空间，检索结果会莫名其妙地差，这种问题排查起来很隐蔽，我后面在常见问题里细讲。

3.4 检索策略：普通相似度还是 MMR

检索环节决定了模型能看到什么材料，是整个 RAG 效果的上限。默认方案是similarity_search，直接用向量余弦相似度取 Top-K。这个方案实现的检索结果在大部分场景下够用，但存在一个典型问题——召回的片段之间可能高度相似，从多个角度重复描述同一件事，信息冗余，覆盖不全。

max_marginal_relevance_search（MMR）能缓解这个问题。它一边选相关性高的片段，一边排除与已选片段过于重复的候选项，让召回结果在“相关”和“多样”之间做权衡。

retriever = vectorstore.as_retriever( search_type="mmr", search_kwargs={"k": 5, "fetch_k": 20}, )

k=5是送入大模型的片段数，fetch_k=20是 MMR 的候选池大小。我第一次跑 RAG 时用k=8，效果反而更差，因为片段太多，模型容易被无关信息带偏，回答变得冗长且重点模糊。k=5是在回复质量和上下文窗口占用之间的折中。如果你的文档是碎片化的，k可以调小到 3；如果问题需要跨多个文档综合回答，可以调大到 6～8。

3.5 问答链搭建：LCEL 写法与 Prompt 调优

新版 LangChain 推荐用 LCEL 表达式来组装链路，代码更简洁。我的问答核心逻辑如下：

from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_openai import ChatOpenAI prompt = ChatPromptTemplate.from_messages([ ("system", """你是一个严谨的智能助手。请基于以下资料回答问题。 资料： {context} 要求： 1. 只根据资料回答，资料中没有的信息不要编造 2. 如果资料不足以回答，明确回答“资料中未提到” 3. 引用资料中的关键信息时，尽量保留原文表述"""), ("human", "问题：{question}"), ]) llm = ChatOpenAI( model="qwen2.5:7b", base_url="http://localhost:11434/v1", api_key="ollama", temperature=0.1, ) chain = ( { "context": retriever | format_docs, "question": lambda x: x["question"], } | prompt | llm | StrOutputParser() )

Prompt 调优是效果提升最立竿见影的环节。这个 system prompt 里我写了两条硬约束：“只根据资料回答”和“资料不足时明确说不知道”。这两条直接压制了大模型的“编造欲”。我试过不加任何约束的版本，同一个知识库，模型能言之凿凿地给出资料里根本不存在的结论；加上约束后，虽然模型偶尔会回答“未找到相关信息”，但至少不会误导人。

temperature=0.1是我固定的低随机值。知识库问答属于事实型任务，温度越低越稳定，太高了模型会自行发挥。如果要让回答更灵活，最多调到 0.3，再高就不适合 RAG 场景了。

3.6 FastAPI 封装：把 RAG 变成可调用的服务

为了让团队其他人能直接用，我把链路封装成了 FastAPI 服务，暴露POST /ask接口。

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class AskRequest(BaseModel): question: str @app.post("/ask") def ask(req: AskRequest): result = chain.invoke({"question": req.question}) return {"answer": result}

同时加了一个POST /upload接口，支持上传本地文件后即时更新向量库。这里要注意：每次上传都要重新加载文档并做 embedding，耗时比较长，我做了异步处理，并返回任务 ID，前端轮询后台状态。生产环境建议用 Celery 或者 FastAPI BackgroundTasks，避免阻塞其他请求。

4. 开箱即用的工程化细节

4.1 目录结构与配置设计

项目结构我刻意保持扁平，方便理解：

langchain-rag-chat/ ├── app.py # FastAPI 入口 ├── rag_core.py # RAG 核心逻辑：加载、切分、向量化、检索 ├── config.yaml # 业务配置 ├── .env.example # 环境变量模板 ├── data/ │ ├── docs/ # 放入待索引的文档 │ └── chroma_db/ # 向量库持久化目录 ├── requirements.txt └── Dockerfile

config.yaml里集中管理切分参数、检索参数和模型配置。环境变量单独放.env，避免把密钥写进代码仓库。.env.example给出所有需要填写的变量名和示例值，新环境拷贝一份改后缀就能启动。

# config.yaml splitter: chunk_size: 500 chunk_overlap: 50 retriever: search_type: mmr k: 5 fetch_k: 20 embedding: provider: huggingface model: BAAI/bge-m3 llm: provider: openai_compatible model: qwen2.5:7b base_url: http://localhost:11434/v1 temperature: 0.1

4.2 Docker 部署：一键启动

为了让“开箱即用”名副其实，我写了 Dockerfile 和 docker-compose。服务的启动拆分成了两步：首次启动先跑索引构建命令，之后正常启动服务。这里的核心思路是数据卷挂载data/目录，让容器重启不会丢失向量库。

# 首次构建索引 docker build -t langchain-rag-chat . docker run --rm -v $(pwd)/data:/app/data langchain-rag-chat python index.py # 启动服务 docker run -d -p 8000:8000 -v $(pwd)/data:/app/data --env-file .env langchain-rag-chat

踩坑记录：容器里运行 HuggingFace Embedding 模型时，如果内存不足，进程会被 OOM Kill。我在 Dockerfile 里给 Python 进程设置了一个内置 4GB 内存的启动参数，同时把 chorma 的临时目录指向数据卷，避免容器重启后索引丢失。

5. RAG 知识库到底能不能存图片

这个问题在团队内部讨论了很久，也是搜索热词里的高频问题。我的答案是：能存，但要看你怎么理解“存”。

5.1 区别：文件存储和内容理解是两码事

把图片文件作为附件存进知识库，任何文件系统都能做到。但 RAG 问答要求的是“根据图片内容回答问题”——比如你上传一张架构图，问“这个系统用了什么中间件”，如果你的检索链路只处理了文件名和文件路径，那模型什么都答不出来。

5.2 多模态 RAG 的两种落地模式

真正支持图片内容检索的方案有两种。第一种是多模态 Embedding，比如 CLIP 这类模型，把图片直接映射成向量，检索时可以和文本向量在同一空间做相似度匹配。第二种是“图生文”，用视觉模型把图片内容转成一段文字描述，再把描述文本纳入向量库，检索命中后既能返回图片，又能返回对应的文字描述。

第二种方案我实际用过，对大多数业务场景够用了，因为问题通常关心图片里的关键信息和结论，而不是像素级细节。实现方式也不复杂：调一次视觉模型拿到描述，把描述当普通文本走 RAG 链路，同时保存图片路径，检索返回时附带地址给前端展示。

5.3 图文混排文档的最佳实践

对于 PDF 里的图文混排内容，我建议先做 OCR 或版面解析，把图片区域单独抽出来生成描述，再和正文段落一起切分、建向量。这样“图 + 文”都能被检索到，而不是 PDF 解析时把图片区域直接丢弃。如果只是把图片压缩后硬塞进 PDF，再用普通 PDFLoader 解析，出来的文本里往往只有图片说明或完全空白，这种就是无效索引。

6. 常见问题与排查技巧实录

实际操作里遇到最多的问题都是环境、编码和参数层面的，我把排查过程整理成速查表。

6.1 中文文档乱码和加载失败

我踩得最多的是第一个。团队文档库里有大量从旧系统导出、编辑工具默认保存成 GBK 编码的 txt 文件。后来我在TextLoader外面包了一层编码探测，简单粗暴，但很有效:

def autodetect_encoding(filepath): for enc in ["utf-8", "gbk", "gb18030"]: try: with open(filepath, "r", encoding=enc) as f: f.read() return enc except UnicodeDecodeError: continue return "utf-8"

6.2 检索召回质量差

症状是检索返回的片段看起来跟问题无关，或者相关片段被淹没在噪声里。排查链路按照“由近及远”来排查：

1. 切分是不是有问题？如果一句话横跨两个 chunk，检索时关键词对不上。
2. Embedding 模型选对了没有？中文文档用英文 embedding，效果会很差。
3. 检索类型和参数有没有调过？默认search_type="similarity"遇到同质化片段就容易重复召回，换成 MMR 并调整fetch_k能缓解。
4. 向量库里的数据是不是旧的？改了分块参数或者重新加载文档后，旧的向量残留导致命中过时内容。

这里给出一个实操小技巧：调试时打印出检索出来的原始片段，不要只盯着最终回答。如果片段本身就答非所问，问题出在检索层，怎么调 prompt 都没用；如果片段是对的，回答却不对，才需要调 prompt 和模型参数。这个区分能大幅缩短排错时间。

6.3 幻觉问题压制不住

我用temperature=0.1和 system prompt 约束之后，幻觉问题已经小了很多，但仍然存在。遇到模型一本正经说资料里不存在的细节时，可以先检查两件事：一是是否有多个相似片段拼接后产生了结论冲突；二是是否把不相关的片段推给了模型，导致模型在综合时自由发挥。

最彻底的做法是加一道“引用溯源”：让模型在回答末尾列出引用的片段编号，前端渲染时展示来源。这样回答即使有偏差，也能快速回溯到是哪段资料导致的，迭代修正时效率高很多。实现方式就是在 prompt 里加一条输出要求，让模型把用到的片段来源列出来。

6.4 大文档内存占用过高

跑完一个 500 页的 PDF，直接把 Docker 容器干重启了。排查发现PyPDFLoader一次性把整份 PDF 解析成一个超大 Document，embedding 时内存直接爆掉。解决方法是按页拆分：用递归切分器之前，先按页或其他边界拆成多个 Document，再统一切分。另一种做法是改用流式加载，一次只处理一页。

6.5 换了 embedding 模型后检索效果变差

这个问题最隐蔽。我在实验阶段把 embedding 模型从 m3e-base 换到 bge-m3 后，检索效果反而退步了——因为 Chroma 持久化目录里存的是旧模型生成的向量，新模型查询时拿新向量去比对旧索引，语义空间根本不匹配。后来每次换 embedding 模型都强制清除data/chroma_db重新建索引，问题才解决。

7. 从 RAG 到 Agent：后续还可以怎么扩展

7.1 引入 LangGraph 做复杂流程

RAG 检索是一个“单轮问答”的闭环，遇到需要多步推理的问题就力不从心了。比如“对比 A 方案和 B 方案的成本差异”，需要先检索各自成本数据、再综合对比。这种场景适合引入 LangGraph 做多步 Agent 流程。LangChain 官方有个 agent-inbox 方向，让 Agent 可以接收外部输入、挂起等待人工确认，对复杂任务挺有用。

我在实验环境里试过 LangGraph，把 RAG 链包成一个节点，做成“先检索-再判断是否足够-不够再检索”的循环。效果比一次性 RAG 稳定，但成本也翻倍，适合对准确性要求高的场景。

7.2 知识图谱 RAG：结构化知识库的进阶

纯向量的 RAG 处理关系型问题很弱。“有哪些服务依赖数据库 X”，这类问题在纯向量检索下，回答只能靠文档里的片段偶然命中。如果知识库里同时维护一份实体和关系图谱（KG），可以在向量检索之外做图谱查询，这两类结果合并后再喂给模型，能显著提升关系型问题的正确率。这个方向叫 GraphRAG 或 KG RAG，适合团队文档有大量跨文档引用关系的情况。代价是知识图谱的构建成本高，初期需要人工梳理实体关系，所以我的建议是：先跑通纯 RAG，等确实遇到关系型问题质量瓶颈再上图谱。

7.3 RAG 的瓶颈和评估思路

做这个项目之前，我一直以为 RAG 最大的瓶颈是模型能力，实际操作后才发现，检索质量才是天花板。文档质量差、切分不匹配、向量检索召不回相关片段，再强的模型也白搭。所以项目里我预留了一个评估脚本，从知识库里抽出几十个高频问题作为测试集，每次改完参数就批量跑一遍，统计命中率和回答完整度。没有评估的 RAG 优化就是盲人摸象——你觉得改好了，其实只是这次运气好。

最后说一点实际部署的体会：RAG 项目的复杂度不在代码，而在数据质量。把文档整理干净、统一格式，比调任何参数都更有效。这套项目跑通之后，我们团队现在开始整理规范化的文档标注体系了——好的输入才有好的输出，RAG 的架构和代码可能只能占一半功劳。