企业官网建设流程全解析

做RAG应用的朋友大概率都绕不开一个场景：手里攒了一堆PDF文档——可能是产品手册、行业报告、内部规范，想把这些非结构化内容变成大模型能用的知识库。从零搭一套流水线听起来吓人，实际动手之后你会发现，LangChain把PDF读取到向量数据库落地这条链路上的大部分脏活都封装好了，核心代码可能不到三十行。但能跑通和能用好之间隔着不少细节：分块策略怎么定、embedding模型如何选、检索参数怎么调，这些直接决定最终回答质量的高低。

这篇内容面向已经了解Python基础、想动手搭一套文档问答原型的开发者，也会照顾到刚接触RAG概念、需要一份完整操作路径的朋友。我会从整体架构讲起，拆解PDF读取的几种方案、文本切分的参数逻辑、向量数据库的选型与落地，再结合我自己踩过的坑，给出一份可直接复现的实操流程和排错清单。核心关键词围绕LangChain、PDF读取、向量数据库、文本分块和embedding展开，读完你可以拿自己手头的文档跑起来一套可用的检索链路。

1. 整体架构与方案选型思路

在动手写代码前，先把这条流水线的骨架说清楚。一个典型的PDF文档问答系统，本质上做的是四件事：把PDF里的文字提取出来、把长文本切成合适大小的块、把每块文本转成向量存进数据库、用户提问时检索出最相关的块交给模型回答。LangChain在这四个环节里都提供了对应的抽象层，让你不用从零造轮子，也方便后续替换组件。

我为什么坚持用LangChain而不是裸调OpenAI SDK或直接用PyPDF2：核心原因是它的组件抽象做得比较干净，Document对象、TextSplitter、VectorStore、Retriever各司其职。你可以在开发阶段用Chroma做本地向量库，上线时换成别的数据库，加载器和切分器的代码基本不用动。这种可替换性在做原型验证时特别值钱，你能用最短时间横向对比不同embedding模型和不同切分策略对检索效果的影响。

1.1 为什么PDF读取是整条链路的第一个瓶颈

很多人以为PDF就是一个带格式的文本文件，读出来就行。实际不是。PDF本质上是一套打印指令集合，它描述的是“在哪个坐标画哪个字形”，而不是“这段文字在逻辑上是第几段”。这就导致两个直接问题：第一，纯文本提取出来的内容可能丢失段落结构，出现大量换行错乱；第二，扫描件PDF根本没有文字层，直接读只能拿到空白。

LangChain封装了多种PDF加载器，底层分别调用了不同的解析库，适用场景差异很大。我在项目里试过三种主流方案，结论是：能拿到文字层的原生PDF用PyPDFLoader就够了，表格多或版式复杂的用pdfplumber，扫描件必须走OCR分支。不要一上来就上最重的方案，先拿样本文件测一下提取质量再决定，能省掉大量调试时间。

1.2 文本分块策略的核心权衡

分块（chunking）是整条链路里最容易被忽视、却对检索质量影响最大的环节。切得太碎，单块信息不完整，模型拿到手也答不出东西；切得太粗，一块里面混了好几个主题，向量表示被稀释，检索精度直线下滑。

LangChain提供了一套RecursiveCharacterTextSplitter，它的逻辑是优先按段落切，段落太长再按句子切，句子还长就按字符硬切。这个设计的好处是尽量保持语义边界完整。工程实践中，中文文档的chunk_size我一般从500字左右起步，chunk_overlap控制在50到100字之间，overlap的作用是让相邻块之间保留一点上下文衔接，避免一个完整意思刚好被切断后两边都读不懂。这是一组经验起点，不是标准答案，具体值要结合文档密度和问题粒度去调。

1.3 向量数据库的选型逻辑

向量数据库这个领域这两年卷得厉害，从FAISS、Chroma、Milvus到Pinecone、Weaviate，选择面很宽。做原型阶段我不建议一上来就部署分布式方案，Chroma是本地验证阶段最省心的选择：pip装上就能用，支持持久化到本地目录，API简单，和LangChain的集成也是开箱即用。等到数据量上了百万级、或者需要多人并发查询时，再考虑迁移到Milvus这类专门的向量数据库。

选型时要说清楚一个容易被混淆的概念：向量数据库本身不负责把文本变成向量，那是embedding模型的活。数据库只负责存向量、建索引、做近似最近邻搜索。所以真正影响检索质量的第一个决策是embedding模型，第二个才是数据库的索引参数。同一个embedding模型换个数据库，召回率不会差太多；但换个embedding模型，那就是两个世界。

2. PDF读取的实操细节与避坑

这一节把PDF读取拆开讲透。看似简单的一步，藏着的坑比后面所有环节加起来还多。

2.1 三种加载器的适用场景与实测对比

LangChain里跟PDF相关的加载器不少，常用的有这么几个，我按实际使用频率排一下：

