企业官网建设流程全解析

1. 为什么 RAG 项目里 PDF 解析总在拖后腿

做过 RAG 的人大概率都经历过这个场景：向量库搭好了，Embedding 模型选好了，检索链路也跑通了，结果一测效果，答非所问。回头一查，问题出在最上游——PDF 解析出来的文本乱七八糟，表格串行、段落断裂、页眉页脚混进正文、扫描件直接是空白。检索增强生成这套架构，检索质量的上限很大程度上被原始文档的解析质量卡死了。

pdf-inspector这个工具就是冲着这个痛点来的。它做的事情说起来很朴素：把 PDF 里的内容尽可能还原成结构化的 Markdown，让下游的切分、向量化、检索环节拿到的是干净、有层次、带语义边界的文本。适合谁用？正在搭建 RAG 知识库的工程师、需要批量处理 PDF 文档的数据团队、以及任何被 PDF 转文本折磨过的人。

我自己的项目里前后换过四五种 PDF 解析方案，从最粗暴的pdfplumber逐行抽取，到后来上 OCR 兜底，再到引入版面分析模型，踩的坑足够写一篇长文。pdf-inspector吸引我的地方在于它把"检查"和"转换"两件事合在了一起——先判断这个 PDF 是什么类型（文本型、扫描型、混合型），再决定用什么策略处理，而不是一根筋地套同一个流程。这个思路在批量处理场景下特别关键，因为真实世界的 PDF 从来不是统一格式的。

下面我会从整体设计思路、核心细节、实操流程、问题排查几个维度，把这个工具的使用方法和背后的逻辑讲透，尽量让不同基础的人都能直接抄作业。

2. 整体设计思路与方案选型拆解

2.1 PDF 解析的本质难点在哪里

要理解pdf-inspector的价值，得先搞清楚 PDF 这个格式为什么难搞。PDF 的设计目标是"精确呈现"，不是"语义表达"。它描述的是"在坐标 (x, y) 处画一个字符"，而不是"这里有一个段落"。所以同一段文字，在 PDF 内部可能被拆成几十个独立的文本绘制指令，顺序还未必和阅读顺序一致。

这就带来几个典型问题。第一是阅读顺序错乱：双栏排版的论文，按坐标顺序抽出来会变成左右栏交错，读起来像乱码。第二是表格结构丢失：表格在 PDF 里就是一堆线和一堆文字，没有"单元格"的概念，抽出来往往是一坨。第三是页眉页脚污染：每页重复的页眉页脚会被当成正文切进 chunk，稀释检索信号。第四是扫描件无文本层：纯图片 PDF 根本没有可提取的文字，必须走 OCR。

pdf-inspector的设计思路，是先做类型判定，再走差异化处理管线。文本型 PDF 走原生文本提取加版面重建，扫描型走 OCR，混合型则按页分别处理。这个"先诊断后治疗"的逻辑，是它区别于很多单一功能库的核心。

2.2 为什么输出格式选 Markdown 而不是纯文本

很多人会问，为什么不直接输出纯文本，非要转 Markdown？这里有个容易被忽略的点：RAG 的切分策略高度依赖结构信息。

纯文本丢掉了标题层级、列表、表格这些结构，切分时只能按固定长度硬切，很容易把一个完整语义单元从中间劈开。而 Markdown 保留了#标题、-列表、|表格这些标记，切分器可以按标题层级做语义切分，让每个 chunk 尽量是一个完整的知识点。

举个实际例子。一份产品手册里，"安装步骤"是个二级标题，下面有五个有序步骤。纯文本切分可能在第 300 字处切断，把第三步和第四步分到两个 chunk 里。而 Markdown 保留了标题和列表结构，切分器可以识别出"这是一个完整的步骤列表"，要么整体保留，要么在步骤边界切分。检索时命中率明显不一样。

