企业官网建设流程全解析

1. 项目概述与方案选型

1.1 这个项目到底在做什么

先说结论：这是一套基于LangChain框架、以检索增强生成（Retrieval-Augmented Generation，简称RAG）为核心架构的知识库问答系统。你给它一堆文档——PDF、Word、Markdown、数据库里的结构化数据——它能把文档内容切碎、向量化、存进向量库，然后在每次问答时先从库里检索出最相关的片段，喂给大模型做参考，让模型"带着资料说话"而不是凭空瞎编。

我在实际项目里最深的感受是：RAG解决了大模型两个让人头疼的问题——幻觉和知识滞后。模型训练完就"冻结"了，你问它上周才上线的产品规则，它大概率胡编；但你给它检索到的真实片段，它至少能沿着资料回答问题。这个项目最大的价值，就是让大模型在私有数据、实时数据上变得"可用、可控"。

适合谁来看这篇内容？如果你是刚接触RAG的开发者、想给公司搭一个内部知识库问答工具、或者正在调研LangChain到底怎么落地，这篇文章按我的实操路径走一遍，基本能跑通一个可用的知识库问答服务。

1.2 为什么是LangChain + RAG的组合

LangChain在这个项目里承担的不是"必须品"的角色，而是一个"加速器"。坦白讲，RAG的链路你完全可以用纯Python手写——自行调用Embedding接口、自己管理向量库、自己拼Prompt模板。但LangChain把这些步骤封装成了标准化组件，提供了统一的接口抽象，免去了很多重复造轮子的工作。

我选LangChain的方案，看中的是三点：第一，它天然支持多路文档加载器，文件类型繁杂的时候不用自己写一堆解析逻辑；第二，它的Prompt模板、Output Parser、Callback机制让我能很方便地控制模型的输入输出格式；第三，生态成熟，接各种向量库、各种模型都很顺手。

RAG侧的核心逻辑可以概括为三句话：索引（Indexing），把文档拆块并向量化；检索（Retrieval），把用户问题也向量化，去库里捞最相近的内容块；生成（Generation），把检索到的上下文和用户问题拼接成Prompt，交给大模型回答。这三步贯穿全程，也是这篇文章后面每个章节的主线。

2. 系统架构与关键组件拆解

2.1 完整架构梳理

我把这个项目的整体数据流拆成下面这条链路，跑通这一步，后面的编码就只是把这些环节按序串起来：

文档加载 → 文本切分 → 向量化(Embedding) → 写入向量库 → 用户提问 → 向量检索 → 构建上下文 → 大模型生成 → 回复用户

前四步属于"离线索引阶段"，一般跑一次就行，除非知识库文档有更新；后五步属于"在线问答阶段"，每次用户提问都会走一遍，需要尽可能控制耗时。

文档加载用LangChain的Loader组件搞定，PDF、Markdown、纯文本、甚至网页抓取都有对应实现；切分用文本分割器，按固定块大小加重叠区把长文档拆成小块；向量化用的是Embedding模型，这一步输出的向量决定了检索的语义效果，是整个系统质量的基础；向量库用来存储和检索这些向量，我选的是支持本地文件持久化的方案，能直接跑不需要额外起服务。

2.2 为什么文本要切块

切分文本这一步很多人会忽略，但它决定检索效果的上限。如果一整篇几万字的文档直接做Embedding，那向量化后的语义会非常模糊——向量会把全文的主题"平均"掉，用户问一个细节问题时，召回的内容根本不够精准。切得越碎，每个向量代表的语义越集中，召回越准；但也不是越碎越好，块太小会导致上下文信息不完整，模型回答时缺乏背景支撑。

我常用的配置是：块大小(chunk_size)设置为500到800个字符，重叠区(chunk_overlap)设置为50到100个字符。重叠区的作用是让相邻块之间保留衔接信息，避免一句话被从中间截断后，前后两块都丢失部分语义。