我个人的实际组合是：先用PyMuPDFLoader跑一遍，检查提取出的文本质量；如果表格或双栏排版错乱严重，再针对那批文件切换到PDFPlumberLoader单独处理。PyMuPDF底层是C库，解析速度比pypdf快不少，中文提取的乱码概率也低一些，这在处理大批量文档时体感很明显。

注意：加载器返回的是Document对象列表，每个元素包含page_content和metadata。metadata里通常有source（文件路径）和page（页码），这两个字段在后续做溯源引用时非常有用，不要图省事直接丢掉。

2.2 扫描件与乱码的应对办法

扫描件PDF没有文字层，直接调加载器返回的基本是空字符串或者一堆无意义字符。判断方法很简单：读一份文件，看page_content的字符长度，如果和预期页数严重不匹配（比如十页的文件只返回两百个字符），大概率就是扫描件。

处理扫描件需要引入OCR。常见的组合是先用PyMuPDF把PDF页面渲染成图片，再调OCR引擎识别文字。这一步在LangChain里没有一键方案，需要自己写个循环，比较折腾。所以我的建议是：动手前先抽样检查文档来源，把扫描件挑出来单独处理，别让少量坏样本污染整个流水线。如果扫描件占比很高，就在架构里明确加一个预处理阶段，而不是指望加载器自动兜底。

至于文字层PDF的乱码，中文场景下最常见的原因是字体编码问题，提取出来的可能是各种奇怪符号。这个在PyPDFLoader上比较常见，换成PyMuPDFLoader通常能缓解。如果换加载器还不行，那就得检查PDF本身的编码方式，这种情况比较少见，遇到再单独处理。

2.3 读取后的文本清洗不能省

加载器吐出来的文本，直接拿去切分往往效果很差。常见问题是：页眉页脚重复出现、段落间多余空行、连字符断词、特殊符号残留。这些噪音会稀释向量的语义信息。

我一般会做几件简单但有效的清洗：用正则去掉连续空白行，把单个换行替换成空格（中文文档尤其重要，因为PDF提取常把一个段落拆成多行，保留换行会让切分器误判段落边界），去掉页眉页脚的固定模式字符串。清洗代码不用复杂，十几行正则就能覆盖大部分场景，但带来的检索质量提升很直观。这一步很多人跳过，后面发现检索结果总带一堆无关片段，回头排查才发现是脏文本导致的。

3. 文本切分与向量化的参数设计

PDF读进来之后，紧接着就是切分和向量化。这两个环节的参数选择直接决定检索质量的上限，值得花时间单独讲。

3.1 RecursiveCharacterTextSplitter的中文适配

RecursiveCharacterTextSplitter的默认分隔符列表是按英文习惯设计的，对中文来说需要调整。中文没有空格分词，段落内常常没有明显标点，所以我把separators参数改成优先按中文标点和换行切：

from langchain.text_splitter import RecursiveCharacterTextSplitter splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=80, separators=["\n\n", "\n", "。", "！", "？", "；", "，", " ", ""], length_function=len, )

这里的逻辑是：先尝试在双换行处切（段落边界），不行再单换行，再不行在句号问号处切，以此类推。length_function我用的是len直接数字符数，中文场景下按字符计比按token计更直观，虽然和模型的token计数不完全对齐，但工程上够用。

chunk_size=500这个值的含义是每块大约500个字符，对应中文大概是一个中等段落的长度。这个粒度下，单块通常能容纳一个完整的小主题，又不会混入太多无关内容。如果文档是操作手册这类条目清晰的，可以降到300字左右提高精度；如果是长篇论述类文档，可以放宽到800字保持上下文完整。没有万能值，拿几条典型查询实测召回效果再定。

3.2 向量化的模型选择与成本考量

向量化就是把文本块转成高维浮点数组，这个数组的语义距离能反映文本的语义相似度。LangChain支持多种embedding接入方式，选型时要考虑三个因素：语言支持、向量维度、调用成本。

中文场景下，我优先考虑对中文优化过的模型。向量维度方面，常见的有768维、1024维、1536维，维度越高表达力越强但存储和检索成本也越高。做本地验证时可以用轻量的开源embedding模型跑通流程，这个阶段不需要追求极致效果，先把链路跑顺。等确认架构没问题，再对比几个候选模型在真实查询集上的召回率，选性价比最高的那个。

实操心得：embedding模型一旦确定，入库的向量就和它绑定了。后续换模型意味着所有文档要重新向量化一遍。所以不要频繁换模型，定下来之前多花点时间做横向评测。我吃过一次亏，中途换模型导致整个库重灌，几千个文档重跑了大半天。

3.3 批量向量化时的工程细节

文档量大的时候，向量化是整条链路里最耗时的环节。LangChain的向量库封装了add_documents方法，内部会分批调用embedding接口，但批次大小和并发策略需要自己控制。我的做法是显式分批，每批50到100个chunk，批间加个短暂间隔，避免触发接口的速率限制。