提示：Markdown 的表格语法对 RAG 特别友好，因为表格转成 Markdown 后，每一行都自带表头语义，向量化时能保留"这一列是什么含义"的信息，比纯文本的逗号分隔强太多。

2.3 工具选型的横向对比

在决定用pdf-inspector之前，我把常见的几类方案都试了一遍，这里做个对比，方便你判断自己的场景该选哪个。

pdf-inspector的定位在第二类，但它把 OCR 作为兜底能力整合进来了，所以混合型 PDF 也能一把梭。如果你的文档里既有文本型又有扫描型，用它比维护两套流程省事得多。

2.4 处理管线的整体架构

从使用者的角度看，pdf-inspector的处理流程大致是这样一条链路：输入 PDF 后，先做页面级类型检测，判断每页是文本层可提取还是需要 OCR；然后对文本页做版面元素识别，区分标题、正文、表格、图片、页眉页脚；接着做阅读顺序重排，把坐标顺序还原成人类阅读顺序；再对表格做结构重建，输出 Markdown 表格；最后清洗冗余内容，去掉页眉页脚和重复水印，输出统一的 Markdown。

这条链路里，最影响最终质量的是版面元素识别和阅读顺序重排。前者决定了标题层级对不对，后者决定了段落有没有被拆散。很多解析工具在这两步偷懒，结果就是文本抽出来了但没法用。

3. 核心细节解析与实操要点

3.1 类型检测：先搞清楚你面对的是什么 PDF

批量处理前，强烈建议先做一次类型普查。我见过太多人上来就无脑跑 OCR，结果文本型 PDF 被 OCR 一遍，识别错误反而引入了噪声。pdf-inspector的类型检测逻辑，核心是看每页有没有可提取的文本层，以及文本层的字符密度。

判断标准可以简化为：如果一页能提取出的字符数超过某个阈值（比如 50 个），且这些字符不是乱码，就判定为文本页；否则判定为扫描页，走 OCR。混合型 PDF 就是两种页面都有。

实操时你可以先跑一个统计脚本，看看文档里文本页和扫描页的比例。如果扫描页占比很高，就要提前规划 OCR 的算力，因为 OCR 是整条链路里最慢的一环。

# 伪代码示意：页面类型普查思路 from pdf_inspector import inspect_pdf report = inspect_pdf("manual.pdf") print(f"总页数: {report.total_pages}") print(f"文本页: {report.text_pages}") print(f"扫描页: {report.scan_pages}") print(f"混合型: {report.is_mixed}")

注意：类型检测的阈值不要设得太死。有些 PDF 每页只有页码是文本层，正文全是图，这种如果阈值设低了会被误判成文本页，结果抽出来只有页码。建议阈值结合字符分布来看，而不是只看总数。

3.2 版面元素识别：标题、正文、表格怎么区分

版面识别的核心依据是字体大小、字重、位置和间距。标题通常字号更大、加粗、独占一行、上下留白多；正文是常规字号、行距均匀；表格有明显的横竖线或对齐的列结构。

pdf-inspector会综合这些特征给每个文本块打标签。这里有个经验：不要完全信任自动识别的标题层级。很多 PDF 的标题字号设置很随意，一级标题和二级标题可能只差 1pt，自动识别容易串。我的做法是识别完之后人工抽查前几页，如果层级乱了，就调整字号映射规则再重跑。

表格识别是另一个难点。有框线的表格相对好办，靠检测线条就能还原单元格；无框线但靠对齐排布的表格就麻烦，需要靠列坐标聚类来推断。实测下来，有框线的表格还原准确率能到 90% 以上，无框线的看排版规整程度，规整的能到 80%，不规整的可能只有 50%，这种就得考虑单独走 OCR 或人工修正。

3.3 阅读顺序重排：双栏排版怎么救

双栏排版是阅读顺序错乱的重灾区。按坐标从上到下、从左到右抽，会得到"左栏第一行、右栏第一行、左栏第二行……"这种交错结果。