提示：不要照着默认参数一填就完事。文本切分参数要根据你实际文档的句式长度去调，中文文档的字符密度和英文差异很大，后面我专门说这个坑。

2.3 检索为什么用向量而不是关键词

传统的关键词检索是字面匹配，用户搜"退款流程"时，文档里写的是"退货退款的办理步骤"，关键词检索大概率漏掉这条相关内容。向量检索是把文字映射到高维语义空间，意思相近、表达不同的句子距离也近。这就是为什么RAG时代几乎清一色用向量检索做召回。

当然，向量检索不是完美的。它偶尔会召回一些"语义上相关但事实上无用"的内容，比如用户问账单细节，检索回来的却是客服流程。所以我在实践中会加一层**重排序（Rerank）**环节，先用向量检索召回Top 20结果，再用重排序模型对结果做精细化打分，只保留Top 4到Top 6喂给大模型。这一步对回答质量的提升非常明显，后面会展开细说。

3. 环境搭建与数据准备

3.1 基础环境与依赖安装

这个项目对硬件没有特别硬性的要求，我实际用的是一台8核16G内存的开发机，跑起来很流畅。如果你是Windows笔记本，内存最好有16G，因为加载模型和运行服务时，内存占用会比较明显。

必要的依赖我用一行命令装齐，Python版本建议3.9以上：

pip install langchain langchain-community langchain-openai chromadb sentence-transformers pypdf markdown

关于模型，我的建议是Embedding模型不用太大，常规的中文场景用开源的中文Embedding模型就能取得不错效果，不需要上那种体积庞大的商业向量模型。大模型侧的接入，我用的是标准OpenAI兼容接口，可以对接在线模型服务，也可以用本地部署的开源模型地址，LangChain里的ChatOpenAI组件对这两种情况都兼容，只需改一下base_url和api_key。

3.2 文档加载与清洗

拿到一堆原始文档后，第一件事不是切块，而是清洗。我在一个模拟项目X里接过一批从各处汇总来的产品说明，PDF里带着页眉页脚，Word文档里混着表格，Markdown里还夹杂着一堆无意义标签。直接切块的话，这些噪声会被一并向量化，检索出来给到模型时不仅没用，还干扰回答。

我的清洗流程分三步：

1. 统一格式：PDF用pypdf抽取文本，Word用python-docx转换，全部清洗成纯文本或者结构清晰的Markdown形式。
2. 去噪：去掉页眉页脚、空行、无关标记，把表格转成逻辑流畅的文字描述。
3. 统一编码：确保文档内容是UTF-8编码，避免之后处理中文时出现乱码。

这些步骤虽然琐碎，但对最终效果影响非常大。检索链路里，"垃圾进、垃圾出"的现象比传统数据处理更明显，模型会把噪声也当成事实依据。

3.3 文本加载器怎么选

LangChain的文档加载器很多，我实际项目里常用的就几个：

• TextLoader：针对纯文本文件，简单直接，指定编码方式就行。
• PyPDFLoader：针对PDF文件，可以按页拆分，返回Document对象的列表，保留了每页内容。
• UnstructuredMarkdownLoader：针对Markdown文件，会把标题层级保留下来，对后面切块时的结构感知很有帮助。
• CSVLoader：针对CSV数据，适合加载结构化表格数据作为知识源。

加载完的Document对象里有两个核心字段：page_content存正文内容，metadata存来源信息。我强烈建议你在metadata里保留原始文件路径和页码，这样之后检索出问题时能溯源到原文，排查起来方便很多。

from langchain_community.document_loaders import PyPDFLoader loader = PyPDFLoader("manual.pdf") docs = loader.load() for doc in docs[:2]: print(doc.metadata) # 打印来源信息和页码 print(doc.page_content[:200])

4. 检索链路实现与参数调优

4.1 向量库选型与写入流程

