1. 为什么 RAG 项目总在 PDF 解析这一步翻车做过 RAG 的人大概都有过这种体验向量库搭好了检索链路跑通了大模型也接上了Demo 演示时效果惊艳结果一上真实文档就原形毕露。问它合同里的违约金比例它给你编一个问它财报里的营收数字它把表格里的两列数据串成一行读出来。排查半天发现问题根本不在检索环节也不在生成环节而是最前面那一步——PDF 压根就没被正确地读成文本。PDF 这个格式从诞生之初就不是为了“被机器理解”而设计的。它的核心目标是“在任何设备上看起来都一样”所以它更像是一张张精确排版的画布文字、线条、图片被放在固定的坐标上至于这些内容之间的语义关系PDF 本身并不关心。这就导致了一个很尴尬的局面人眼看着排版清晰的文档程序读出来却是一团乱麻。标题和正文混在一起表格的单元格顺序全乱页眉页脚被当成正文塞进 chunk双栏排版的论文被按行交错拼接读起来像精神分裂。pdf-inspector这个工具就是冲着这个痛点来的。它不是又一个“PDF 转文本”的轮子而是一个专门为 RAG 场景设计的 PDF 结构解析与质量检查工具。你可以把它理解成 PDF 解析流水线上的质检员加调度员一方面它能帮你把 PDF 里的内容按照语义结构抽出来输出成对 RAG 友好的 Markdown另一方面它能告诉你这份 PDF 到底“好不好啃”哪些页面是扫描件需要走 OCR哪些页面是原生文本可以直接抽表格和图片分别分布在哪些位置。这篇文章适合两类人看。一类是正在做 RAG 知识库、被 PDF 解析折磨得死去活来的工程师另一类是想搞清楚 PDF 解析到底难在哪、该怎么选型的技术负责人。我会从整体设计思路讲到具体实操把踩过的坑和验证过的参数都摊开来说尽量让你看完就能上手而不是又看了一篇“原理介绍”。2. 整体设计思路为什么不能直接上 OCR 一把梭2.1 PDF 的两副面孔原生文本层与扫描图像层很多人对 PDF 有个误解觉得 PDF 就是图片所以直接上 OCR 就完事了。这个思路在部分场景下没错但用在 RAG 上会吃大亏。PDF 实际上分两种一种是“数字原生 PDF”由 Word、LaTeX、排版软件导出里面每一行文字都有真实的字符编码和坐标信息另一种是“扫描 PDF”本质是一堆图片文字信息完全不存在只能靠 OCR 识别。这两者的处理成本和准确率天差地别。原生 PDF 抽文本几乎是零成本、接近百分之百准确扫描 PDF 走 OCR 不仅慢还会引入识别错误尤其是中文、公式、特殊符号错一个字符可能就让检索命中率掉一大截。所以一个成熟的解析流程第一步永远是判断“这一页有没有文本层”而不是无脑 OCR。pdf-inspector在这件事上的价值就体现出来了。它会在解析前先做一次“体检”逐页统计可提取字符数、图片覆盖率、字体信息等指标给出一个页面类型的判断。你可以据此决定哪些页走快速文本抽取哪些页走 OCR哪些页干脆标记为“低质量、建议人工复核”。这个分流动作看起来简单但它能帮你省下大量的算力和调试时间。2.2 为什么输出格式选 Markdown 而不是纯文本纯文本抽取是最省事的但也是最坑 RAG 的。原因在于纯文本丢掉了所有结构信息标题和正文没有层级区分表格变成一堆用空格对齐的数字列表项的层级关系消失。当你的切分器splitter按固定长度切 chunk 时它根本不知道自己在切的是标题还是正文结果就是检索出来的片段语义不完整。Markdown 的好处是它用极轻量的语法保留了结构#表示标题层级|表示表格-表示列表表示引用。这些符号对 RAG 的切分器来说是极其宝贵的信号。你可以按标题层级切分保证每个 chunk 都在一个语义单元内你也可以识别表格块单独做结构化处理而不是硬切。pdf-inspector把输出对齐到 Markdown本质上是在为下游的切分和检索铺路。这里有个实操细节值得说Markdown 的表格语法对 RAG 特别友好因为它是“行列对齐”的。一个财务表格转成 Markdown 后每一行是一条记录表头在顶部检索时模型能清楚知道“这一列是营收、那一列是成本”。而如果转成纯文本表格往往变成“营收 成本 利润 100 80 20”这样一串数字模型只能靠猜。2.3 解析、检查、分流三位一体的设计把pdf-inspector单纯当成一个转换器是低估它了。它的设计思路其实是三位一体的解析负责把内容抽出来检查负责评估质量分流负责决定后续处理路径。这三件事在真实项目里是强耦合的。举个实际场景你收到一批 500 份 PDF 合同不可能每份都人工看一遍。你需要先跑一遍检查看看有多少是扫描件、多少是原生件、多少是混合的。然后对原生件直接抽文本对扫描件排队走 OCR对混合件按页分流。这个过程如果没有工具支撑纯靠脚本拼凑维护成本会非常高。pdf-inspector把这条链路收敛到一个工具里你只需要配置好阈值和输出格式剩下的它帮你判断。提示不要一上来就追求“全自动完美解析”。真实项目里先跑一遍检查、拿到质量报告、再决定处理策略比盲目全量 OCR 要高效得多也更省钱。3. 核心细节解析PDF 解析里那些要命的坑3.1 阅读顺序双栏论文为什么读起来像乱码学术论文、杂志、产品手册大量使用多栏排版。PDF 里这些栏的文字是按坐标存放的如果你简单地按“从上到下、从左到右”抽取就会把左栏第一行、右栏第一行、左栏第二行、右栏第二行这样交错拼起来读出来完全不通顺。正确的做法是基于文本块的坐标做“分栏聚类”先识别出页面有几栏再按栏的顺序逐栏抽取。pdf-inspector在处理这类文档时会先分析文本块的横向分布找到栏与栏之间的空白间隙把文本块归到不同的栏里再按栏内顺序输出。这个逻辑听起来简单但阈值调不好就会出错间隙设太小单栏文档被误判成多栏设太大多栏文档又识别不出来。我的经验是对于 A4 幅面的文档栏间距通常在 20 到 40 像素之间按 72dpi 计算。你可以先用默认阈值跑一遍看看输出的阅读顺序对不对再针对性调整。如果文档来源比较杂建议按来源分组处理而不是用一套参数打天下。3.2 表格还原RAG 里最容易丢分的地方表格是 RAG 的重灾区。原因很简单表格的信息密度极高一个单元格错了整条记录的语义就变了。而 PDF 里的表格往往没有真正的“表格结构”只有一堆线条和文字块。解析器需要根据线条位置、文字对齐方式反推出行列关系。这里有个关键判断表格是“有线表”还是“无线表”。有线表有明确的边框线解析相对容易靠线条交点就能定位单元格。无线表只有文字对齐需要靠列与列之间的空白间隙来推断难度大很多。pdf-inspector会尝试识别这两种情况并在输出 Markdown 表格时尽量保持行列对应。实操中我踩过的一个坑是合并单元格。PDF 里的合并单元格在视觉上是一个大格子但解析出来往往变成“第一行有值、下面几行空着”或者值被重复填充。对于 RAG 来说前者会导致信息丢失后者会导致信息冗余。处理这类表格我的建议是如果表格结构复杂有大量合并单元格不要指望自动解析完美而是把表格区域单独截出来用多模态模型或人工方式补充描述再作为独立 chunk 入库。表格类型识别难度推荐处理方式RAG 友好度有线规则表低直接解析为 Markdown高无线对齐表中解析后人工抽检中含合并单元格高截图加描述中低跨页表格高按页解析后拼接中3.3 页眉页脚与页码噪声是怎么污染检索的页眉页脚是 RAG 里最隐蔽的噪声源。它们出现在每一页的固定位置内容往往是公司名、文档标题、页码、保密声明。如果你不做过滤这些内容会被重复切进每一个 chunk导致检索时大量无关片段被召回稀释了真正有用的信息。pdf-inspector的检查环节会统计每页顶部和底部区域的文本重复率。如果某段文字在超过 80% 的页面同一位置出现基本可以判定为页眉页脚自动剔除。这个逻辑比硬编码坐标范围要靠谱因为不同文档的页边距不一样。但要注意一个例外有些文档的页眉里包含章节标题这个信息其实是有用的。我的做法是把页眉页脚单独抽出来存到一个元数据字段里而不是直接丢弃。这样既不影响正文检索又保留了文档的结构信息需要时可以回溯。3.4 图片与公式RAG 知识库到底能不能存图片热词里有个问题问得很实在“RAG 知识库能存储图片嘛”。答案是能但要看你怎么存。直接把图片二进制塞进向量库没有意义因为向量库检索的是文本语义。正确的做法是给图片生成文本描述把描述文本向量化图片本身存到对象存储通过 ID 关联。对于 PDF 里的图片pdf-inspector会提取图片的位置和尺寸信息你可以据此判断哪些图片是“有信息量的”比如流程图、架构图、数据图表哪些是“装饰性的”比如 logo、分隔线。有信息量的图片建议走多模态模型生成描述装饰性的直接跳过。公式是另一个难点。PDF 里的公式如果是用 LaTeX 排版的可能保留了一些结构信息如果是图片形式的就只能靠 OCR 或专门的公式识别模型。对于技术类文档公式往往承载核心信息建议单独处理转成 LaTeX 或 MathML 后作为独立 chunk 入库并在描述里说明公式的上下文。4. 实操过程从零跑通一条 PDF 解析流水线4.1 环境准备与依赖安装先把基础环境搭起来。pdf-inspector通常依赖几个底层库处理 PDF 结构的、做 OCR 的、做图像分析的。我建议用虚拟环境隔离避免版本冲突。python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install pdf-inspector如果你需要 OCR 能力还要额外装 OCR 引擎。中文场景我推荐 PaddleOCR识别率和速度都比较均衡英文场景 Tesseract 够用。注意 OCR 引擎的版本要和你的系统架构匹配尤其是 ARM 机器上有些预编译包不一定能用。pip install paddleocr paddlepaddle装完之后先跑一个最小验证确认工具能正常导入、能读到一个 PDF 文件。这一步别省很多问题在环境阶段就暴露出来比在流水线里排查要容易得多。4.2 第一步先做体检别急着解析拿到一批 PDF第一件事不是解析而是体检。跑一遍检查看看每份文档的页面类型分布。from pdf_inspector import Inspector inspector Inspector() report inspector.inspect(contract_sample.pdf) print(report.summary()) print(report.page_types()) # 每页是 text / scanned / mixed print(report.quality_score()) # 0-100 的质量分体检报告里我重点看三个指标文本覆盖率、图片覆盖率、字体嵌入情况。文本覆盖率低于 10% 的基本是扫描件直接走 OCR覆盖率在 10% 到 60% 之间的往往是混合件需要按页分流高于 60% 的原生件直接抽文本。字体嵌入情况能反映文档是否被特殊处理过有些加密或子集化的字体会导致抽取乱码这种要提前标记。注意体检阶段不要跳过任何一份文档。我见过太多项目因为“觉得这批文档都是原生件”而跳过检查结果混进去几份扫描件导致检索时那部分内容完全查不到排查了半天才发现。4.3 第二步按页面类型分流处理体检完就进入分流环节。原生文本页走快速抽取扫描页走 OCR混合页按区域判断。这里的关键是“按页”而不是“按文档”分流因为很多 PDF 是图文混排的整份文档走同一条路径会浪费算力或损失质量。from pdf_inspector import Parser, OCRRouter router OCRRouter(text_threshold0.1) parser Parser(routerrouter) result parser.parse(contract_sample.pdf, output_formatmarkdown) with open(contract_sample.md, w, encodingutf-8) as f: f.write(result.markdown)text_threshold这个参数控制“一页里文本占比低于多少就判定为扫描页”。默认 0.1 是个比较稳的值但如果你处理的文档普遍是图文混排的可以适当调高到 0.2让更多页面走 OCR 以保证完整性。反过来如果文档很干净调到 0.05 能省不少 OCR 开销。4.4 第三步输出 Markdown 并做后处理解析出来的 Markdown 不能直接入库还要做几件后处理的事。第一是清理多余空行和断行PDF 抽取经常把一句话拆成好几行需要合并。第二是修复表格检查行列数是否一致不一致的标记出来人工复核。第三是补充元数据把页码、章节标题、来源文件名写进 chunk 的 metadata 里。import re def clean_markdown(md: str) - str: # 合并被硬换行拆断的句子 md re.sub(r(?![。.!?])\n(?![\n#|\-]), , md) # 压缩连续空行 md re.sub(r\n{3,}, \n\n, md) return md.strip() cleaned clean_markdown(result.markdown)这个合并逻辑要小心别把列表项和表格行也合并了。所以正则里排除了以#、|、-开头的行。实际用的时候建议先在小样本上验证确认不会误伤再批量跑。4.5 第四步切分与入库的衔接解析完的 Markdown 怎么切分直接决定了检索质量。我的建议是按标题层级切一级标题作为大 chunk 的边界二级标题作为子 chunk 的边界如果某个子 chunk 还是太长再按段落切。这样能保证每个 chunk 都在一个完整的语义单元内。from langchain.text_splitter import MarkdownHeaderTextSplitter headers_to_split_on [ (#, h1), (##, h2), (###, h3), ] splitter MarkdownHeaderTextSplitter(headers_to_split_onheaders_to_split_on) chunks splitter.split_text(cleaned)每个 chunk 的 metadata 里会带上它所属的标题路径检索时你可以根据这个路径做过滤或加权。比如用户问的是“第三章的付款条款”你可以优先召回 h1 为“第三章”的 chunk。这个技巧在长文档场景下特别管用能显著提升命中率。5. 常见问题与排查技巧实录5.1 中文乱码与字体缺失中文 PDF 抽取乱码是最常见的问题之一根源通常是字体没有正确嵌入或使用了子集化字体。表现是抽出来的文字变成方框、问号或者完全无关的字符。排查方法是先看体检报告里的字体嵌入信息如果显示“未嵌入”或“子集化”基本可以确定是字体问题。解决办法有两个一是走 OCR 兜底把这一页当扫描页处理二是用字体映射表做修复但这个需要知道原始字体是什么成本较高。我的经验是对于中文文档如果原生抽取乱码率超过 5%直接整份走 OCR 反而更省心因为 OCR 对中文的识别已经相当成熟了。5.2 OCR 识别率上不去的几个原因OCR 识别率低先别怪引擎八成是图像质量的问题。常见原因有扫描分辨率太低低于 200dpi、图像倾斜、对比度不足、有噪点或水印干扰。处理前先做图像预处理灰度化、二值化、去噪、纠偏这几步能把识别率拉高十几个百分点。另一个容易被忽略的点是语言设置。PaddleOCR 默认是中英文混合如果你处理的是纯韩文或纯日文文档要显式指定语言否则识别率会惨不忍睹。热词里有人提到“以下 OCR 代码识别不了韩文”大概率就是没设语言参数。from paddleocr import PaddleOCR ocr PaddleOCR(use_angle_clsTrue, langkorean) # 韩文要显式指定 result ocr.ocr(korean_doc.png, clsTrue)5.3 表格跨页断裂怎么处理跨页表格是解析里的一大难题。一个表格从第 3 页底部延伸到第 4 页顶部解析出来会变成两个独立的表格而且第二个表格往往没有表头。处理思路是先识别出“疑似跨页表格”然后根据列数、列宽、内容连续性判断是否要拼接拼接时把第一页的表头复制到第二页。判断是否跨页可以看前一页最后一个表格和后一页第一个表格的列数是否一致、列宽是否接近。如果一致大概率是同一个表格。拼接时要注意去掉重复的表头行避免数据冗余。常见问题典型表现排查方向解决手段中文乱码方框、问号字体嵌入情况OCR 兜底或字体映射OCR 识别率低错字多、漏字图像质量、语言设置预处理加指定语言表格错位行列不对应有线/无线、合并单元格单独处理或人工复核阅读顺序乱双栏交错分栏聚类阈值调整栏间距参数页眉页脚污染重复内容入 chunk重复率统计自动剔除加元数据保留5.4 解析速度太慢怎么优化全量 OCR 是性能杀手。一份 100 页的扫描 PDF单线程 OCR 可能要跑好几分钟。优化方向有三个一是分流能走文本抽取的绝不走 OCR二是并行把页面分片后多进程处理三是缓存同一份文档解析过一次就存结果别重复跑。并行处理时要注意 OCR 引擎的线程安全问题有些引擎不支持多线程调用需要用进程池而不是线程池。另外GPU 加速能显著提升 OCR 速度如果条件允许尽量用 GPU 跑。from concurrent.futures import ProcessPoolExecutor def parse_page(page_num): return parser.parse_page(doc.pdf, page_num) with ProcessPoolExecutor(max_workers4) as executor: results list(executor.map(parse_page, range(total_pages)))5.5 几个我踩过的坑和对应技巧第一个坑是“以为所有 PDF 都一样”。我早期做项目时用一套参数处理所有文档结果学术论文的阅读顺序全乱合同文档的表格全错位。后来改成按文档来源分组每组单独调参效果立刻好转。PDF 解析没有万能参数只有针对性的配置。第二个坑是“忽略元数据”。一开始我只存正文文本后来发现检索时无法区分内容来自哪份文档、哪一页、哪个章节排查问题特别困难。现在我会把文件名、页码、标题路径、解析时间都写进 metadata检索时可以按这些字段过滤调试效率高很多。第三个坑是“过度追求自动化”。有些复杂表格和公式自动解析确实做不到完美。与其花大量时间调参不如接受“80% 自动加 20% 人工”的模式把自动解析搞不定的部分标记出来人工补充描述。这样整体效率反而更高质量也更可控。提示解析质量报告要留档。每次批量解析后把质量分、异常页面列表存下来后续检索效果不好时可以快速定位是不是解析环节的问题而不是盲目怀疑检索或模型。6. 把解析质量纳入 RAG 的持续监控RAG 项目上线不是终点而是起点。用户的问题千奇百怪检索效果会随着文档更新而波动。我的做法是把 PDF 解析质量纳入持续监控每次文档更新后跑一遍体检记录质量分变化定期抽样检查检索结果看是否有因为解析错误导致的答非所问把解析失败的页面单独建一个队列定期人工复核。这套机制跑下来最大的收获是“问题可定位”。以前检索效果不好只能猜是切分问题、embedding 问题还是模型问题现在有了解析质量数据能快速排除或确认解析环节的嫌疑。对于做 RAG 的人来说这种可观测性比任何单点优化都重要。pdf-inspector这类工具的价值不在于它能把 PDF 转得多完美而在于它把 PDF 解析从“黑盒”变成了“白盒”。你知道每一页是什么类型、质量如何、哪里可能出问题就能有针对性地处理而不是把一堆脏数据丢进向量库然后祈祷模型能理解。RAG 的上限很大程度上取决于数据质量的下限把解析这一步做扎实后面的检索和生成才有意义。