正确的做法是先做栏检测，把页面按垂直空白切成左右两栏，然后先读完左栏再读右栏。pdf-inspector内部会做这个分栏判断，但前提是栏间距足够明显。如果两栏之间没有明显的空白分隔，或者有跨栏的图表，判断就可能出错。

我的经验是，遇到复杂排版的文档，处理完一定要抽样检查阅读顺序。可以随机抽几页，把解析结果和原 PDF 对照着看，重点看段落有没有被拆散、句子有没有前后颠倒。这一步花十分钟，能省下后面调试检索效果的好几个小时。

3.4 页眉页脚与水印清洗

页眉页脚是 RAG 的隐形杀手。它们每页重复出现，向量化后会在检索时频繁命中，把真正相关的内容挤下去。清洗逻辑通常是：统计每页顶部和底部固定区域出现的文本，如果某个文本在超过 80% 的页面都出现，就判定为页眉页脚，统一删除。

水印更麻烦，因为它可能斜着印在正文中间，和正文文字混在一起。简单的文字水印可以靠颜色或透明度特征过滤，图片水印就得靠 OCR 后的文本匹配来剔除。这块没有银弹，只能针对具体文档调规则。

提示：清洗规则建议做成可配置的，不同来源的 PDF 页眉页脚格式不一样，硬编码一套规则换个文档就失效。把"顶部区域高度""底部区域高度""重复率阈值"这些做成参数，换文档时调一调就行。

3.5 OCR 兜底：什么时候该用、怎么用

OCR 不是万能的，用错地方反而添乱。判断标准很简单：有文本层的页面绝不走 OCR。OCR 会引入识别错误，本来准确的文本层被 OCR 一遍，反而变差了。

只有扫描页才需要 OCR。OCR 的质量取决于几个因素：扫描分辨率（建议 300 DPI 以上）、图像是否倾斜、文字是否清晰、语言是否匹配。中文 OCR 和英文 OCR 用的模型不一样，混排文档要选支持多语言的模型。

# 伪代码示意：对扫描页启用 OCR from pdf_inspector import convert result = convert( "scanned_doc.pdf", ocr_enabled=True, ocr_lang="ch", # 中文文档 ocr_dpi=300, # 扫描分辨率 output_format="markdown" )

实测下来，300 DPI 的清晰扫描件，中文 OCR 准确率能到 95% 以上；如果是 150 DPI 的模糊扫描，准确率可能掉到 80% 以下，这种就得先做图像增强再 OCR。

4. 实操过程与核心环节实现

4.1 环境准备与依赖安装

先把环境搭起来。pdf-inspector这类工具通常依赖几个底层库：PDF 解析库（如 pdfplumber 或 PyMuPDF）、图像处理库（Pillow、OpenCV）、OCR 引擎（Tesseract 或 PaddleOCR）。安装时最容易出问题的是 OCR 引擎的系统依赖，尤其是中文语言包。

# 以 Python 环境为例的安装示意 pip install pdf-inspector # OCR 引擎的系统依赖（以常见 OCR 为例） # 需要单独安装引擎本体和中文语言包

安装完先跑一个最小验证，确认能正常导入、能处理一个简单 PDF。别急着上大批量文档，先用一个两三页的小文件跑通全流程，确认输出格式符合预期，再扩展到全量。

注意：OCR 引擎的语言包要单独装，很多人装完引擎发现识别不了中文，就是漏了语言包。装完记得用命令行测一下引擎本身能不能识别中文图片，排除环境问题。

4.2 单文件转换的完整流程

单文件转换是最基础的用法，也是调试规则的主战场。完整流程分四步：加载 PDF、类型检测、分页处理、合并输出。

from pdf_inspector import convert result = convert( input_path="input.pdf", output_path="output.md", output_format="markdown", ocr_enabled=True, ocr_lang="ch", remove_header_footer=True, table_detection=True, reading_order="auto" ) print(f"处理页数: {result.pages}") print(f"OCR 页数: {result.ocr_pages}") print(f"表格数: {result.tables}")

