企业官网建设流程全解析

接手RAG项目之后，我逐渐意识到一个道理：检索效果的上限，在文档被送进向量库那一刻就已经锁死了。换句话说，多格式文档解析这一环做不好，后面不管是embedding、检索排序还是生成策略，都只是在一个坏地基上修修补补。前阵子有个朋友跟我抱怨，说他们给知识库接了几百份PDF和企业内部资料，结果用户问啥都答不对，我帮他排查了一下午，问题全出在最前面的解析环节——表格被切碎、扫描件根本没识别、页码标签全丢。这也是我为什么想着把系列的第二篇单独留给文档解析：它是RAG链路里最不性感、却最能决定成败的一步。

这篇文章会分别拆解PDF、Word、PPT、Excel、扫描件这几类最常见的文档格式，给出可以直接落地的解析方案、工具选型思路和代码级细节，最后把我这一年多踩过的坑和一些工程质量上的建议也一并分享出来。不管你是刚接触RAG，还是已经在做知识库优化，这一篇应该都能帮你省下不少试错时间。

1. 先想明白：解析为什么能决定RAG效果的上限

1.1 从链路关系看解析的"蝴蝶效应"

RAG的完整链路大致是：文档接入 → 解析 → 数据清洗 → 结构化 → 切片 → 向量化 → 检索 → 排序 → 生成。大多数团队把注意力放在后半段，调embedding模型、换rerank策略、优化prompt，效果却始终上不去。原因很简单：检索只能找到"被正确表达过的内容"。如果一段表格在解析时被读成了没有行列关系的纯文本流，检索阶段再怎么努力，也没办法把一个乱序的字符串和用户的"上周各区域销售额对比"对应起来。

我曾经做过一次数据体检，把一套知识库里检索不到的case全部拉出来，逐个反查源头，发现超过六成的问题出在解析环节：有的是PDF扫描件被当成有文本层的普通PDF处理，切片里全是OCR噪音；有的是Excel合并单元格导致大量空值，连累同一行的数据对不上；有的是PPT里文本框读取顺序和视觉顺序完全相反，用户问"第三页讲了什么"，向量检索到的却是第四页的内容。也就是说，上游一个看似很小的解析失误，会在向量化的过程中被放大，最终表现为"模型胡编"或"答非所问"。

1.2 为什么embedding阶段救不了解析错误

这里要展开说一个容易被忽略的技术细节：现有的embedding模型对输入文本的质量非常敏感。你把一个排版良好的段落丢进去，和把一段被硬切过的、字段错位的文本丢进去，得到的向量分布差异非常大。embedding模型本身不理解"文档结构"，它只是在词与词、句与句的共现关系上做语义映射，一旦文本被切得支离破碎，它就很难捕捉到真实的语义单元。

举个我实际遇到过的例子：一份PDF里的表格本来是"产品名称、规格、库存、价格"四列，用纯文本提取后变成了"产品名称规格库存价格"挤在一起，行与行的边界也丢了。embedding阶段确实能把这些词都编码进去，但检索"库存不足的产品"，返回的片段里关键词散落在各个位置，不仅命中率低，即便命中了，送给大模型做生成的上下文也是残缺的。所以我想强调的第一条经验是：别指望下游环节替你收拾解析的烂摊子。解析是唯一一个"一次做错、全链路背锅"的环节。

2. 按格式拆解：PDF、Word、PPT、Excel各自的正确打开方式

2.1 PDF：先回答三个问题再动手

拿到一份PDF，我习惯先问三个问题：这份PDF有没有文本层？里面有没有表格？有没有扫描出来的图像页？这三个问题决定了完全不同的技术路线。

• 有文本层的纯文本PDF：直接用PyMuPDF（也就是fitz）提取。它的速度比pdfplumber快很多，能拿到文字块的位置坐标（坐标这个信息后面排版本面顺序有用）。
• 需要提取表格的PDF：首选pdfplumber，它的extract_table()方法是基于字符坐标做聚类的，对有线表格和无线表格都有不错的识别率。注意它有明显的性能瓶颈：大文件解析速度偏慢，遇到几十页的报表建议按页切片后并行处理。
• 扫描件/图片型PDF：必须走OCR，不能交给任何文本提取库硬啃。检测方法很简单：用PyMuPDF打开后检查每一页的page.get_text()，如果文本长度几乎为0而页面包含大尺寸图像对象，基本可以判定是扫描页。