向量库我用的是Chroma，原因很实际：配置简单、单机够用、支持持久化到本地文件夹，不用额外部署服务，对中小规模知识库非常友好。如果你后续数据量上来了，需要水平扩容，再考虑换正式的向量数据库产品。

持久化写法如下：

from langchain_chroma import Chroma vectorstore = Chroma.from_documents( documents=split_docs, embedding=embedding_model, persist_directory="./data/chroma_db" )

这段代码会执行两件事：把每个文本块交给Embedding模型生成向量，然后把"文本块原文、向量、元数据"一起写入本地目录。下次启动时，不需要重新加载文档、重新切块、重新做向量化，直接加载持久化目录即可：

vectorstore = Chroma( persist_directory="./data/chroma_db", embedding_function=embedding_model )

提示：Embedding模型一定要保持一致。如果你想换更强的Embedding模型，必须重建整个向量库，不能用旧向量库去和新模型匹配，向量空间的分布完全不同，检索结果会直接“漂移”。

4.2 检索核心参数怎么调

Chroma的similarity_search_with_score是检索入口，它返回结果和相似度分数。实际操作中有几个参数直接影响效果：

检索数量（k）：默认我通常从k=4起步，如果你发现模型回答时背景不足，可以逐步调大到6或8。k太小，上下文不够；k太大，噪声变多，还会增加后续传给大模型的Token量，拖慢响应速度。

相似度阈值过滤：检索回来的结果不是每条都可信。我习惯加一道阈值筛选，低于某个分数线的直接丢弃。这个阈值需要你拿着真实问题去测，不同Embedding模型的分数范围不一样，有些模型出来是0到1的相似度，有些是余弦距离，别直接用网上的经验值。

重排序：向量检索完之后，如果你有条件用重排序模型，建议一定加上。我拿项目里的数据对比过，加了重排序之后，回答正确率能有明显提升，尤其是文档量大、主题相似度高的场景。它的原理是：向量检索先粗筛出候选集，重排序模型再按相关性精排，把最贴合问题的内容顶到前面。

from langchain_community.cross_encoders import HuggingFaceCrossEncoder from langchain.retrievers.document_compressors import CrossEncoderReranker from langchain.retrievers import ContextualCompressionRetriever reranker = CrossEncoderReranker( model=HuggingFaceCrossEncoder(model_name="BAAI/bge-reranker-base"), top_n=4 ) compression_retriever = ContextualCompressionRetriever( base_compressor=reranker, base_retriever=vectorstore.as_retriever(search_kwargs={"k": 12}) )

4.3 Prompt模板的设计思路

Prompt是RAG链路里最容易被低估的一环。一个粗糙的Prompt很可能导致模型无视检索到的资料，自顾自发挥；而一个设计得当的Prompt能约束模型严格基于上下文作答。

我经过多次迭代后，形成了一套稳定的模板结构，核心诉求是：要求模型仅使用上下文信息回答，不知道就明确说不知道，附上引用来源。

from langchain_core.prompts import ChatPromptTemplate prompt_template = ChatPromptTemplate.from_messages([ ("system", "你是一个严谨的问答助手。请基于给定的知识片段回答问题。\n" "规则：\n" "1. 只能使用【知识片段】中的内容作答，不得编造事实；\n" "2. 如果知识片段中没有相关内容，直接回答“根据现有知识库无法回答”；\n" "3. 回答时引用对应的知识片段编号，便于溯源。\n\n" "【知识片段】\n{context}"), ("human", "我的问题：{question}") ])

系统提示词里的"规则1"尤其关键，它拦截了大量幻觉输出。我在早期版本里没写这条，模型经常给出知识库之外的“自由发挥”内容，加上之后好了很多。

5. 核心链路完整编码实现

5.1 离线索引：从文档到向量库

把前面所有环节串起来，形成一个可复用的索引函数。我实际项目里会把数据路径配置做成了配置文件，这样文档更新时只需要替换路径，重新执行索引即可。

