企业官网建设流程全解析

最近这段时间，陆续有几个朋友问我同一个问题：网上 RAG 教程那么多，照着敲完也能跑，为什么我自己的知识库回答总是差口气？其实这正是我想做 langchain-rag-chat 的原因。这个项目不是一个简单的 Hello World，而是一条从文档导入、切分、向量化、检索到问答界面全串起来的完整链路，目标是让你 clone 下来、填上 Key、启动脚本，就能得到一个可以实际用起来的本地知识库问答系统。

我当时给自己定的标准很直接：不折腾数据库，不写一堆胶水代码，默认配置能跑通，换参数不换逻辑，并且把常见的坑提前埋好解决方案。所以这个项目里，我选了 LangChain 作为编排框架，默认用 FAISS 当向量库，支持 OpenAI 兼容接口和本地模型切换，还把重排、多轮对话、来源引用都做了进去。如果你是刚入门 RAG，想知道一套可落地的组合怎么搭；或者你已经搭过 Demo，但卡在检索效果和工程细节上，这篇文章应该能让你少走不少弯路。

1. 项目出发点：为什么需要“开箱即用”的 RAG 问答库

1.1 RAG 的常见陷阱：Demo 与生产的距离

很多同学第一次接触 RAG，跑的是 LangChain 官方文档里的RetrievalQA示例，加载一个 PDF，切成几百个 chunk，存进向量库，然后问一句话，看起来没问题。但一旦换成自己的文档，问题马上冒出来：PDF 里的表格变成乱码、切分把一句话拦腰截断、检索返回的前 4 个片段里只有 1 个跟问题相关，最后 LLM 用那 3 个不相关片段硬生生编了一个答案。

这个落差感不是错觉。RAG 的公开 Demo 往往只验证“链路通”，不会告诉你实际数据有多脏、问答场景有多杂。真正到生产环境，你得处理不同文件格式、不同语言的文档、不同粒度的知识单元，还要考虑多轮对话时上下文怎么组织。开箱即用的意思是：默认配置已经帮你想过这些问题，你能直接跑出一个可接受的结果，而不是把调优的苦活全留给使用者。

1.2 langchain-rag-chat 希望解决的核心问题

我整理 langchain-rag-chat 时，优先解决了四个问题：

第一，文档接入足够省心。项目内置了常见的 PDF、Word、TXT、Markdown 加载方式，不需要每次重新查 loader 用法。第二，检索结果可解释。回答后面会带来源片段，用户能看到 AI 是基于哪些内容回答的。第三，配置和代码分离。模型名、温度、切分大小、Top K 这些参数全部放在一个 YAML 文件里，改配置比改代码安全得多。第四，支持从检索到问答的独立调试。项目拆成了ingest和chat两条命令，你可以先单独看文档切分和入库是否正常，再去看问答链路是否合理，定位问题会快很多。

1.3 技术选型：LangChain、LlamaIndex、Dify 到底怎么选

写这个项目的时候，我其实对比过三套方案。LlamaIndex 的索引机制更强，尤其适合处理大规模文档集合，但它对“问答链路编排”的抽象不如 LangChain 直接；Dify 这类产品化平台上手确实快，但如果你是开发者，想在代码层面控制 prompt、控制工具调用，它反而会限制你的灵活性；CrewAI 更偏 Agent 多角色协作，不是纯粹的 RAG 框架。

最终选 LangChain 的原因很务实：它的文档加载器、切分器、向量库封装、LLM 接口抽象已经足够全，社区案例多，出了奇怪问题更容易搜到答案。而且 LangChain 的 LCEL 表达式语言可以很简洁地串起retriever | prompt | llm这样的链路，代码量少，逻辑也好懂。langchain-rag-chat 本质上就是用了 LangChain 最核心的那几个模块，没有引入太多花哨的组件，这让项目本身也更容易被阅读和改造。

2. 整体架构与关键环节设计

2.1 一条数据从文件到向量库的完整链路

我在设计整个项目时，把数据流向理成了四个阶段：加载、切分、向量化、持久化。加载阶段读文件内容，切分阶段把长文档变成有语义边界的块，向量化阶段把这些块转成高维向量，持久化阶段把向量和原始文本一起存到向量库。用户提问的时候，系统把问题也向量化，在库中找到最相似的几个文档块，再把这些块连同问题一起交给 LLM 生成回答。