跑完之后重点看三样东西：输出的 Markdown 结构对不对（标题层级、列表、表格）、有没有明显的乱码或断句、页眉页脚有没有清干净。这三样过关了，单文件流程就算通了。

4.3 批量处理的工程化改造

真实项目里很少只处理一个 PDF，通常是几百上千个。批量处理要考虑三件事：并发控制、失败重试、进度追踪。

并发不是越高越好。OCR 是 CPU 密集型任务，开太多进程反而会因为资源争抢变慢，还可能把内存吃爆。我的经验是并发数控制在 CPU 核心数的 1 到 1.5 倍比较稳。文本型 PDF 处理快，可以适当提高并发；扫描型 PDF 处理慢，并发要压低。

失败重试要区分错误类型。文件损坏这种重试也没用，直接记录跳过；OCR 超时这种可以重试，但要设最大重试次数，避免死循环。

# 伪代码示意：批量处理框架 import os from concurrent.futures import ProcessPoolExecutor from pdf_inspector import convert def process_one(pdf_path): try: result = convert(pdf_path, output_format="markdown", ocr_enabled=True) return {"file": pdf_path, "status": "ok", "pages": result.pages} except Exception as e: return {"file": pdf_path, "status": "failed", "error": str(e)} pdf_files = [f for f in os.listdir("pdfs") if f.endswith(".pdf")] with ProcessPoolExecutor(max_workers=4) as executor: results = list(executor.map(process_one, pdf_files)) ok = [r for r in results if r["status"] == "ok"] failed = [r for r in results if r["status"] == "failed"] print(f"成功: {len(ok)}, 失败: {len(failed)}")

批量跑的时候一定要有日志，记录每个文件的处理状态、耗时、页数。出了问题能快速定位是哪个文件、哪一步出的错。

4.4 输出 Markdown 的质量校验

转换完不是就完事了，得做质量校验。我一般从三个维度抽查：结构完整性、内容准确性、噪声残留。

结构完整性看标题层级有没有断档、列表有没有丢、表格有没有还原。内容准确性随机抽几段和原 PDF 对照，看有没有漏字、错字、串行。噪声残留重点看页眉页脚、水印、页码有没有清干净。

可以写个简单的校验脚本，统计一些指标：标题数量、表格数量、平均段落长度、疑似页眉页脚的重复文本。指标异常的文件挑出来人工复核。

4.5 与 RAG 切分环节的衔接

解析出来的 Markdown 最终要喂给切分器。这里有个衔接技巧：按 Markdown 结构切分，而不是按固定长度切分。标题是天然的语义边界，遇到标题就开新 chunk，能让每个 chunk 尽量是一个完整知识点。

具体做法是先用 Markdown 解析器把文档拆成标题树，然后按标题层级切分。一级标题下的内容作为一个大块，如果太大再按二级标题细分，以此类推。表格和代码块要作为整体保留，不能从中间切断。

# 伪代码示意：按 Markdown 标题切分 from markdown_parser import parse_headings def split_by_headings(md_text, max_chunk_size=1000): sections = parse_headings(md_text) chunks = [] for section in sections: if len(section.content) <= max_chunk_size: chunks.append(section) else: # 超长段落再按段落切 chunks.extend(split_by_paragraph(section, max_chunk_size)) return chunks

切分粒度也要调。太粗检索不精准，太细丢失上下文。我的经验是每个 chunk 控制在 500 到 1000 字之间，具体看文档类型。技术文档可以细一点，叙述性文档可以粗一点。

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

5.1 解析出来是空白或乱码

这是最常见的问题，原因通常有三类。第一类是扫描件没开 OCR，文本层是空的，自然抽不出东西。第二类是字体编码问题，PDF 用了非标准编码，抽出来的字符是乱码。第三类是加密 PDF，有权限限制，解析库读不了。