def build_vectorstore(doc_dir, persist_dir): # 1. 加载文档：遍历目录下所有PDF和MD文件 documents = [] for file in Path(doc_dir).rglob("*"): if file.suffix.lower() == ".pdf": loader = PyPDFLoader(str(file)) documents.extend(loader.load()) elif file.suffix.lower() == ".md": loader = UnstructuredMarkdownLoader(str(file)) documents.extend(loader.load()) # 2. 文本切分 text_splitter = RecursiveCharacterTextSplitter( chunk_size=600, chunk_overlap=80, separators=["\n\n", "\n", "。", "！", "？", ".", " ", ""] ) split_docs = text_splitter.split_documents(documents) # 3. 初始化Embedding模型和向量库 embedding_model = HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5") vectorstore = Chroma.from_documents( documents=split_docs, embedding=embedding_model, persist_directory=persist_dir ) return vectorstore

这个函数里你会注意到切分器的separators配置，我把中文句号、感叹号、问号都加了进去，因为中英文的句子边界完全是两回事，如果不加这些分隔符，切出来的块会非常粗糙，经常把两件不相干的事硬拼在一起。

5.2 在线问答：从问题到答案

索引建好后，问答链路由检索、重排、Prompt、大模型四部分组装。我把组装过程拆成清晰几步，便于你按需替换组件：

def create_qa_chain(vectorstore): # 1. 组装带重排的检索器 compression_retriever = build_reranker(vectorstore) # 2. 定义大模型（此处用标准OpenAI兼容接口） llm = ChatOpenAI( model="gpt-4o-mini", temperature=0.2, openai_api_base="https://your-endpoint/v1", openai_api_key="your-key" ) # 3. 组装LangChain表达式 def format_docs(docs): return "\n\n".join( f"[片段{i+1}] {doc.page_content}" for i, doc in enumerate(docs) ) rag_chain = ( {"context": compression_retriever | format_docs, "question": RunnablePassthrough()} | prompt_template | llm | StrOutputParser() ) return rag_chain answer = rag_chain.invoke("商品退款需要提供什么凭证？") print(answer)

LangChain表达式语言（LCEL）用管道符把各个组件串起来，读起来很直观：先检索并格式化上下文，然后填充Prompt模板，交给大模型，最后解析输出字符串。这种写法的好处是中间任何一步想插入自定义逻辑，都很方便。

5.3 检索结果溯源

这一点我特别想强调：RAG系统必须做到可溯源。用户问了一个问题，模型给出了回答，如果回答错了，你要能快速定位是检索错了、还是模型理解错了、还是文档本身就没写清楚。我在格式化函数里给每个片段加了编号，回答引用片段编号后，就能反查原始文档。

进一步，我建议你在检索结果的metadata里保留原始文件路径，并暴露给前端展示"参考来源"。实际做知识库产品时，这个功能在提升可信度方面的作用远超想象——用户看到答案下方附带了原文出处，对系统的信任感完全不一样。

def format_docs(docs): lines = [] for i, doc in enumerate(docs): source = doc.metadata.get("source", "未知来源") lines.append(f"[片段{i+1}] (来源:{source})\n{doc.page_content}") return "\n\n".join(lines)

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

6.1 中文文档切块导致的语义撕裂

我最早跑通项目时，回答质量很不稳定，排查后发现不少问题都出在切块上。当时用的是默认的分隔符，纯英文标点，中文文档被从毫无语义关系的地方切断，比如把"产品的保修期为一年，非人为损坏可免费维修"切成"产品的保修期为一年"和"非人为损坏可免费维修"两块，丢到知识库里后，检索"保修期多久"时召回的内容就不完整。

解决方式：在分隔符里加上中文字符的标点："。"、"！"、"？"、"；"。我用的是RecursiveCharacterTextSplitter，设置分隔符优先级后，它会优先在完整句子边界切分，语义完整性大幅提升。