听起来很简单，但每个阶段都有取舍。比如加载阶段，PDF 不能直接按文本读，要区分 PDF 自身是文本型还是扫描型；切分阶段，按固定长度切最简单，但会把“虽然……但是”这种逻辑结构切断；向量化阶段，Embedding 模型的选择直接决定“相似”到底指什么。开箱即用不是把这些取舍都抹平，而是给每个决策点一个合理的默认值，同时保留调整的入口。

2.2 切分策略怎么定：固定长度、递归切分与语义切分

切分是 RAG 里最影响效果的环节之一。默认配置我用的不是固定长度，而是 LangChain 的RecursiveCharacterTextSplitter。它维护一组分隔符，比如先尝试按段落分，段落太长再按句号分，再不行按逗号分，这样切出来的块更贴近自然语义边界。

具体参数上，chunk_size=500，chunk_overlap=80，这个组合在大多数中文和英文混合文档上表现比较稳。chunk_overlap 的作用是让相邻块之间保留重复信息，避免一个概念刚好被切在边缘导致检索时丢失。举个例子，一份 1000 字的文档，按 500 字、重叠 80 字来切，实际生成的块数大约是ceil((1000-500)/(500-80)) + 1，也就是 3 块左右，虽然多占了一点存储，但检索召回率会明显好于完全不重叠。

固定窗口切分是另一种常见做法，处理超长日志之类的内容时更快，但容易切断语义。语义切分我也试过，用 LLM 判断段落边界，效果最好，但成本高、速度慢，不适合批量入库。所以我的建议是：默认用递归切分，如果文档有明显章节结构，可以先用正则把它按章节拆开，再对每章做递归切分。

2.3 Embedding 与向量库选型细节

Embedding 选型几乎是决定检索质量的天花板。在 langchain-rag-chat 里，我保留了三个可切换的选项：OpenAI 的text-embedding-3-small、本地 BGE 系列、以及 M3E。OpenAI 的优势是省心，1536 维的数据兼容性也好，适合快速验证；BGE 和 M3E 对中文更友好，可以完全本地运行，但需要准备一定内存和推理框架。你可以在config.yaml里改一个embedding_provider字段，代码会自动选择对应的加载方式。

向量库方面，默认用 FAISS 是因为它就是一个本地文件，不需要额外启动服务。对单机知识库来说，FAISS 的检索速度完全够用，项目里还做了index.faiss与index.pkl的持久化，重新启动问答服务不用重新跑入库流程。如果你要部署成多人服务或者数据量大到单机扛不住，我会建议换 Chroma 或者 Milvus，LangChain 的VectorStore接口抽象让这种切换可以控制在很小的范围内。

2.4 检索后的排序与增强：从单路召回走向混合检索

只看向量相似度的检索，在正式场景里经常不够用。原因很简单：用户问题的表达方式和文档里的表达方式可能差别很大，但语义向量能抓住意思，却不一定能精确匹配出文档里那个关键的人名、产品型号或者缩写。所以我在项目里加入了混合检索的选项：一路走向量相似度，另一路走 BM25 关键词匹配，最后把两路结果用 RRF 算法合并。

RRF 的思想很朴素：每个文档在结果列表里有一个名次，综合得分是1 / (k + rank)，k 一般取 60。这样即使关键词检索把某个文档排得很靠前，向量检索也不会完全无视它。实测下来，混合检索对专业术语多、缩写多的文档提升很明显。另外，如果你有精力再加一个 Cross-Encoder 重排模型，可以把检索出的 top 20 再精排成 top 5，但这不是开箱即用的默认项，因为重排模型会占用额外的推理资源。

3. 代码实现：核心模块逐段拆解

3.1 项目结构：模块职责一次说清

langchain-rag-chat 的目录结构是这样组织的：

langchain-rag-chat/ ├── config.yaml ├── requirements.txt ├── ingest.py ├── chat.py ├── app.py ├── rag_core/ │ ├── __init__.py │ ├── loader.py │ ├── splitter.py │ ├── embedder.py │ ├── retriever.py │ └── llm.py

rag_core下面每个模块只干一件事。loader.py负责把各种文件读成纯文本，splitter.py负责切分，embedder.py负责根据配置创建 Embedding 模型，retriever.py负责从向量库检索并做混合排序，llm.py负责构建大模型客户端。ingest.py是入库脚本，chat.py是命令行问答脚本，app.py是 Web 界面入口。这样拆分最大的好处是，你可以在不跑到 Web 层的情况下，单独验证每一段逻辑。