踩过一个很典型的坑：一份混合型PDF，前面20页是正常文本，后面10页是扫描附件。早期我的管线是全局套PyMuPDF提取，结果后面10页只有零星几个乱码词，检索系统还以为那是某种"加密内容"。后来改成逐页检查page.get_text()的输出长度，一旦低于某个阈值（我一般设30个字符）就直接把该页路由到OCR模块，问题立刻消失。这个页面级路由逻辑，是处理现实世界里"脏"PDF的关键。

2.2 两栏/多栏版面和跨页段落的处理

学术论文、行业报告里最常见的就是两栏排版。如果只是按阅读顺序把整页文本一次性提取出来，左栏和右栏的内容会交错混在一起，段落被"拦腰截断"。这里我的做法是：先拿到每个文本块的边界框（bounding box），按纵坐标分组，再在同一组内按横坐标排序，最后拼接出真正的两栏阅读序。说白了，就是用坐标自己重排阅读顺序，而不是盲目相信提取器的默认输出。

跨页段落是另一个高频问题。一个段落从第3页底部一直延续到第4页顶部，如果切片时按"页"做硬边界，这段内容就会被拆成两块，向量化时上下文信息直接丢失。我的处理习惯是做一个后处理步骤：提取文本时记录每个段落的起始与结尾，如果段落结尾没有句号或其他终止标点，就把它和下一页的开头合并。这个小规则不复杂，但对检索效果提升非常明显，尤其是处理长篇报告时。

2.3 Word、PPT、Excel：别在二进制格式上硬扛

.docx本身是一个zip包，里面是各种XML文件，python-docx库把这一层封装好了，直接用就行。要注意的是它只能处理docx，老版doc需要用其他方案先转换。很多人忽略的是标题样式：Word里的"标题1/标题2/标题3"不仅是视觉样式，它定义了文档的层级结构。如果你把它们保留下来，转成Markdown输出，后面的切片阶段直接按标题层级做分段，结构清晰还不会切乱。

.pptx用python-pptx读取，最麻烦的是shape的顺序问题：shape的读取顺序跟元素在幻灯片中的视觉位置没有必然关系。我的做法是遍历所有包含文本的shape，用shape.top和shape.left对文本框做排序，优先按从上到下、再按从左到右排。不然的话，文本会被读成乱序的单词组合，检索出来不知所云。另外要注意分组形状（GroupShape），它里面的子shape必须递归展开；还要留意SmartArt，python-pptx默认拿不到SmartArt的文本内容，需要走shape.text_frame之外的接口去尝试，这部分兼容性差，实在不行建议直接把整页转成图片交给视觉模型处理。

.xlsx用openpyxl，这里有个几乎必踩的坑：合并单元格。在openpyxl里，合并单元格区域只有左上角的值，其它单元格返回None。不处理的话，原始表格里的每一行几乎都缺数据。我的方案是做一个"向上填充"的清洗步骤：记录所有合并区域，然后把左上角的值复制到区域内所有其它单元格上。处理完之后，再决定表格要不要转成Markdown、还是按"表头+键值对"描述给模型。

2.4 统一输出：为什么我建议都转成Markdown

解析完各种格式之后，我强烈建议做一步"格式归一"：把解析结果统一转成Markdown（或者结构更细的JSON blocks）。原因有两点：一是Markdown能保留标题层级、表格、列表这些结构语义，embedding模型对带Markdown标记的结构化文本编码效果通常更好；二是后面切片时可以直接依据Markdown的标题标记来确定边界。

下面是我常用的一个归一化伪代码框架，展示的是思路，不是贴一个完整工具库：

def parse_document(file_path): ext = file_path.suffix.lower() # 按扩展名分发到不同的解析器 if ext in [".pdf"]: raw_blocks = parse_pdf(file_path) elif ext in [".docx"]: raw_blocks = parse_docx(file_path) elif ext in [".pptx"]: raw_blocks = parse_pptx(file_path) elif ext in [".xlsx"]: raw_blocks = parse_xlsx(file_path) else: raw_blocks = parse_other(file_path) # 统一转换为带结构的Markdown md_text = blocks_to_markdown(raw_blocks) return md_text

这个框架看起来简单，真正的工程量全在parse_pdf、parse_docx这些函数内部——每个函数都要处理版式、表格、图片、页码这些细节。但有了这层统一出口，后续所有模块都只需要面向一种数据结构开发，维护成本会大大降低。

3. 扫描件和图片：OCR这步怎么选、怎么用才不掉链子

3.1 OCR工具选型：开源优先，但要分场景

