FAQ

pdfvision 是 PDF 转文本工具，还是视觉工具？

两者都是，但核心思想是证据。pdfvision 会在可用时提取原生文本，同时暴露布局、图像/矢量几何信息、警告、渲染图像、OCR、搜索匹配和 PDF 特性元数据，让智能体判断仅靠文本是否足够。

为什么提取文本为空？

PDF 可能是扫描件、图像密集、加密，或使用了自定义字形编码。请检查概览字段和 pages[].warnings，然后尝试 --render、--ocr 或 --layout。

如果页面有 empty_but_visual_content，请渲染或 OCR。若存在字形相关警告，请在信任原生文本前与渲染页面或 OCR 结果比较。

什么时候使用 --layout？

当页面包含分栏、表格、表单、脚注、重复页眉或页脚、竖排 CJK，或任何位置会改变含义的内容时使用。

--layout 对论文、报告、财务报表、表单和幻灯片导出尤其有用，因为这些 PDF 的原始文本流可能与视觉阅读顺序不同。

什么时候使用 OCR？

当原生文本缺失、稀疏、像扫描页，或与渲染图像明显不一致时使用 --ocr。

OCR 会添加在原生文本旁边，而不是替换原生文本。智能体应比较原生文本、OCR 文本、置信度和警告。

什么时候只渲染区域而不是整页？

在搜索、布局、图像 bbox、矢量 bbox 或 visual regions 找到关键区域后使用 --render-region。当模型只需要验证一个条款、表格单元格、图表标签、表单值或图形时，裁剪通常比整页渲染更合适。

visual regions 是什么？

Visual regions 是可裁剪的页面区域，可能包含有意义的图形、图表、表格、表单区块、批注、示意图，或栅格/矢量聚集区域。它们帮助智能体在把图像发送给 vision model 前先发现该看哪里。

pdfvision 可以搜索 PDF 吗？

可以。--search 会输出 pages[].matches[]，包含页码、source、匹配文本、上下文，以及可用的 bbox。搜索可以覆盖原生文本、可见表单字段值、可点击 link target、FreeText 批注，以及启用 OCR 后的 OCR 输出。

pdfvision 使用什么坐标系？

bbox 使用未旋转的 pdf.js page view 可见框原始 page-view units，并以左上角为原点。适用时该框是 CropBox ∩ MediaBox，否则是 MediaBox。x 向右增加，y 向下增加。物理点数 = 原始值 × pages[].userUnit（省略时按 1）；像素数 = 原始区域 × UserUnit × render scale。bbox 可原样传给 --render-region；旋转页使用 pdf.js 的旋转 viewport transform。

缓存在哪里？

结果缓存在操作系统临时目录中。PDFVISION_CACHE_DIR 必须指向专用绝对路径；危险的宽泛路径会被拒绝。经过所有者检查的 .pdfvision-cache-root 标记用于授权递归清理。清理绝不采用未标记的自定义根目录；无 override 时，只能在权限加固前后确认旧版形状后采用当前历史默认根目录。在 POSIX 上，会拒绝带有 group/other 写权限的未标记根目录；祖先必须可读/open、由当前用户或 root 拥有且不可写或有安全的 sticky 保护。移入 quarantine 后，st_dev 不一致会阻止递归删除，但原路径已移动，且无法检测同一 device 的 bind mount。检查依赖传统 POSIX mode semantics，不涵盖 ACL、网络文件系统权限或最终检查后的 root/同一 UID 替换。Windows 只能提供 best-effort 防护。清理不与活动 OCR 协调；被中断时请重试。--no-cache 会绕过提取缓存和远程 PDF 缓存，但 OCR support files 仍会持久化在已验证的缓存根目录下。

PDF 密码应该如何传递？

优先使用 --password-stdin，避免密码出现在进程参数中：

printf "your-password\n" | pdfvision encrypted.pdf --password-stdin --format json

应该使用哪种输出格式？

快速人工阅读使用 Markdown，工具和智能体控制使用 JSON，按照显式标签构建的使用方或提示词使用 XML。当具有相同标量字段的对象数组占多数时，可以考虑 TOON，并使用自己的文档和目标模型上下文比较各种格式。