3.2 文档加载与预处理实现

文档加载部分，我封装了一个load_documents(path)函数，根据后缀分发到不同 loader。核心逻辑大致是这样：

from langchain_community.document_loaders import ( PyPDFLoader, Docx2txtLoader, TextLoader ) def load_documents(path): suffix = path.rsplit(".", 1)[-1].lower() if suffix == "pdf": loader = PyPDFLoader(path) elif suffix == "docx": loader = Docx2txtLoader(path) elif suffix in ("txt", "md"): loader = TextLoader(path, encoding="utf-8") else: raise ValueError(f"暂不支持的文件类型: {suffix}") return loader.load()

这里有个细节：PDF 加载默认是文本抽取，如果 PDF 本身是扫描件，PyPDFLoader会抽出一堆空白。遇到这种文件，我会先用 OCR 工具把 PDF 转成文本再入库。项目里没有强制集成 OCR，是因为 OCR 依赖较多，会增加安装复杂度，但我在 README 里写了应对扫描件的准备方案。

切分部分我单独写了一个split_documents函数，方便你打印切分结果来调试。建议第一次跑的时候，随机抽几段切分结果看看，确认没有把重要逻辑切断，再继续入库。

3.3 问答链实现与多轮对话处理

问答链我用的是 LCEL 方式，而不是直接调RetrievalQA。因为 LCEL 更透明，你可以清楚看到中间发生了什么。核心代码是这样：

from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_core.runnables import RunnablePassthrough prompt = ChatPromptTemplate.from_template( """你是知识库助手，请根据以下资料回答问题。 如果资料里没有相关信息，直接说“不知道”，不要编造。 最后附上你参考的文档来源。 资料： {context} 问题：{question} """ ) rag_chain = ( {"context": retriever, "question": RunnablePassthrough()} | prompt | llm | StrOutputParser() )

retriever会返回一个包含文档列表的对象，prompt 里通过{context}把它格式化成正文。多轮对话的处理，我在项目里用了一个简洁的方案：把历史消息压缩成最近的两轮摘要，再拼进系统提示里。你不需要引入复杂的记忆模块，因为对知识库问答来说，大多数问题本身已经包含足够信息，过长的历史反而会干扰模型注意力。

3.4 用 Gradio 快速实现可交互界面

命令行脚本好用，但给非技术成员演示不方便。所以我用 Gradio 写了一个app.py，几十行代码就能出一个 Web 页面，支持文件上传和实时对话。

关键的部分是文件上传回调。用户上传一个文件后，系统自动调用入库管道，把文件切分并写入向量库，然后提示“文档已经入库，可以开始提问”。问答框则把上面对话链包装成predict函数，返回答案和参考来源。Gradio 的ChatInterface本身会处理聊天历史，你不用自己维护 session，非常省事。

如果需要把这个项目部署到公网给更多人用，建议你在 Gradio 前面套一层 Nginx 做 HTTPS，并且加上访问鉴权。毕竟一个会被外部访问的聊天接口，如果不做权限控制，很容易被人当免费 API 刷。

4. 实战中的坑与排查方法

4.1 检索引擎返回不相关内容怎么办

我遇到最多的问题就是：答案看着流畅，但参考来源和问题根本不搭。这时候不要急着调 LLM，先检查检索链路。第一步，把问题的向量相似度 Top 5 片段打印出来，看它们是否真的和问题有关。如果无关，大概率是 Embedding 模型不适合你的文档语言，或者切分后的块本身太碎、信息密度太低。

如果是混合检索，还要看是不是 BM25 权重把不相关但含关键词的文档抬了上来。我一般先关闭混合检索，单独跑向量检索看效果，再逐步打开。另外top_k也很关键，默认是 4，如果你觉得答案信息不够，可以调到 6 或 8，但并不是越多越好，因为无关片段一旦进 prompt，模型很容易被带偏。

4.2 大模型“编答案”：幻觉问题的处理思路

RAG 比纯靠模型记忆生成答案已经有了很大改进，但幻觉仍然存在。尤其是在检索片段不够、或者 prompt 约束不够强的时候。我在 prompt 里做了两条硬约束：一是资料里没有就直接说不知道，二是强制输出来源。这两条不是摆设，模型在多数时候会遵循明确的指令。