另一个心得是，如果你的文档有很强的层级结构，Markdown标题是最好的切分边界。LangChain的MarkdownHeaderTextSplitter可以按标题层级切块，并按需把标题信息注入到每个块的正文里，这样每个块自带章节上下文。

6.2 检索结果相关但回答仍然错误

这个问题我排查了很久，最后发现根因不在检索侧，而在大模型侧。比如知识库里明明有准确的退货规则，模型回答却引用了过时的信息，或者直接答非所问。

这个现象背后的原因是：检索回来的Top N片段里，最相关的一条位于列表末尾，模型注意力被前面几条次相关的内容带偏了。解决方式有几个：

1. 把重排序的top_n调小，减少噪声输入；
2. 在Prompt中明确要求按"片段优先级"参考，先看前面的内容；
3. 适当调低模型的temperature参数，让它更“忠于”资料而少做自由发挥；
4. 如果条件允许，把回答生成过程拆分两段：先让模型对检索片段做摘要，再基于摘要回答，效果更稳但耗时会增加。

6.3 在线问答响应太慢

RAG问答链路天然比普通对话多两步耗时：Embedding向量化和检索。响应偏慢通常集中在两个环节：

一个是Embedding模型加载耗时。首次加载需要把模型权重读入内存，如果用的是大体积模型，初次请求可能要等好几秒。优化方向是：进程启动时预热模型，或者直接选择轻量的Embedding模型，中文场景下用小体积模型的效果差距没有想象中大。

另一个是检索返回的候选集太大，传给大模型的上下文过长。优化方向是调低k值、加重排序的top_n限制，把上下文压缩到必要的内容。实测把上下文从十几段压到四段，响应速度能快很多，回答质量不降反升。

6.4 向量库更新后老问答失效

典型场景：知识库文档更新了一批，重新做了索引，但用户问旧问题时，模型答案和更新前不一致，甚至变差了。这通常是因为新文档和旧文档在向量空间中存在交叉与覆盖，切块后的向量分布变化较大。

我建议的稳定做法是：版本化向量库目录。每次更新文档后，用新的目录名持久化，不要覆盖旧的存储路径。线上切换时先保留旧库一段时间，验证新库检索结果没问题后再切换。同时，更新范围如果只是部分文档，可以考虑只对增量文档做切块向量化，再追加到原向量库中，Chroma原生支持add_texts追加，这种方式比全量重建高效得多。

7. 经验总结与后续扩展建议

这套RAG知识库框架跑通之后，我最大的体会有三点。第一，RAG的成败大半取决于索引质量而不仅是模型能力强弱，处理好文档清洗和切块，比换更大的模型效果提升更明显。第二，重排序环节是整个链路里“性价比”最高的增强手段，投入一套开源重排序模型就能获得肉眼可见的效果提升。第三，Prompt中显式约束“不要编造，不知道就说不知道”，是从源头控制幻觉的关键，这个设计比任何后置的校验都有效。

后续想在实际业务中更进一步，我建议关注几个方向：

• 用多路召回策略，同时用关键词检索和向量检索做混合召回，再做融合排序，能兼顾精确匹配和语义匹配；
• 引入Agent能力，让模型自主判断是否需要检索、先检索哪一部分再做组合回答，适合复杂多跳问题；
• 上线前一定要建一套评测集，把几百条真实问答固化下来，每次改动后跑一遍回归，避免优化A问题的同时弄坏B问题；
• 如果文档需要实时更新，可以维护一个向量库增量同步的任务队列，接进文档变更事件里，省去全量重建的时间成本。

最后再分享一个小技巧：调试RAG时，别只盯着最终回答看，建议把每一步中间结果都打印出来——切块后的片段列表、向量检索命中了哪些块、重排序后的顺序、传给模型的完整Prompt——整套观察下来，你一眼就能定位是哪个环节出了问题。这套“链路可视化”的调试思路，在我后续好几个项目里都帮了大忙。