pdfvision让 AI 智能体具备类似人的 PDF 视觉

为什么是 pdfvision ​

许多 PDF 提取工具只给智能体一段字符串，并要求它信任结果。真实文档中，这种方式很容易失败：双栏论文、含义藏在形状里的幻灯片、带图表和表格的报告、政府表单、带 OCR 残留的扫描件，以及文本层包含兼容字形或乱码的多语言 PDF，都不能只看一条扁平文本流。

pdfvision 围绕一个不同的循环设计：

1. 提取 PDF 的原生信号。
2. 判断这些信号是否可信。
3. 定位真正重要的证据。
4. 只对需要进一步检查的页面或区域进行渲染或 OCR。

这个循环更接近人类阅读 PDF 的方式。你会先浏览页面，注意视觉页面和提取文本是否不一致，放大图表或表单字段，并保留可验证的原始证据。

它给智能体什么 ​

pdfvision 在一个 CLI 和 TypeScript 库中组合了智能体需要的 PDF 信号：

• 带 Unicode 规范化的原生文本，以及可选的 raw text。
• 字符数、图像数、矢量数、文本覆盖率、原生文本状态等逐页密度与质量字段。
• 布局块、标题、多栏阅读顺序、竖排 CJK、数字表格提示、重复页眉/页脚检测。
• 面向视觉模型的页面 PNG 与目标区域裁剪。
• 扫描或图像型页面的 OCR 文本、置信度、语言和词级 bbox。
• 横跨原生文本、可见表单值、FreeText 注释和 OCR 输出的搜索匹配与 bbox。
• 用于图、图表、表格、表单和图示裁剪的 raster image box、vector box 和 visual region。
• 按需输出表单字段、链接、注释、目录、页码标签、图层、viewer 设置、结构树和附件元数据。
• 乱码字形、可疑 OCR 层、密集矢量图、被压平的表格、重叠文本、页外内容、隐藏图层风险、阅读顺序分歧等人类会注意到的警告。

快速开始 ​

无需安装即可运行：

npx pdfvision document.pdf

为多模态模型渲染页面图像：

npx pdfvision document.pdf --render

从 URL 提取结构化 JSON：

npx pdfvision --remote https://raw.githubusercontent.com/mozilla/pdf.js-sample-files/master/tracemonkey.pdf --format json

搜索证据，然后只裁剪匹配区域：

npx pdfvision report.pdf --search "revenue" --json
npx pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --json

不渲染每一整页，也可以检查视觉结构：

npx pdfvision slides.pdf --layout --image-boxes --vector-boxes --visual-regions --json
npx pdfvision slides.pdf --render-visual-regions --render-output ./regions --json

文档 ​

• 快速开始 介绍基本流程。
• 使用场景 将常见 PDF 类型映射到 pdfvision 命令模式。
• CLI 选项 按任务整理主要参数。
• 结构化输出 解释智能体和工具会消费的字段。
• 布局与警告 解释应从 README 简短介绍中分离出去的视觉结构细节。
• 渲染与 OCR 覆盖图像输出、区域裁剪和扫描文档。
• 搜索与区域放大 展示如何找到文本证据，并只渲染匹配区域。