1. 为什么Agent落地先得啃下“文档解析”这块硬骨头做Agent开发这段时间我最大的感受是很多人把精力全花在提示词工程、模型选型、工具调用这些“上层建筑”上结果一上真实业务场景就翻车。翻车点往往出奇一致——模型根本读不懂输入材料。你让它总结一份PDF合同它把表格数据读丢了你让它分析一份扫描版报告它输出一堆幻觉你让它处理几十页PPT转出来的文件上下文窗口直接被塞爆。说白了文档解析是把非结构化数据变成结构化、可检索、可计算内容的关键环节。Agent能不能在真实业务里干活七成取决于这一层。文档解析做不好后面接再强的模型、再精巧的RAG链路都是空中楼阁。写这篇内容是想把我在Agent项目中反复折腾文档解析攒下的经验梳理一遍。适用对象是正在做Agent应用开发、RAG知识库搭建或者被PDF、扫描件、表格、复杂版式折磨过的人。我会从技术选型、管线设计、代码实现、踩坑记录几个角度展开尽量把那些文档里不写、但实际项目中一定会遇到的东西讲清楚。先说一个误区。有人觉得文档解析不就是“把PDF转成文本”吗这个理解局限在“提取字符”层面。实际上现代Agent需要的文档解析是三层能力的叠加先识别内容区域标题、段落、表格、图片、页眉页脚再按结构抽取信息表格结构、列表层级、段落关系最后转成模型友好的格式Markdown、JSON、向量化分块。每一步都有独立的坑每一层都会直接影响下游效果。2. 文档解析的技术地图先搞清你的文档是哪一类2.1 文本型PDF看着简单细节全在“元信息”里文本型PDF是指在PDF生成时就带有真实文本层比如Word导出的、网页打印生成的可以直接通过库提取文字。这类文档解析的难点不在于“能不能提取”而在于“提取后的结构是否保真”。拿一份典型的论文PDF举例。表面上你要的是标题、作者、摘要、正文这些元素。但PDF里的文本存储方式非常原始它记录的是“这个字符串放在页面哪个坐标”而不是“这是一个标题”或“这是一个段落”。排版软件生成时标题、正文、页眉可能混在同一文本流里甚至一个段落会被拆成几十个文本片段。我最初用最简单的提取方式做过测试直接抽文本结果V字型缩进的标题夹杂在段落中间目录页码混进正文多栏论文的阅读顺序完全错乱。所以处理文本型PDF核心是两件事解析坐标信息重建阅读顺序和用规则或模型判断文本块的语义角色。2.2 扫描件与图片型PDF必须上OCR但OCR只是第一步扫描件本质上就是图片。银行回单、老合同、纸质报告扫描归档这些文档没有文本层只能走OCR。但OCR先要解决图像质量问题倾斜、暗角、折痕、低分辨率都会显著降低识别率。我在项目中处理过一批手机拍摄的合同照片直接用OCR识别错字率感人。后来加入预处理环节——透视矫正、自适应二值化、降噪识别准确率才上来。这项经验后面在实操部分详细展开。OCR完成后还有更关键的问题版式还原。扫描件里标题居中、正文两端对齐、表格带框线这些信息OCR引擎不一定能自动还原成结构。你需要版面分析Layout Analysis能力找出哪些坐标区域是标题哪些是正文哪些是表格哪些是页眉页脚。2.3 复杂版式文档表格是重灾区多栏/图文混排也要留心如果说前面两类是常规题复杂版式就是压轴题。核心难点集中在三块表格、多栏布局、图文混排。表格为什么难因为表格的信息不仅存在于单元格文字里还存在于行列关系中。哪怕OCR把每个格子的字都识别对了行跨列、列跨行、合并单元格这些结构一旦丢了表格数据就没法用。更麻烦的是无框线表格——文字靠空格对齐——这几乎是所有表格识别模型的老大难。多栏布局又是另一个问题。论文通常两栏排版阅读顺序是先左栏从上到下再右栏从上到下。解析器如果按坐标从左往右、从上到下扫描会把两栏内容混成一条乱七八糟的文本流。图文混排这块常见的是图片里有文字信息截图、流程图标注、海报文字。处理策略是识别出图片区域裁剪后用OCR或多模态模型抽取并跟主文本流做位置关联。提示真实项目中以上问题往往叠加出现。一份扫描版论文既有多栏又有图表还有公式。建议先按“文本型/扫描型/混合型”给文档分类再决定解析管线复杂度。3. 核心管线设计与工具选型把解析拆成五层每层都能独立替换3.1 一个能落地的解析管线的五层架构我做了好几个项目之后总结出一条基本管线按数据流从原始文件到结构化输出拆成五层。这个架构的好处是每层都可以独立替换出了问题也好定位。第一层文档加载与格式识别。处理输入文件判断类型PDF/Word/PPT/图片检查是否加密、是否扫描版、总页数、文件大小。这一层决定后面走哪条解析分支。第二层图像预处理。只针对扫描件包括透视矫正、倾斜检测、降噪、分辨率增强。这一层对OCR准确率影响巨大但经常被忽略。第三层版面分析与区域切分。识别页面上的标题、段落、表格、图片、页眉页脚区域确定阅读顺序。这是结构还原的关键。第四层内容抽取。对文本区做字符提取对扫描区做OCR对表格区做结构还原对图片区做裁剪和描述。第五层结构化输出。把抽取结果转成Markdown、JSON或按字段组织的schema供Agent/RAG消费。文档解析工具五花八门本质差异就在这五层的覆盖深度。轻量方案只做第一层和第四层的部分工作重型方案会覆盖全部五层。选型之前先想清楚你的文档复杂度需要哪些层别一上来就堆重型方案。3.2 主流工具盘点各自适合什么场景坑在哪这几年我试过不少解析工具按定位分成三类。第一类轻量PDF文本提取库。代表包括PyMuPDF、PDFPlumber、pdfminer.six。这类库速度快、部署简单、适合文本型PDF。PyMuPDF对坐标信息的访问非常灵活我经常用它拿文本位置做自定义规则比如判断某段文字是否在页眉区域。PDFPlumber擅长处理带表格线的简单表格有Table Extraction API可以直接用。但弱点很明显对扫描件无能为力对复杂版式没有理解能力。第二类OCR引擎。老牌的有Tesseract新一些的有PaddleOCR以及一些商业OCR服务。PaddleOCR做中文识别的效果比Tesseract好不少尤其是印刷体中文的准确率。商用OCR服务一般在车牌、票据、证件等特定场景做了优化通用文档的表现也稳定但按调用量收费私有化场景要评估成本。第三类文档解析框架/服务。这类工具主打版面分析和结构还原直接输出Markdown或JSON包括开源项目如PP-StructureV2也有商业化的解析服务如LlamaParse等。它们的通病是“方便但黑盒”遇到格式怪异的文档你很难干预内部逻辑出了问题也只能换工具。我的做法是用开源框架作主解析预留自定义后处理接口关键业务文档走自定义规则。不要迷信某一个工具银弹。我见过不少人试图用一个解析器处理所有文档类型结果在特定格式上反复挣扎。成熟的做法是写一个解析路由先识别文档类型再按类型分发给对应的解析模块。办公软件生成的PPT、含有大量数据表格的Excel、带签章扫描件最优解析路径完全不一样。3.3 选型决策的几条硬经验如果文档是从办公软件导出的文本型PDF优先试PyMuPDF 轻量规则。速度极快效果不差。如果文档是扫描版但版式规整如标准A4文字页上标准OCR管线预处理 OCR 最小版面分析。如果文档是复杂版式论文、杂志、年报先尝试文档解析框架同时做好后处理方案。如果文档批量小、但解析效果要求极高比如法律合同审查可以考虑人工抽查 高精度模型组合。注意部署环境对选型的影响不容低估。很多OCR模型对GPU有依赖纯CPU环境识别速度可能慢得不可接受。如果只能CPU部署建议优先选轻量OCR模型或分布式任务队列方式把单页处理时间控制在可接受范围。这个取舍我在第五节会展开。4. 实操过程从零搭一套可复用的文档解析能力4.1 环境准备与依赖安装我用Python做了一套基础解析环境组合如下pymupdf1.24.x # PDF文本与坐标提取 pdfplumber0.11.x # 简单表格提取 pdf2image1.17.x # PDF转图片扫描件走OCR路径 opencv-python4.9.x # 图像预处理 paddleocr2.7.x # OCR引擎 ppstructure0.1.x # 版面分析表格还原、标题检测安装时有两个坑。一个是PaddleOCR依赖的PaddlePaddle不同Python版本、不同CPU/GPU环境对应不同安装指令建议先查官方安装说明再装。另一个是系统底层库的依赖pdf2image需要系统安装Poppler否则运行时直接报错如果走PaddleOCR的GPU版本还需要特定版本的CUDA和cuDNN。安装完成后建议先跑一个最小化冒烟测试用一张清晰的扫描图片做识别确认OCR引擎可用再用一个多页文本型PDF确认提取正常。别在依赖没验证完的时候就开始写流程代码。4.2 文本型PDF的提取用坐标规则还原结构我的处理逻辑大致是import fitz def extract_text_with_positions(pdf_path): doc fitz.open(pdf_path) blocks [] for page_num in range(len(doc)): page doc[page_num] # 获取页面文本块包含坐标信息 page_dict page.get_text(dict) for block in page_dict[blocks]: if lines not in block: continue # 计算块的平均字号、位置、文本内容 text max_size 0 min_x float(inf) min_y float(inf) for line in block[lines]: for span in line[spans]: text span[text] max_size max(max_size, span[size]) min_x min(min_x, span[bbox][0]) min_y min(min_y, span[bbox][1]) blocks.append({ page: page_num, text: text, size: max_size, x: min_x, y: min_y, bbox: block[bbox] }) return blocks拿到每个文本块的坐标、字号、字体信息后就可以写规则了。字号明显大于正文的大概率是标题Y坐标位于页面顶部固定区间的可能是页眉文本块宽度超过页面宽度的一半且X坐标在页面中线左侧可能是左栏内容。这套坐标规则在版式规整的文档上准确率相当高。唯一要小心的是表格区域PDF文本层里的表格get_text提取出来往往是按行排列的纯文本列的结构信息横坐标会被打成不规则的坐标序列没法直接还原成表格。遇到表格我建议单独用PDFPlumber提取它有专门的表格线检测逻辑能输出行列结构。4.3 扫描件的OCR管线预处理决定成败我的OCR管线固定包含四步。第一步是倾斜矫正用图像上的文字边缘计算倾斜角度再做仿射变换。第二步是透视矫正适合手机拍摄或扫描歪斜的文档找四个角点做透视变换。第三步是灰度化与二值化降低干扰信息。第四步是去噪去掉孤立噪点。代码示例import cv2 import numpy as np def preprocess_image(img): # 灰度化 gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) # 自适应阈值二值化处理光照不均 binary cv2.adaptiveThreshold( gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 31, 15 ) # 形态学开运算去噪 kernel np.ones((3, 3), np.uint8) cleaned cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel) return cleanedOCR效果的差异很多时候不是引擎的差距而是预处理没做好。我用同样的OCR引擎做过对比原图直接识别准确率约88%预处理后能到96%以上。而文档解析这种场景里5个百分点的准确率差距意味着每二十个字就少错一个。注意图像预处理不是加得越多越好。过度平滑会让笔画变细、粘连OCR反而识别不动。正确做法是先试原始图发现问题再针对性处理。4.4 版面分析怎么把页面切成“标题/正文/表格/图片”用PaddleOCR提供的PP-Structure做版面分析时它能输出每个区域的类型和坐标框。我们拿到结果后按区域类型做后续处理标题区域直接取文本标记为标题层级正文区域OCR识别按阅读顺序排列表格区域切成独立块走专门的表格结构还原逻辑图片区域裁剪保存可后续用多模态模型做描述版面分析完成后还要做一个阅读顺序重建。PP-Structure等工具输出的区域框顺序可能是从左到右的对多栏文档不友好。我的做法是按区域类型排序先标题再正文正文内部再按从左上到右下的对角线方向排序表格和图片就近插入相关正文附近。这个阅读顺序的调整对Agent问答效果影响比很多人想象的大。页面内容顺序错乱时模型会把不相关的句子拼在一起理解输出质量崩坏是必然的。4.5 表格还原最花时间的一环表格还原我分两个路径处理。路径一是文本型PDF里的表格优先用PDFPlumber的extract_table它能识别表格线返回二维数组格式数据。路径二是扫描件里的表格先用PP-Structure检测到表格区域再用其附带表格结构识别能力还原单元格。但这两条路径对无框线表格都表现吃力。这种表格靠空格实现列对齐没有物理线可依赖。我的临时方案是把表格区域的行文本按Y坐标聚类再按X坐标投影分析列边界。准确率谈不上完美但在规整表格上基本可用。还有一个藏在细节里的问题表格跨页。一张大表页脚处断掉下一页接着排版。解析时如果不做合并这张表就变成两张残缺表。我的处理逻辑是记录上一页末尾表格的列结构下一页开头如果检测到同结构的表格残片自动拼接合并。表格数据在结构化输出里我习惯优先输出成Markdown表格同时在JSON里保留二维数组的原始形态。Agent做数值计算、对比分析时用二维数组更稳Markdown便于人类阅读和调试。4.6 输出Markdown与JSON给Agent喂结构化内容解析管线的最终产物我统一整理成两种格式。一种是Markdown保留标题层级、列表、粗体、表格、图片引用供人类阅读和后续直接送进模型上下文。一种是与Markdown对应的JSON schema包含页面信息、区域类型、文本内容、表格二维结构、图片路径。当Agent处理具体任务时我会根据任务类型决定给哪份输出。做总结类任务给Markdown就够做合同条款提取这类字段解析任务必须给结构化JSON。5. 在Agent里接入文档解析架构设计与调用方式5.1 把文档解析封装成Agent ToolAgent里接入文档解析最简单的做法是把它封装成一个标准工具函数交给Agent在需要时自动调用。关键点在于工具的描述、参数设计和返回格式。工具描述要写清楚“这个工具能做什么、适合处理什么输入、不适合处理什么”。我见过Agent反复误调解析工具的场景多半是描述太模糊导致Agent拿它去做文本摘要。参数设计上我保留几个核心参数文件路径、解析模式快速/完整、输出格式markdown/json、是否启用OCR兜底。快速模式只提取文本型PDF完整模式走全部五层管线适合扫描件和复杂排版。返回格式上除了解析结果一定要附带元信息总页数、解析耗时、检测到的区域数量、OCR置信度。Agent判断解析成功与否、决定要不要换路径试试全靠这些元信息。5.2 大文件怎么处理分页解析与增量注入实际项目里经常遇到几百页的大文档。一股脑解析丢给AgentToken消耗爆炸不说模型上下文窗口也装不下。我的处理策略是解析阶段按页或按章节切块每块保留“页码 章节路径”元数据首轮只给Agent注入文档目录、章节摘要、前几页全文让Agent大致了解文档内容后续根据Agent提问内容动态检索相关章节再注入对应解析结果这个分块、按需注入的组合让Agent能处理远超上下文窗口的大文档。很多所谓的“长文本能力不够”其实不是模型问题是解析和调度策略没跟上。5.3 与RAG结合的chunk策略如果Agent走RAG路线解析结果还得做分块chunking。这里我踩过一个坑按固定字符数比如500字一刀切分块会把表格从中间切断、把列表拆得支离破碎。检索召回时相关片段被切成两截怎么都召不全。我的经验是尽量按语义边界分块比如标题下的一整节算一个大块表格作为一个整体块列表作为完整块。如果块过大比如超过2000字再在段落边界处做二次切分并给相邻块之间保留少量overlap防止边界处的关键信息丢失。另外表格类内容分块时我强烈建议保留表头描述。单独检索表格中部时模型看到只有单元格数值、没有列名的片段很难理解语义。我的做法是在表格块的文本前自动加一行说明格式类似“在《某合同》中第五条包含以下费用明细表列为项目名称、金额、备注”。5.4 私有化部署时怎么平衡成本和效果文档解析可以全走本地开源模型也可以部分调用商业服务。我的建议是分场景权衡对数据不敏感的通用文档商业解析服务省心省力效果好对数据敏感的合同、内部报告必须私有化部署私有化部署的典型问题是识别速度。我在纯CPU机器上跑PP-Structure处理一个复杂扫描页耗时要超过10秒批量处理几百份文档总时长累计起来就不可接受了。这时候要么上GPU要么把解析任务丢进队列异步处理配合缓存机制避免重复解析同一份文件。缓存这个点值得多说一句。很多项目反复解析同一批文档纯粹是浪费算力。我一般用文件哈希做一层缓存文件没变直接读缓存结果。顺手再建一层业务语义缓存同一份合同不同Agent会话之间共用一份解析结果数据一致性更好也更省资源。6. 常见问题与排查技巧实录6.1 表格数据丢失或错乱表现表格区域提取后单元格内容少了一列或者行列错位。排查思路先看表格区域是否被正确检测用版面分析的可视化结果检查区域框再看跨页表格是否合并正确最后检查是否有无框线表格这类表格需要单独做列边界分析。我踩得最多的坑是文本型PDF里表格线被当作“图形”对象PDFPlumber默认不识别导致extract_table返回空。解法是给extract_table加上vertical_strategy和horizontal_strategy参数指定用线条检测还是文本对齐检测。6.2 OCR漏行、错字集中在某些区域排查先看预处理效果。比如页面边缘的字太小、光照不均导致二值化失败常见。我的处理是针对性做局部增强而不是全局套同一套预处理参数。扫描件里的印章、水印会产生大片噪点干扰识别我会先检测水印区域并做遮盖处理。如果错字集中在数字、英文大小写上确认OCR引擎的语言模型是否同时加载了中英文字典。PaddleOCR默认支持中英文混合但个别场景比如识别化学式、专业缩写要额外加自定义词典明显提升准确率。6.3 解析结果速度太慢单页超过10秒就得关注了。优先排查是否走了全量版面分析复杂文档可以跳过不必要的区域类型检测。还可以把多页文档并行解析用进程池或队列同时跑多个页面的解析任务多核CPU环境能明显提速。6.4 模型上下文被解析结果灌满解析结果过长的原因一般是块切分太粗、附件信息页眉页脚混入正文、图片被转成大量无效文本。我的做法是清洗环节去页眉页脚和页码图表区域不等比例的裁剪压缩保存。尽量在解析层减少垃圾信息别指望模型自己过滤。6.5 字号、字体识别不准导致标题层级判断错误单纯用字号判断标题层级在处理嵌套标题时容易出错。我的经验是结合多维度判断字体是否加粗、是否居中、与上下文的间距大小、所在区域是否有列表序号特征。规则实在判断不了的就交给小模型做语义分类让模型判断这段文字更像标题还是正文。我做了一个简单的文档解析问题速查表每次排查先按这个顺序过一遍症状优先排查项常用解法扫描件识别率低图像预处理是否到位倾斜矫正、二值化、去噪表格行列错乱表格区域检测、跨页合并调整表格检测策略、手动拼接多栏阅读顺序错版面分析区域排序按类型和位置重建阅读顺序大文档Token爆炸分块和注入策略按语义分块、按需注入解析速度慢是否全量跑重型模型批量并行、跳过无关检测7. 写在最后如果能重来我会先做三件事文档解析这块我折腾了挺长时间如果现在从头搭建一套我会把注意力提前放在三件事上。第一件先建立一套文档类型画像。别急着写解析代码先收集自己业务场景里可能出现的文档样本按格式、版式复杂度、是否需要OCR、表格密度这几个维度做分类。花一天时间做这件事后面省下的是几周的返工。第二件解析质量要做量化评估。找个包含典型版式的测试集定好指标文本准确率、表格还原率、标题识别正确率每次改完管线就复跑一遍。没有评估标准你无法判断修改到底是变好了还是变坏了只能凭感觉调参这是最让人崩溃的。第三件把解析管线设计成可插拔的。不同文档走不同解析路径同一个路径里的每个环节能独立替换。商业解析服务效果好但一旦换供应商你的管线不能被绑定死要能快速切换。开源模型免费但效果不够就得能无缝换成商业服务。我实际干活时还有一个习惯任何一份解析结果我都会抽样做人工抽检。抽样数量不多比如每百页抽三到五页重点看表格区域和复杂版面。模型再强也有盲区人工抽检是最后一道保障。如果你正在做Agent里的文档解析建议把这套抽检机制也加进流程。解析层稳定了上层Agent的效果才能谈得上可控。最后再分享一个小技巧保存解析结果时把原始文件、解析代码版本号、模型版本号一起存下来。一份文档的解析效果不对你可以沿着版本链排查是换了模型、改了预处理、还是加了新规则导致的。否则解析结果变了你连变化原因都找不出来数据管线就变成了黑盒。这行干得越久越觉得可复现性比临时效果更重要。