formatactive

PDF

Byparz1 ZHOU

一种固定版面文档格式;在 AI 工作流里,它同时暴露了解析能力、运行位置与信任边界。

当前理解

PDF(Portable Document Format) 是一种以稳定呈现页面为核心的文档格式。它适合跨设备保留字体、图形、图片和版式,但不保证保留段落、标题、表格、阅读顺序等高层语义。

这也是 PDF 在 AI 工作流里经常比预期更难处理的原因。人看到的是一篇文档,解析器看到的可能是散落在页面坐标上的字符、嵌入字体、矢量路径、压缩图片、表单和附件。扫描件甚至可能只有每页一张图,没有可提取的文本层。

所以“把 PDF 给 AI”不是一次模型调用,而是一条能力链:

PDF 文件
  -> 判断运行位置与信任边界
  -> 识别 PDF 类型
  -> 提取文本或渲染页面
  -> 必要时 OCR
  -> 恢复阅读顺序与结构
  -> 切分、引用并交给模型分析

为什么它是 entity

PDF 是一个具体命名的文件格式,有标准、版本、扩展名、内部对象结构和兼容工具,因此应作为 entity 记录。

文档解析、版面理解、OCR、上下文切分和信任边界更接近 concept。PDF 卡片的作用是把这些概念锚定到一个反复出现在 Agent 工作流中的具体对象上。

云端 Chat App

把 PDF 上传到云端 Chat App 时,至少文件字节或由它生成的派生表示需要进入厂商控制的计算边界。厂商可能在服务器端完成文本抽取、页面渲染、OCR、索引、切分或多模态理解;具体链路、缓存方式和保留策略取决于产品实现与隐私设置。

这类产品通常把解析能力包装成附件体验。用户只看到上传、等待和回答,不一定看得到使用了哪种解析器、哪些页面失败、表格是否被破坏,或回答究竟来自原始页面还是提取后的文本。

因此,云端的主要问题不是“有没有 Python 库”,而是:

  • 文件是否可以离开本地信任边界。
  • 解析过程是否可观察,失败是否会被明确暴露。
  • 回答能否追溯到页码、区域或原文。
  • 扫描件、复杂表格、公式和多栏排版是否被正确处理。

本地 Agent

本地 Agent 不能假定宿主一定提供 PDF 能力。模型可能知道 PDF 应该怎样处理,但实际可执行能力取决于 agent-harness 暴露了什么工具、skill 是否能被发现、系统是否安装了解析器,以及沙箱是否允许读取文件和运行命令。

常见失败路径是:Agent 先寻找专门的 PDF 工具或 Skill,发现不可用后,临时写 Python,尝试导入 pypdf、PyMuPDF 或其他库;如果依赖也不存在,它又要继续安装、换库或把页面转成图片。最后虽然“开始分析”了,解析质量、页码对应关系和视觉结构却可能已经丢失。

更稳妥的本地能力链应该是渐进降级,而不是一上来就把 Python 当作 PDF 解析器:

层级目标典型能力
1. 发现确认宿主已有能力内置文件读取、PDF Skill、MCP 工具
2. 快速抽取处理有文本层的普通 PDFpdftotext、pypdf、PyMuPDF
3. 视觉核对保留页面版式与图表页面渲染、截图、多模态模型
4. OCR处理扫描件OCRmyPDF、Tesseract 或视觉识别
5. 结构恢复处理表格、多栏和公式版面分析、区域切分、专用解析器
6. 交付让分析可验证页码引用、失败页清单、解析产物

Python 在这里更像胶水:它可以调用库、串起流程并统一产物,但“用了 Python”不等于“正确理解了 PDF”。

Agent 应先检查什么

收到 PDF 后,一个 Agent 至少应该先回答这些问题:

  1. 文件位于本地还是云端,是否允许上传到外部服务?
  2. 宿主是否已经提供 PDF 读取、渲染或 OCR 工具?
  3. PDF 有可选文本层,还是扫描图片?
  4. 任务只需要全文检索,还是依赖表格、公式、图注和页面布局?
  5. 解析结果能否保留页码,并让用户核对原文?
  6. 哪些页面或对象没有成功解析?

这组检查把“读取文件”和“分析内容”拆开。前者是工具与运行时问题,后者才是模型问题。

与 Agent Harness 的连接

PDF 很适合用来观察 agent-harness 的能力边界。

同一个模型在云端 Chat App 中可能表现得像是“天然会读 PDF”,放进本地 Agent 却开始搜索命令、检查依赖或编写脚本。变化的通常不是模型关于 PDF 的知识,而是 harness 是否提供了文件上传、解析、渲染、OCR、依赖管理和结果回传这条完整链路。

一个成熟的 harness 不应只返回一大段抽取文本,还应该向 Agent 暴露解析模式、页数、页码映射、失败警告和可复用的中间产物。这样 Agent 才能知道自己看见了什么,也能知道自己没有看见什么。

张力与取舍

第一个张力是便利和信任边界。云端解析通常更省事,却可能不适合私密、受监管或不能离开设备的文档;本地解析保留控制权,但依赖安装、性能和格式兼容都需要自己承担。

第二个张力是文本抽取和视觉忠实。纯文本更便于搜索、切分和节省上下文,页面图像则更能保留表格、公式、图表与空间关系。可靠流程往往需要两者互相校验。

第三个张力是通用解析和任务专用解析。总结普通报告可能只需要文本层;审阅合同条款、理解论文公式或读取财务表格时,丢失版面结构会直接改变含义。

第四个张力是自动降级和显式失败。Agent 自动换用 Python 或 OCR 可以提高完成率,但如果不报告降级,用户会把低质量解析误认为完整阅读。

未解问题

  • Agent 应该把 PDF 解析能力作为内置工具、Skill,还是独立的本地服务?
  • 哪些解析元数据需要成为统一接口,才能让不同工具的结果可互换?
  • 如何让 Agent 在文本抽取与页面视觉之间自动选择,而不是对所有 PDF 使用同一条路径?
  • 云端产品应该向用户暴露多少解析过程与中间产物?
  • 解析失败应该在什么时候阻止回答,什么时候允许带着明确警告继续?

演化

  • 2026-08-24: 初始 entity,记录 PDF 在云端 Chat App 与本地 Agent 中不同的解析责任、工具发现和降级路径。