1. 为什么 RAG 的成败往往卡在 PDF 解析这一步做 RAG 的人大概都有过这种体验向量库搭好了embedding 模型选好了检索链路也跑通了结果一问问题模型答得驴唇不对马嘴。回头一查问题根本不在检索也不在生成而是最上游那一环——PDF 压根没被正确读出来。表格串行了双栏排版被读成单栏页眉页脚混进正文公式变成一堆乱码字符。你后面所有的精排、重排、混合检索全都建立在一堆垃圾文本上再精妙的架构也救不回来。pdf-inspector这个工具就是冲着这个痛点来的。它做的事情说起来很朴素把 PDF 里的内容尽可能还原成结构化的 Markdown让你在进入 chunk 切分和向量化之前手里拿到的是一份干净、有层级、可追溯的文本。关键词里那几个词其实已经把它的定位说清楚了——RAG、PDF、Markdown、OCR。它不是一个通用 PDF 阅读器也不是一个排版工具它是专门服务于 RAG 数据预处理这一环的解析器。这篇文章适合谁看如果你正在搭 RAG 知识库尤其是那种文档来源以 PDF 为主合同、论文、技术手册、财报、产品说明书的场景那这篇基本就是给你写的。如果你只是偶尔转个 PDF 看看那可能用不上这么重的东西。我会从 PDF 解析为什么难讲起然后拆解 pdf-inspector 的工作机制再给出一套可以直接抄的接入流程最后重点讲那些文档里不会写、但实际跑起来一定会遇到的坑。全文基于常见工程实践展开具体 API 以你实际拿到的版本为准。先说一个反直觉的结论在 RAG 项目里PDF 解析的投入产出比往往比换一个更强的 embedding 模型还要高。我见过太多团队花两周调检索参数效果提升 3 个点结果把解析器换掉召回率直接涨 20 个点。原因很简单检索的前提是库里有正确的东西库里全是错的检索再准也是错的。2. PDF 为什么这么难解析从文件结构说起2.1 PDF 本质是打印描述不是文档结构很多人以为 PDF 里存的是标题、段落、表格这些语义信息其实完全不是。PDF 的全称是 Portable Document Format它的设计目标是在任何设备上打印出来长得一样所以它存的是绘制指令在坐标 (x, y) 处画一个字符用某个字体某个字号某个颜色。至于这个字符属于标题还是正文属于第几段PDF 本身根本不关心。这就导致一个根本性问题解析 PDF 本质上是一个逆向工程过程。你得从一堆带坐标的字符碎片里反推出这是一行这是一个段落这是一个两栏布局这是一个表格。没有哪个解析器能做到 100% 准确区别只在于谁猜得更合理。2.2 三种 PDF三种难度实际工作中遇到的 PDF难度差异极大我一般分成三类类型特征解析难度典型来源原生文本型文字可选可复制有内嵌字体低Word 导出、LaTeX 编译扫描图像型整页是图片文字不可选高必须 OCR纸质扫描、传真件混合型部分页文本、部分页扫描或文本层叠加在图像上最高拼接文档、老档案原生文本型看着简单但坑也不少。比如双栏论文如果解析器按 y 坐标从上往下读会把左栏第一行和右栏第一行拼在一起读出来就是本文提出了一种方法 实验结果如表 1 所示这种精神分裂的句子。再比如表格PDF 里表格根本没有单元格概念就是一堆绝对定位的文字你得靠对齐关系去猜行列。扫描图像型就更直接了必须走 OCR。但 OCR 本身也有精度问题尤其是中文、公式、特殊符号。关键词里出现了以下 ocr 代码识别不了韩文php ocr 识别验证码java 使用百度 ocr 识别上传合同文件这些说明 OCR 在实际业务里是个高频刚需而且坑特别多。pdf-inspector 这类工具的价值就在于它把判断该用文本层还是该走 OCR这件事自动化了。2.3 为什么输出 Markdown 而不是纯文本这里要专门解释一下为什么这类工具普遍选择 Markdown 作为输出格式而不是直接吐纯文本。纯文本丢掉了结构。一个标题和一段正文在纯文本里长得一模一样chunk 切分的时候你没法按语义边界切只能按固定字数硬切结果就是一句话被拦腰截断检索时两边都召不回。Markdown 用#、##、-、|这些符号把层级、列表、表格保留了下来你在切 chunk 的时候就可以按标题层级切一个二级标题下的内容作为一个语义块召回质量完全不一样。而且 Markdown 是纯文本天然适合塞进 prompt。你把解析结果直接喂给大模型模型能看懂## 标题是什么意思能看懂表格。关键词里markdown 表格转换 excelmarkdown 数学公式插件github markdown callout这些热搜也侧面说明 Markdown 已经成了 LLM 时代事实上的中间格式。3. pdf-inspector 到底在做什么核心能力拆解3.1 它解决的不是转换而是还原市面上 PDF 转 Markdown 的工具一抓一大把但大多数是能转就行转出来能看但没法用于 RAG。pdf-inspector 的定位更偏工程化它关注的是还原质量和可追溯性。所谓还原质量是指它要尽量判断出哪些文字是标题哪些是正文哪些是页眉页脚这些要丢掉哪些是表格哪些是代码块。所谓可追溯性是指解析出来的每一段内容最好能对应回原 PDF 的页码甚至坐标这样用户问问题时你能告诉他这个答案来自第 12 页而不是干巴巴一段文字。3.2 文本层优先OCR 兜底一个成熟的 PDF 解析流程一定是先判断有没有文本层有就用文本层没有才走 OCR。原因很实在文本层是 PDF 自带的100% 准确零成本OCR 是识别出来的有错误率还慢还费算力。pdf-inspector 这类工具通常会在页级别做判断这一页提取出来的文字数量低于某个阈值比如少于 50 个字符就认为它是扫描页转去走 OCR 通道。这个阈值不能设死因为有些页确实只有一张图加一行图注字符少但不需要 OCR。实际调的时候我一般会结合文字密度和图像覆盖率两个指标一起判断。3.3 版面分析把坐标翻译成结构这是最核心也最难的部分。解析器拿到一页的所有字符及其坐标后要做几件事行合并把 y 坐标接近、x 坐标连续的字符合并成一行。段落合并把行间距正常、缩进一致的行合并成一段。栏检测通过 x 坐标的分布判断这页是单栏还是多栏。表格识别通过字符的对齐规律识别出表格的行列结构。页眉页脚剔除出现在页面顶部/底部固定位置、且在多个页面重复出现的文本判定为页眉页脚。每一步都是启发式规则加统计判断没有银弹。这也是为什么不同工具解析同一份 PDF结果可能天差地别。3.4 输出结构标题层级怎么来的Markdown 的标题层级#、##、###不是 PDF 里带的是解析器推断出来的。常见推断依据有几个字号明显大于正文、加粗、独立成行、上下有较大留白、编号模式如第一章1.1。把这些信号加权打分分数高的判为标题再根据字号大小排序决定是几级标题。这里有个经验不要完全信任自动推断的层级。我一般会在解析后加一步人工抽检尤其是文档结构复杂的场景。因为一旦层级错了后面按标题切 chunk 就会全乱。4. 把 pdf-inspector 接进 RAG 流水线的完整流程4.1 整体链路长什么样先给一张我常用的链路图文字描述PDF 文件 → pdf-inspector 解析 → Markdown带页码元数据 → 清洗去页眉页脚残留、修表格 → 按标题层级切 chunk → 附加元数据来源、页码、标题路径 → embedding → 向量库 → 检索 重排 → 喂给 LLM关键点在于解析和切分是两件事不要混在一起做。有些工具边解析边切结果切出来的块没法调整。正确做法是先拿到完整的 Markdown再单独做切分这样切分策略可以随时改不用重新解析。4.2 环境准备与依赖具体安装方式以你拿到的版本为准但通用思路是Python 环境建议 3.10装好解析库本身如果涉及 OCR 还要装对应的 OCR 引擎和语言包。中文场景一定要确认语言包装全了否则会出现识别不了韩文这类问题——本质是语言模型没加载对应语种。提示OCR 语言包不是装得越多越好。加载的语言越多内存占用越大识别速度越慢而且容易把形近字认错。按你的实际文档语种来装。4.3 解析阶段的关键参数解析时我一般会关注这几个可调项是否启用 OCR纯文本型文档可以关掉省时间。OCR 触发阈值每页最少字符数低于则走 OCR。是否保留页眉页脚RAG 场景一律不保留。表格输出格式Markdown 表格还是 HTML 表格。表格复杂时 HTML 更保真但 Markdown 更省 token。图片处理图片是丢弃、保留占位符还是走图注 OCR。这里重点说图片。关键词里有个热搜叫rag 知识库能存储图片嘛这问题问得很实在。答案是能但不是直接存图片而是存图片的描述或图注。纯图片没法做文本检索你得用多模态模型给图片生成一段文字描述或者提取图注文字把这段文字存进向量库图片本身存对象存储检索命中后把图片一起返回。pdf-inspector 在解析时如果能保留图片位置和图注对后续做多模态 RAG 帮助很大。4.4 切分策略按标题切不按字数切拿到 Markdown 后切 chunk 我强烈建议按标题层级切而不是按固定字数切。具体做法以二级标题##为一级切分点每个二级标题下的内容作为一个大块。如果某个大块超过 token 上限比如 800 token再按三级标题或段落细分。每个 chunk 头部带上标题路径比如第三章 3.2 节 具体小节这样检索时上下文更完整。chunk 之间保留一定重叠overlap一般 10%~15%防止边界信息丢失。按字数硬切的坏处前面说过了会把语义单元切碎。按标题切的好处是每个 chunk 语义自洽检索时命中率高喂给 LLM 时也不会出现半句话。4.5 元数据设计别忘了页码这一步很多人偷懒不做后面一定后悔。每个 chunk 至少要带这几个元数据字段说明用途source源文件名区分不同文档page起始页码答案溯源heading_path标题路径提供上下文chunk_id唯一标识去重、更新有了 page 字段用户问这个结论哪来的你能直接答来自《XX 报告》第 23 页。这个体验差距是巨大的也是 RAG 产品能不能被信任的关键。5. 实测中一定会踩的坑与排查思路5.1 表格解析错位最常见的翻车现场表格是 PDF 解析的重灾区。我遇到过最离谱的一次一份财务报表解析出来数字全串行了营收和成本对调如果直接喂给模型生成的财务分析完全是错的。排查思路是这样的先看原始 PDF 里表格是真表格还是用空格对齐的假表格。真表格有边框线相对好识别假表格纯靠空格对齐极难因为解析器分不清这是表格的一列还是这是一段文字里的空格。处理办法对关键表格解析后做一次校验比如检查每行的列数是否一致不一致的标记出来人工核对。或者对表格区域单独走一次结构化提取不要依赖通用解析。5.2 双栏论文读串行学术论文基本都是双栏这是解析器的经典难题。表现是左栏和右栏的文字被交替拼接读起来完全不通顺。判断方法很简单解析出来的文本如果读起来逻辑跳跃、句子接不上八成是栏检测失败。解决办法是找支持栏检测的解析模式或者在解析前先做版面分析把页面按栏切开再分别解析。有些工具提供阅读顺序参数可以手动指定。5.3 页眉页脚污染页眉页脚如果没剔除干净会污染每一个 chunk。想象一下每个 chunk 开头都是XX 公司内部资料 第 X 页 机密检索时这些词会干扰相似度计算。剔除逻辑一般是统计每页顶部/底部固定区域出现的文本如果同一段文字在超过 50% 的页面出现判定为页眉页脚。但有些文档页眉是章节名每页不同这种就剔不掉得靠位置规则比如页面顶部 5% 区域内的文字一律丢弃。5.4 OCR 识别错误中文和公式是重灾区OCR 对中文的识别尤其是生僻字、繁体字、竖排文字错误率明显高于英文。公式更是灾难∑、∫、上下标基本认不对。应对策略对公式密集的文档比如数学教材、物理论文不要指望 OCR要么找带公式识别的专用工具要么干脆把公式区域截图用多模态模型转成 LaTeX。关键词里自然语言处理课本 pdfcst 仿真设计理论与实践 pdf这类大概率公式很多解析时要特别小心。5.5 解析慢大文档的时间成本一份 500 页的扫描 PDF走 OCR 可能要几十分钟甚至更久。如果文档量大解析会成为整个流水线的瓶颈。优化思路解析任务异步化不要阻塞主流程已经解析过的文档做缓存用文件哈希做 key避免重复解析OCR 部分可以并行多进程或多线程跑。关键词里rag 瓶颈这个词很说明问题很多人的 RAG 瓶颈根本不在检索而在数据预处理。6. 让解析结果真正服务于检索的几个进阶技巧6.1 给 chunk 加上下文前缀单纯一段文字检索时容易歧义。比如 chunk 内容是该指标同比增长 15%脱离上下文根本不知道说的是什么指标。解决办法是在 chunk 前面加上下文前缀比如《2024 年财报》第三章 营收分析该指标同比增长 15%。这个前缀在 embedding 时一起编码检索命中率会明显提升。这个技巧本质上是把标题路径用自然语言表达出来让向量模型能理解 chunk 的语境。6.2 表格单独建索引表格内容和正文的检索需求不一样。正文是语义检索表格往往是精确查询2023 年 Q3 营收是多少。所以我会把表格单独抽出来转成结构化的键值对或 JSON存一份到支持结构化查询的地方检索时正文走向量、表格走精确匹配两条路并行。6.3 保留原文位置支持高亮回溯如果解析时保留了每个 chunk 对应的原文坐标前端就能做到点击答案跳转到 PDF 对应位置并高亮。这个功能对专业用户律师、研究员、财务价值极高是他们愿不愿意用你产品的分水岭。pdf-inspector 这类工具如果输出里带坐标信息一定要留着别嫌麻烦。6.4 定期回归测试解析质量解析器不是配好就一劳永逸的。文档来源会变PDF 生成工具会变解析效果也会波动。我建议建一个小型的回归测试集挑 20 份有代表性的文档人工标注关键内容每次解析器升级或参数调整后跑一遍看召回率有没有下降。这个投入不大但能避免悄悄变差这种最难查的问题。7. 关于工具选型的一点个人看法市面上 PDF 解析方案大致分三档纯开源库灵活但效果参差、云服务 API效果好但按量收费、有数据合规顾虑、专用工具介于两者之间。pdf-inspector 属于第三类它的价值在于把 RAG 场景的常见需求做了针对性优化省去你自己拼装各种库的功夫。选型时我的判断标准就三条解析质量能不能满足你的文档类型、能不能保留页码等元数据、出问题能不能定位和调整。第一条决定能不能用第二条决定好不好用第三条决定敢不敢用在生产环境。最后分享一个我踩过的坑早期我图省事用了一个一键转 Markdown的工具转出来看着挺漂亮结果上线后发现表格全错、页码全丢用户问哪来的我答不上来只能推倒重来。从那以后我的原则是解析环节宁可慢一点、麻烦一点也要保证结构完整和可追溯。因为这是整条 RAG 链路的地基地基歪了上面盖得再高都是危房。如果你现在正在做 RAG文档又是 PDF 为主我建议你花半天时间拿几份最有代表性的文档把 pdf-inspector 这类工具跑一遍重点看表格、双栏、页眉页脚这三块的处理效果。这三块过了后面的路会顺很多。