另外要留好断点续传的能力。几千个文档灌到一半报错重来，那种体验很糟糕。简单做法是记录已处理的文件列表到本地，重跑时跳过。复杂一点的做法是把向量化结果按文件维度落盘，任何一步失败都能从文件级别恢复。原型阶段可以用最土的方式——宁可慢也别让一次失败全部重来。

4. 向量数据库落地与检索调优

向量入库之后，检索环节的调参才是决定最终体验的地方。这一节讲Chroma的落地细节和检索参数怎么调。

4.1 Chroma的本地持久化与集合管理

Chroma最省心的用法是持久化到本地目录，重启之后数据还在：

from langchain_chroma import Chroma vectorstore = Chroma.from_documents( documents=chunks, embedding=embeddings, persist_directory="./chroma_db", collection_name="pdf_knowledge", )

collection_name这个参数值得留意。同一个目录下可以建多个集合，相当于逻辑上的多张表。我习惯按文档类别分集合，比如产品手册一个集合、行业报告一个集合，检索时按需选择，避免不同主题的文档混在一起互相干扰。如果所有文档都塞一个集合，检索时容易出现语义漂移，问产品问题却召回报告里的段落。

Chroma默认用余弦相似度做距离度量，这个对文本检索是合适的。如果后续要调整索引参数，Chroma也支持配置HNSW的构建参数，但原型阶段默认值足够用，先别过早优化。

4.2 检索参数top_k与相似度阈值的配合

检索时最关键的两个参数是返回条数top_k和相似度阈值。top_k设太小，可能漏掉相关块；设太大，会把不相关的块塞给模型，反而干扰回答。我的经验起点是top_k=4到6，配合一个相似度阈值做过滤，低于阈值的块直接丢弃，宁可少给也不要给错。

LangChain的检索器支持similarity_score_threshold参数，可以同时设置返回条数和最低分数。这里要注意，不同embedding模型和距离度量方式下，分数的量纲完全不同，阈值不能照搬。余弦相似度下通常在0.7以上算强相关，但这个数值必须在自己的数据上实测校准。

还有一种提升检索质量的手段是MMR（最大边际相关性），它在选块时兼顾相关性和多样性，避免返回一堆内容雷同的块。当文档里有大量重复表述时，MMR的效果比较明显：

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

fetch_k是先从库里取多少候选，lambda_mult控制相关性和多样性的平衡。0.7偏向相关性，调低会更多样。这组参数我一般先在测试集上跑一遍看召回，再微调。

4.3 检索质量的自测方法

调参不能凭感觉，得有个简单的评测集。我会从文档里挑20到30个真实可能被问到的问题，人工标注每个问题应该命中的文档块，然后跑检索看命中率。这个评测集不需要复杂工具，一个文本文件记录问题和期望命中的chunk标识即可。

实测下来，影响召回率的因素里，分块策略的权重往往比embedding模型还大。一个切得合理的500字块，用中等embedding模型也能召回得不错；而切得乱七八糟的块，用顶级模型也救不回来。所以当检索效果不理想时，我排查的顺序是：先看分块质量，再看embedding模型，最后看数据库索引参数。这个顺序能帮你避免在错误的方向上浪费时间。

5. 常见问题排查与实操避坑录

链路跑起来之后，问题往往不是报错，而是“检索结果不太对”。下面这些是我实际遇到过的典型情况，整理成速查表方便对照。

表格之外，再补几个不容易从报错里看出来的坑。

第一个坑是元数据丢失导致无法溯源。很多人在切分时只保留page_content，把metadata丢了，结果检索出相关块之后无法告诉用户这段内容来自哪个文件哪一页。正确做法是在切分时用split_documents而不是split_text，前者会保留每个块继承的元数据。这个小细节在做引用展示时非常关键。

第二个坑是中文标点被切分器忽略。默认分隔符列表里没有中文句号，会导致大段中文被硬切，语义边界全乱。前面给的分隔符配置就是针对这个问题的，别忘了改。

第三个坑是把所有文档塞进一个集合后不做区分。不同来源的文档在向量空间里可能互相干扰，尤其是术语体系不一致的时候。按类别分集合是成本最低的解法，如果暂时不想分，至少在检索后加一步重排序（rerank），用交叉编码器对候选块做精排，效果提升立竿见影，代价是多一次模型调用。

第四个坑是改了切分参数却忘了重新灌库。向量库里存的是旧切分结果，你改了chunk_size但只重跑了切分代码，库里还是老数据。这种不一致排查起来很隐蔽，因为代码看起来是对的，实际检索用的还是旧向量。每次改切分或换embedding模型，都要清空集合重新灌，养成这个习惯能少走很多弯路。

最后分享一个我在调参时的小技巧：拿同一个问题，分别用top_k=3、5、8跑一遍，把召回的块打印出来人工对比。很多时候你以为是模型不行，实际上是top_k设小了漏掉了关键块，或者设大了混进了噪音。这种土办法比看指标直观得多，几轮下来对参数的手感就有了。