OCR是处理扫描件、拍照件、图片型PDF的唯一出路。我在这块试过好几套方案，简单说下结论。

• Tesseract：开源、老牌、免费。英文和印刷体识别效果尚可，但中文长文、复杂版面的识别效果一般。胜在部署简单，适合快速跑通流程，不太适合对中文准确率要求较高的生产环境。
• PaddleOCR：目前我处理中文文档的首选。识别精度、中文长文支持都明显更强，而且自带版面分析能力。它还有个PP-Structure模块，能直接输出表格的HTML结构，这个对"表格完整转出来"的场景特别有用。
• 云端OCR服务：适合对识别精度要求最严、愿意付费的场景。各云厂商都有，通常返回更规范的结构化结果。缺点是数据要出内网，对文档安全敏感的项目不建议。

选型其实没有唯一标准。我自己的经验是：先拿自己真实的文档样本去测，不要只看公开benchmark。公开数据集里都是规范印刷体，真实场景里手写批注、印章、水印、折痕、低分辨率扫描件，全是干扰项。一个OCR模型在公开测试集上95%准确率，到了你的扫描件上可能只有70%。所以我在评估OCR方案时，会专门准备一份"最脏"的样本集——就是实际业务里那些常被抱怨的文件——跑一轮，人工看一眼结果再拍板。

3.2 识别前先预处理：这一步决定了上限

很多人拿到一张歪歪扭扭的扫描件就急着丢给OCR模型，结果准确率上不去，反过来怪模型不行。实际上，预处理的质量直接决定了OCR的识别上限。我常用的预处理步骤包括：

1. 方向校正：用图像旋转检测判断页面方向，错误的方向会让OCR全军覆没，这一步如果交给模型事后纠错，代价太高。
2. 去模糊/增强对比度：用OpenCV做自适应阈值或直方图均衡，让笔画和背景的对比更清晰。
3. 去噪点、去黑边、去手写干扰：扫描件常见黑边和底纹，不做处理很容易被识别成"文字噪声"。
4. 倾斜校正（deskew）：页面歪了，行识别就会乱，校正之后能大幅提升行切分准确率。

预处理接口基本是OpenCV那套，每步都有现成示例，难点在于参数需要针对你的样本调。建议把这四步做成一个封装函数，统一在送入OCR之前调用，并给每一步留出可视化对比的开关，调试时能直接看到哪一步出了问题。

3.3 OCR结果的版面重建：别把文字"读平"

OCR出来的结果如果只是"逐行输出文字"，那它跟一个低质量的纯文本提取器没有本质区别——版面信息全丢了。尤其是多栏文档和带表格的文档，OCR之后必须做版面重建。

我通常的做法是：用PaddleOCR的版面分析能力，先识别出页面上的标题、正文、表格、图片区域，然后对每个区域单独处理。表格区域走表格结构识别，拿到行列关系之后转成Markdown表格；标题区域按文字大小和位置判断层级；正文区域保持原有段落顺序。这样处理完，输出的Markdown保留了文档的层级关系，后续检索和切片的质量才能有保障。

这里也顺带提一个容易踩的误区：OCR输出有置信度分数，别一股脑全收。我的经验是设置一个置信度阈值（通常在0.7到0.8之间，视数据情况调整），低于阈值的字符块标记为"低置信度"并单独记录。这些低置信度片段要么人工复核，要么在检索时加权降低，避免它们污染向量库。

4. 解析之后马上要做的三件事：结构化、切片与元数据

4.1 结构化：不只存文本，还要存"骨架"

解析完成后，如果你只是把大段文本丢进向量库，那前面做的版式识别、标题层级还原就全浪费了。我会把解析结果组织成一种"半结构化"的表达方式，简单来说就是把文档拆成一个一个带属性的块（block）。每个block不是孤立字符串，它带有一组元数据字段：

• block_type：是标题、正文、表格、列表、图片说明，还是代码块。
• title_path：当前块所在的完整标题路径，比如"第2章 / 2.3 节 / 技术方案"。
• page_number：原始页码，排查问题和做引用溯源时尤为重要。
• source_file：文件名和文件路径。
• keywords：从原文档里抽取的关键词，辅助检索。

这个骨架的价值在于：它让大模型在生成回答时能感知到"这是从哪里来的内容"。用户问"这个结论出自哪个章节"，如果块上带着标题路径，检索系统就能直接给出答案，而不是靠模型在纯文本里瞎猜。

