扫描版 PDF 的处理逻辑：从本地 OCR 到 Vision 大模型

处理扫描版 PDF 时，一个常见的陷阱是先用传统 OCR 工具跑完全量，再花费大量时间清洗错误结果。本文从一次 Hermes Agent 执行的大尺寸扫描版 PDF 提取任务出发，抽象出一套更通用的处理逻辑：如何以最小的沉没成本，高效、高质量地完成扫描版 PDF 的识别与结构化整理。

一、先判断：这是"图像书"还是"文档"

拿到 PDF 后的第一步不是直接提取，而是做类型探测。很多扫描版 PDF 外表上是 .pdf，内部却没有任何可提取的文本层。

快速探测流程pdfinfo 查看页数、尺寸、文件大小；pdftotext -f 1 -l 3 抽取前 3 页；若输出为空或仅有乱码，立即判定为图像型 PDF，停止在文本提取工具上投入时间。

这一步通常只需几秒钟，却能避免后续数小时的无用功。

二、本地 OCR 的职责应当最小化

确认是图像型 PDF 后，很多人的第二反应是启动 Tesseract 等传统 OCR 工具进行全量识别和清洗。但在实际任务中，这种做法的边际收益往往很低：

• 本地 OCR 对印刷体英文的识别尚可，但对中英混合排版的中文释义容易出错；
• 清洗脚本只能处理排版噪音（页眉、页脚、表格线），无法修复语义层面的识别错误；
• 当最终目标是结构化、可直接使用的高质量文本时，清洗代码的投入很容易变成沉没成本。

更合理的定位：传统 OCR 只负责"结构探测"——确认内容的页码分布规律（例如"每 2 页为 1 个单元"）、主题标题的位置、页面上需要排除的干扰元素类型。具体的内容提取，应交给更准确的工具。

三、决定性环节：引入 Vision 大模型直接识别

在本次任务中，Hermes Agent 在确认本地 OCR 的中文质量不可接受后，自行编写 Python 脚本，直接调用了外部的 Vision-Language 模型（Qwen/Qwen2-VL-72B-Instruct）进行重新识别。这是最终决定输出质量的转折点。

3.1 模型选择的教训

最初测试了名为 OCR 的专用模型，但该模型指令遵循能力较弱，会反复输出页面上的复习表格和标记符号，无法按要求只提取目标内容。这说明：

模型标签不等于任务适配度。 对于需要严格格式化输出、过滤大量页面噪音的场景，通用 Vision 模型的指令遵循能力往往更可靠。Agent 应当通过小样本快速测试来选择模型，而不是被模型名称所误导。

3.2 调用方式的安全实践

外部 API Key 并未硬编码在脚本中，而是通过 ~/.hermes/.env 配置的环境变量注入（如 SILICONFLOW_API_KEY），由脚本通过 os.environ 读取。这种实践符合安全要求：

• 密钥不暴露在任何代码文件或日志中；
• 凭据存储在用户主目录的受控配置里；
• 仅在当前会话生命周期内有效。

对于 AI Agent 而言，通过 ~/.hermes/.env 获取环境变量是调用外部服务的标准且安全的方式。

四、页面拼接策略：把连续页面合并后统一识别

扫描版书籍、教材、试卷往往存在跨页连续排版的内容。如果逐页单独上传给模型，可能导致：

• 上下文割裂，模型误判两页内容的关联性；
• 跨页断开的条目被截断或遗漏。

本次任务采用的策略是：

将逻辑上连续的多个页面垂直拼接为一张长图，再上传给 Vision 模型统一识别。

具体做法：

• 用 pdf2image 将连续页转换为图片；
• 用 PIL 将多张图片垂直拼接成一张长图；
• 以 JPEG 格式压缩后编码为 base64，通过 API 上传。

这种方式的优势在于：保持了阅读的连续性和空间关系，减少了 API 调用中的上下文切换，同时也节省了多次请求的开销。

五、Prompt 设计：格式化输出的刚性约束

为了让 Vision 模型输出可直接写入文件的纯净文本，prompt 需要包含以下刚性约束：

1. 明确排除项：列出页面上所有非目标内容（表格、圆圈标记、页码、使用说明等），要求模型主动忽略；
2. 格式模板：规定每个条目的输出格式，例如 序号. 英文单词 音标 词性 中文释义；
3. 固定头部：强制要求输出开头包含统一的标题结构，方便后续自动化处理；
4. 参考文本辅助：将本地 OCR 的初筛结果附在 prompt 末尾，让模型基于图片进行"对比修正"，而不是从零盲猜。这能显著提升输出准确率和完整性。

六、核心方法论：先验证，再全量

无论使用什么工具链，处理扫描版 PDF 时最重要的一步是：

理解问题 → 拆解问题 → 最小化验证 → 全量执行。

6.1 最小化验证的内容

在启动全量批处理之前，Agent 应当先用最小成本验证以下要素：

• 页码映射规律：几天/几章？每章占几页？边界在哪里？
• 模型识别能力：当前 DPI 下，模型能否准确识别字体、音标、中英混合内容？
• Prompt 稳定性：连续 1~3 个样本的输出格式是否一致？是否遗漏内容？
• 成本估算：单页/单章的 token 消耗是否在预算范围内？DPI 是否可以降级？

6.2 分辨率动态降级

图像 token 成本与分辨率大致成正比。可以先以低 DPI（如 100 DPI）测试 Vision 模型，如果识别率已足够，就不必使用 150 DPI 或 250 DPI。对于字体较大的印刷品，100 DPI 往往已能满足需求，可降低约 50% 以上的图像编码成本。

6.3 结构化输出的可能性

如果 API 支持 JSON mode，可以直接要求模型返回结构化数组（如 {"word", "phonetic", "pos", "definition"}），从而彻底消除后处理清洗代码，提升自动化程度和可维护性。

七、交付结构：原始数据与精校结果隔离

在处理可能产生多版本结果的任务时，建议采用双目录隔离的设计：

~/output-raw/        ← 本地 OCR 或初筛结果（保留，供回溯对比）
~/output-refined/    ← Vision 模型精校后的最终版本（推荐使用）

这种设计的好处：

• 原始数据不丢失；
• 任何单元的精校结果都可以与原始输出做 diff；
• 不会因为覆盖操作导致无法回滚。

八、给 AI Agent 的前置检查清单

如果你是 AI Agent，在接到"从扫描版 PDF 中提取结构化内容"的任务时，请按以下顺序执行：

1. PDF 类型探测：pdfinfo + pdftotext 抽样，确认是否为图像型 PDF；
2. 结构规律探测：用最低成本的方式（低分辨率 OCR 或少量 Vision API 调用）确认"页→章节/单元"的映射规律；
3. 方案验证：用 Vision 模型处理前 1~3 个单元，验证输出格式、完整性和准确率；
4. API Key 安全：从 ~/.hermes/.env 环境变量读取，绝不硬编码；
5. 全量并发执行：确认无误后再批量处理，结果保存到独立目录，不覆盖原始数据。

九、结论

对于扫描版 PDF 的内容提取，工具链的选择顺序比单一工具的能力更重要。传统 OCR 适合作为低成本的结构探测前哨，但如果最终目标是可直接使用的高质量结构化文本，Vision-Language 模型才是质量的最终保障。

最昂贵的错误，往往不是选错了模型，而是在没有经过最小化验证的情况下就启动了全量批处理。Agent 应当在早期就建立"验证样本 → 调整参数 → 全量执行"的节奏，以控制沉没成本并确保最终交付物的可靠性。