如果你的任务对准确性要求很高，还可以在回答后加一层校验逻辑：用模型判断答案中的关键实体是否在检索片段中出现，没有出现的部分标为“推测”。这种做法不需要额外训练，只是一个额外的 LLM 调用，但对降低错误信息传播很有帮助。我在项目里留了这个校验函数的接口，但默认关闭，因为会多一次调用、增加延迟。

4.3 本地模型与 API 模型切换时需要注意什么

langchain-rag-chat 用了一个很常规的做法：通过环境变量存 API Key，通过config.yaml指定llm_provider。我试过本地跑 Ollama 上的 Qwen 系列，也试过直接调 OpenAI 兼容接口，两种方式在代码层的切换成本都不高。但要注意，本地模型和 API 模型的可控性完全不同。

本地模型如果显存不够，生成速度会慢到让人怀疑人生，这时我建议把超时时间调大，同时减小max_tokens。还有一个容易忽略的问题：Embedding 模型和 LLM 必须是同一个加载方式，不能说 LLM 用 API、Embedding 用本地模型还期望效果好。至少让它们在同一语言能力区间，否则可能出现“问题能识别、答案却答非所问”的诡异现象。

4.4 环境搭建踩坑：macOS 与内存问题

在 macOS 上跑这个项目，我第一个建议是用 Python 3.11 或 3.12，配一个干净的 venv。FAISS 在苹果芯片上有 CPU 版本，安装faiss-cpu就行，不需要折腾 GPU 版本。如果你是 Intel Mac，同理会更吃力一点，但跑小规模知识库问题不大。

内存方面，如果要处理几十 MB 的大文档，入库时千万不要一次性把所有文档向量都放在列表里。我在项目里用批量写入的方式，每处理 64 个块就写一次向量库，然后释放引用。这个习惯可以避免你的 Python 进程内存暴涨到十几 GB。另一个常见问题是开机驻留模型导致的内存无法释放，建议把 Embedding 模型的加载放到需要时才执行，而不是在import阶段就初始化。

5. 从 RAG 到知识图谱：下一个瓶颈的思考

5.1 RAG 知识库和结构化知识库的应用边界

一定规模之后，你会发现纯 RAG 有它的天花板。RAG 适合的是非结构化文本，比如产品文档、操作手册、技术文章，它擅长回答“怎么做”“是什么”这类基于语义查找的问题。但如果你要问“A 产品和 B 产品有哪些共同组件”“哪些客户关联到了同一事故单”，文本的向量检索就很难给出精确答案，因为它需要多跳关系推理。

这时候就需要区分 RAG 知识库、结构知识库和知识图谱的适用场景。结构知识库（比如数据库表）适合精确查询和统计，知识图谱适合关系查询和路径推理，RAG 知识库适合开放语义理解。它们不是替代关系，而是互补关系。很多公司做知识中台，一开始都是上 RAG，后来发现复杂查询搞不定，才回头补图谱和结构化数据。

5.2 当检索无法回答复杂关系时，知识图谱能做些什么

我在 langchain-rag-chat 的后续规划里，就考虑了 Ontology RAG 的方向。做法是：从入库文档中抽取实体和关系，构建知识图谱，然后在问答时先用 LLM 把用户问题转成图谱查询，如果图谱能查到，就直接返回精确结果；查不到，再退回到向量检索。这种混合架构能同时兼顾精准和开放，但工程复杂度会明显上升。

我不建议新手一开始就上图谱，因为实体抽取的质量、关系模型的建模、以及查询语法的解析，每一个都是不小的课题。更好的路线是先把 RAG 底座做稳，把检索评估指标跑起来，等积累了足够多“RAG 回答不了”的真实问题样本，再考虑用图谱去补那些高频痛点。

5.3 后续计划：把 langchain-rag-chat 扩展成混合问答系统

项目里我已经预留了retriever接口，接下来我会加入一个基于图谱的查询模块，让用户在问答时多一个graph检索源。同时，我打算引入 RAGAS 这样的离线评估工具，对切分参数和检索策略做自动调优。这个领域里，很多人输在“感觉好用”和“实际可用”之间没有度量，引入评估指标后，每次改参数就有一个客观依据，而不是靠玄学调参。

我自己用下来最深刻的体会是：RAG 的难点从来不在“搭建”，而在“调优”。一套开箱即用的代码只是起点，真正让你放心的知识库，一定是经过不断观察坏例、调整切分和检索策略之后打磨出来的。希望 langchain-rag-chat 能帮你把起点抬高一步，让你剩下更多精力去解决真正重要的问题。