举一个递归切片的设计思路。假设我按"标题路径"把文档切成了若干块，一个二级标题下面的正文可能很长，直接作为一个向量块太粗，切成几段又可能破坏结构。这时可以用父子切片（parent-child chunking）：父块保留较大上下文（比如整个二级标题下的内容），子块切成适合embedding的较小片段（比如256或512 token）。检索时用子块去匹配，召回后把对应父块的整体内容交给大模型做生成。这样既保住了召回精度，又保住了上下文完整性。

4.2 切片：边界怎么选，重叠多少合适

切片策略最常见的两个参数是块大小（chunk size）和重叠窗口（overlap）。我在不同项目里的经验值大概是：常规文档用400~800token作为一个块，50~100token的重叠窗口；代码文件用更小的块、更大比例的重叠，因为代码的结构化程度更高、语义密度更大。

但真正影响质量的不是这两个数字本身，而是切片的边界跟文档结构的对齐程度。结构对齐的思路我已经在前面提过：优先按标题层级切，其次按段落切，最后才按固定长度切。如果你直接把固定长度切片接在不考虑结构的纯文本上，那大概率会把一个段落从中间切断。我见过太多人调chunk size参数调了两个小时，最后发现问题是"段落边界识别不出来"。先做好结构化，再谈切片参数，顺序不能反。

4.3 元数据：被忽视的"检索放大器"

元数据用好了，能大幅降低检索的误召回。比如一份包含多款产品参数的Excel，如果解析时把"产品型号"抽取成元数据字段，用户检索"型号A的功耗"时，就可以先按元数据过滤，再做向量检索，命中率会高很多。

元数据还能解决"全文检索"查不到的问题：向量检索本质是语义匹配，它不擅长精确匹配产品编号、日期等字符串。我的做法是在向量检索之外，保留一个传统全文检索通道（比如BM25），检索时对两个通道做结果融合（RAGFusion的思路），再用交叉编码器重排。这个组合策略在多个项目里效果都稳定优于单一通道，而它能生效的前提，正是解析阶段把元数据完整保留了下来。所以我会说：元数据设计要从解析阶段就开始，而不是等向量库建好了再回头补。

5. 我在线上环境踩过的多格式解析坑（附带完整排查链路）

5.1 症状一：检索结果全是乱码，答非所问

有个内部知识库项目上线后，用户反馈"问什么都得到一堆乱码"。我当时的排查链路是这样的：

1. 先看日志里检索到的chunk文本，发现大量chunk内容是"#￥%……&"之类的无意义字符，或者干脆空白。
2. 反查源文件，发现这些都是同一个PDF的扫描页。
3. 进一步确认，解析管线的路由逻辑只按扩展名走PDF文本提取，没有做页面级扫描检测。

修复方案是给PDF解析加一道前置逻辑：提取每一页的文本长度，如果整页文本少于阈值，且该页包含图像对象，就把这一页单独路由到OCR模块。同时把OCR置信度低于阈值的文本丢弃，避免把低质量噪音写进向量库。这个问题本质上是格式假设错误：想当然认为"PDF=有文本层"，没有做页面级检测。

5.2 症状二：表格数据张冠李戴，数值全部错位

另一个典型case是财务表格检索，"上季度收入"查出来的是"本季度支出"。排查链路：

1. 检索命中的chunk确实包含"收入"和"本季度"这些词，但上下文里表格的行列关系是乱的。
2. 反查源文件，这是一个多行多列的PDF表格，表格区域带跨页。
3. 原来的解析器输出的是线性文本流，行列边界和跨页关系全丢了。

修复方案是给表格单独开一条路：先做表格区域检测，用专门的表格识别模块输出HTML/Markdown表格，不做纯文本流式输出。跨页表格则按表头复制到每一页，保证每个分页的表格都自包含。这个坑最值得说的点是：表格不能当"文字"处理，它的二维结构本身就是信息。想逼着文本提取器把表格读好，根本就是不现实的。

5.3 症状三：PPT里的顺序错乱，检索永远找不对页

还有一个问题来自PPT解析：用户问"方案的背景是什么"，检索返回的是"方案总结"那一页的内容。实话说这类问题很隐蔽。我的排查过程是这样的：

1. 在向量库里看到命中的chunk文本来源确实指向某个PPT文件。
2. 把那一页的原文提取出来人工对比，发现文本内容存在，但顺序完全乱掉，一句话被拆成了三段。
3. 检查解析代码，发现问题出在python-pptx遍历shape时没有按坐标排序，读到的顺序和视觉顺序不一致。

