RAG知识库搭建实战：基于LangChain的开箱即用问答系统全解析

做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 检索也不冲突。

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_size=500、chunk_overlap=80，这是从经验出发的起点：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 都扛得住。真正千万级以上的规模再考虑更重的向量数据库，现阶段没必要让基础设施复杂化。

2.3 检索与生成：召回精度、多样性、引用溯源

从向量库检索的时候，单纯用 top-k 相似度有一个问题：返回的 k 条结果可能内容高度相似，比如十条里有六条都在讲同一段，剩下有用信息被挤掉。这个问题叫“召回多样性不足”。我在这里用了 MMR 检索，也就是最大边际相关性，它会在“和问题相关”与“和已有结果不相似”之间做平衡，让返回的段落覆盖面更广。

Top-K 参数设多少也要看语料。项目默认 k=5，如果文档本身内容碎片化严重，可以调到 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.txt

Mac 的 Apple Silicon 芯片在安装一些基础依赖时基本没什么大问题，但如果遇到个别包编译报错，可以先把 Xcode Command Line Tools 更新到最新版本。这类问题通常不复杂，卡住了先看编译日志，别急着换 Python 版本。

项目依赖集中在 requirements.txt 里：

langchain>=0.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.0

loader.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), encoding="utf-8") elif path.suffix.lower() == ".pdf": loader = PyPDFLoader(str(path)) else: continue docs.extend(loader.load()) return docs

ingest.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_size=config["chunk_size"], chunk_overlap=config["chunk_overlap"], separators=["。\n", "！", "？", "\n\n", "\n", "，", "；"], ) chunks = splitter.split_documents(docs) print(f"文档切分完成，共 {len(chunks)} 个片段") embeddings = OpenAIEmbeddings(model=config["embedding_model"]) vectorstore = Chroma.from_documents( documents=chunks, embedding=embeddings, persist_directory=config["vector_db_dir"], ) print("向量索引构建完成")

retriever.py 里使用 MMR 检索：

from langchain_chroma import Chroma from langchain_openai import OpenAIEmbeddings def get_retriever(config): embeddings = OpenAIEmbeddings(model=config["embedding_model"]) vectorstore = Chroma( embedding_function=embeddings, persist_directory=config["vector_db_dir"], ) return vectorstore.as_retriever( search_type="mmr", 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(model=config["llm_model"], temperature=config["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 run

app.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 问题排查速查表

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 这个项目后面要扩展的方向，我自己列了三个：多轮对话记忆、重排器引入、按文档类型动态切分策略。任何一个做扎实，都比再加一堆花哨功能更实用。