排查顺序：先确认是不是扫描件（看能不能提取出任何文本），是的话开 OCR；不是的话检查字体编码，可以换个解析库试试；还不行就看是不是加密的，加密的得先解密。

提示：乱码问题有时候换个解析后端就好了，因为不同库对字体编码的处理策略不一样。遇到乱码别死磕一个库，换一个试试往往有惊喜。

5.2 表格还原成一坨

表格还原失败通常是因为表格没有框线，或者框线太细被忽略了。解决办法有两个：一是调低线条检测的阈值，让细线也能被识别；二是对无框线表格改用坐标聚类，靠列对齐来推断结构。

如果两种方法都不行，可以考虑对表格区域单独截图走 OCR，用 OCR 的表格识别能力来还原。这条路准确率更高，但慢，适合表格数量不多的文档。

5.3 阅读顺序错乱

双栏、多栏、图文混排都容易导致阅读顺序错乱。排查方法是把解析结果和原 PDF 对照，看段落是不是按人类阅读顺序排列的。

如果是分栏问题，检查栏检测有没有生效，栏间距阈值是不是设得太大或太小。如果是图文混排，检查图片有没有被正确识别为独立元素，图片周围的文字有没有被错误合并。

5.4 OCR 识别率低

OCR 识别率低的原因很多：分辨率不够、图像倾斜、文字模糊、语言不匹配、字体特殊。排查时先看原图质量，300 DPI 以上、不倾斜、清晰的图识别率最高。

如果原图质量没问题但识别率还是低，检查语言设置对不对，中文文档用了英文模型肯定不行。再不行就换 OCR 引擎，不同引擎对不同字体的识别能力有差异。

5.5 处理速度太慢

慢的原因通常是 OCR 拖后腿。优化方向有几个：一是只对扫描页开 OCR，文本页跳过；二是降低 OCR 分辨率（但要保证识别率）；三是提高并发，但要注意资源上限；四是对已经处理过的文件做缓存，避免重复处理。

我自己的项目里，把 OCR 分辨率从 300 DPI 降到 200 DPI，速度提升了近一倍，识别率只掉了两三个百分点，性价比很高。当然这要看具体文档，清晰度差的还是得用高分辨率。

5.6 页眉页脚没清干净

清洗规则没覆盖到，或者阈值设得不对。检查方法是统计每页顶部底部区域的文本，看哪些是高频重复的。如果某个文本在 80% 页面都出现但没被清掉，说明阈值设高了，调低一点。

有些页眉页脚是图片形式的，文本统计抓不到，这种得靠图像区域检测来识别。还有的页眉页脚位置不固定，每页高度略有差异，这种就得放宽检测区域。

6. 我踩过的坑和几条实在建议

先说一个最容易被忽略的点：别指望一次配置就能处理所有 PDF。真实项目里的 PDF 来源五花八门，排版风格千差万别，一套参数打天下是不现实的。我的做法是按来源分组，每组调一套参数，处理前先跑样本验证，验证通过再批量。

第二个坑是过度依赖自动识别。标题层级、表格结构这些，自动识别能搞定大部分，但总有一部分需要人工介入。与其追求 100% 自动化，不如设计一个"自动处理加人工抽检"的流程，把人工精力集中在异常文件上，整体效率反而更高。

第三个经验是保留中间产物。解析过程中的类型检测结果、OCR 中间图、版面分析结果，都建议存下来。出了问题能回溯，调参时能对比，比每次从头跑一遍省事得多。

最后分享一个实用技巧：处理前先做文档画像。统计一下文档的页数分布、类型分布、表格数量、语言构成，心里有个底。这样遇到问题时能快速判断是普遍问题还是个别文件的问题，排查方向更明确。

这套流程我在几个知识库项目里跑下来，解析质量比早期的纯文本方案提升明显，检索命中率也跟着上来了。PDF 解析这活儿没有一劳永逸的方案，但只要把类型检测、版面识别、OCR 兜底这几步做扎实，大部分文档都能处理得不错。