修复其实并不难：遍历所有含文字的shape，按top、left排序后再拼接文本。但更难的是在那之前发现问题需要分析现场，因为顺序错乱并不直观。我的建议是线下多找几个复杂PPT做抽样人工体验，而不是等到用户反馈。

5.4 症状四：Excel合并单元格导致大量空数据

这个问题在Excel类知识库里太常见了。排查时看到的部分chunk是"产品A || 缺 || 缺 || 缺"，以为是解析丢失数据，实际是合并单元格带来的None值。修复方案就是前面提到的向上填充逻辑：先读取所有合并区域，把左上角值复制到区域内所有单元格，再去做后续结构化。这个坑的隐蔽性在于openpyxl不会报错，只是默默返回空值。建议凡是接Excel的人，第一件事就检查数据里有没有异常多的空单元格，发现了先怀疑合并单元格。

5.5 症状五：Word里图片信息全丢，图文类问答无法回答

还有一类文档大量使用"图片+文字说明"，用户问"架构图里画了什么"，检索结果里只有图片文件名，完全没有图像内容。这个问题要分两层看：一是解析时默认丢弃了图片，二是就算提取了图片，embedding模型自己也不能理解图像。

我的方案是对这类图中带信息的文档，解析时把图片截取出来，通过一个视觉理解模型（或多模态描述模型）生成图片的文字描述，再把描述作为原块的一个补充字段。这样用户检索图片内容时，能通过描述文本命中。这个方案会额外消耗算力，我通常只对"图片含核心信息"的场景开启，并用一个简单的规则判断图片是否值得处理，比如判断图片尺寸、面积占比和文档类型。

6. 把这套解析管线落地的工程化建议

6.1 先做文件类型识别，别轻信扩展名

现实世界里的文件格式非常混乱：扩展名是pdf，内容其实是扫描图片；扩展名是docx，里面嵌入一堆OLE对象。我的建议是用文件内容的magic number做探测，而不是用扩展名。在Python里可以用python-magic或者直接读文件头字节判断真实类型。同时还要考虑加密文件、损坏文件的情况。这些异常如果在解析前不拦截，到了解析器里大概率导致超时或崩溃，而且排查起来非常痛苦。

6.2 解析任务要可观测、可重试

解析是计算密集、又容易出错的一环。我的工程标准是给每个文件生成一条解析记录，包含文件路径、文件大小、格式、解析器版本、耗时、输出的块数量、失败阶段、错误信息。这些日志存到独立的表或者文件里，方便随时回溯。

另外建议做两级重试：单文件解析失败自动重试两次，重试仍失败的进入死信队列，由人工或降级方案处理。别小看这一个机制，在我经历的项目里，"解析失败静默吞掉"是导致知识库数据缺失的最常见原因。加一个队列和告警，比你后续做多少检索优化都管用。

6.3 性能优化：该并行就并行，该缓存就缓存

解析是吃CPU的活。我的实践是：单机处理中小规模文档库，用Python的多进程并行解析，进程数按CPU核心数和IO比例调整；如果文档量大、格式杂，优先考虑队列拆分的分布式方案，按文件格式分发到不同worker。这里要注意一个细节：很多解析库内部已经用了C扩展，Python多线程受GIL限制收益不大，直接用多进程更划算。

缓存也很重要。同一个文件如果内容没变，解析结果可以直接复用，不需要每次全量重新解析。可以对文件做哈希（MD5或SHA-256），用哈希值和解析结果存入缓存。这个优化在文档库定期增量更新时能省下大量计算。

6.4 解析输出要保留"可追溯"能力

最后一个建议跟AI生成的可信度有关。现在很多RAG应用都要求回答附上引用来源。如果解析阶段把原始页码、章节路径这些信息丢失，后面想让模型给出准确的引用依据，几乎做不到。我的做法是把原始文档的页码范围、标题路径、block类型这些元数据一直保留到最终检索阶段，让大模型在生成时能够输出结构化的引用信息。这一步做扎实了，整个系统的可信度和用户体验都会有质的提升。

关于多格式文档解析，我目前能分享的实战经验大概就是这些。说句实在话，这个领域没有一个"一次性搞定所有格式"的神仙工具，每个方案都是在准确率、速度、成本和可维护性之间做权衡。如果你正打算搭RAG系统，我唯一的建议是多花点时间在解析环节做测试，尤其是拿自己真实的脏文档样本去压测。前期多花一天清理解析问题，后面就可能省下一周调检索效果的时间。