• OCR
• AI 应用

导读

本文以 Zerox 仓库中 shared/outputs/0040.md 这一份真实 OCR 输出为案例，剖析 Zerox 如何将一张包含多语言、防伪底纹、双栏信息与 ICAO 机读码的英国护照样本页图像（shared/inputs/0040.png）转换为结构化 Markdown。你将掌握 Zerox 的核心处理链路（文档转图像 → 视觉模型转 Markdown → 聚合输出）、护照类证件的 OCR 内容结构特征，以及如何用仓库自带的test.json关键词体系对这类输出做回归验证，并了解 Node 与 Python 两种 SDK 的调用方式与关键参数。

案例背景：一份真实生成的护照 OCR 输出

shared/outputs/0040.md 是 Zerox 仓库shared/outputs目录下的第 40 号结果文件，对应输入图像 shared/inputs/0040.png。该图像是一张被手持的英国新版护照样本页：页面整体采用半透明设计，包含防伪图案（飞鸟、地图底纹、点状肖像与打孔式机读码区），上半部分为"官方备注页"，下半部分为个人信息页，底部为符合 ICAO 标准的机读码（MRZ）两行。

这张图像正好覆盖了 Zerox 官方 README 所说的典型痛点：证件文档"天生是一种视觉呈现"，布局怪异、含表格、图表、复杂底纹，传统基于文本层的提取会丢失信息，而视觉模型可以直接"看图说话"。Zerox 的整体逻辑在 README.md 中被概括为四步：传入文件（PDF、DOCX、图像等）→ 将文件转换为一系列图像 → 将每张图像交给 GPT 等视觉模型并请求 Markdown → 聚合响应并返回 Markdown。0040.md 正是这条流水线在单张图像上的产出。

0040.md 输出内容逐字段解析

原始输出全文如下（取自 shared/outputs/0040.md）：

**THIS PAGE IS RESERVED FOR OFFICIAL OBSERVATIONS** **CETTE PAGE EST RÉSERVÉE AUX OBSERVATIONS OFFICIELLES (11)** **THERE ARE NO OFFICIAL OBSERVATIONS** --- **UNITED KINGDOM OF GREAT BRITAIN AND NORTHERN IRELAND** **PASSPORT** **PASSEPORT** **Type/Type** P **Code/Code** GBR **Passport No./Passeport No.** 925600253 **Surname/Nom (1)** UK SPECIMEN **Given names/Prénoms (2)** ANGELA ZOE **Nationality/Nationalité (3)** BRITISH CITIZEN **Date of birth/Date de naissance (4)** 11 SEP / SEPT 88 **Sex/Sexe (5)** F **Place of birth/Lieu de naissance (6)** CROYDON **Date of issue/Date de délivrance (7)** 16 JUL / JUIL 10 **Authority/Autorité (8)** IPS **Date of expiry/Date d'expiration (9)** 16 JUL / JUIL 20 **Holder's signature/Signature du titulaire (10)** A Specimen P<GBRUK<SPECIMEN<<ANGELA<ZOE<<<<<<<<<<<<<<<< 9256002538GBR8809117F2007162<<<<<<<<<<<<<<06

这份输出体现了 Zerox 默认系统提示词（shared/systemPrompt.txt）的几条核心规则被忠实执行：

• "You must include all information on the page. Do not exclude headers, footers, or subtext."：输出完整保留了页眉备注区（"THIS PAGE IS RESERVED FOR OFFICIAL OBSERVATIONS"）、双语标题、签名栏与机读码，没有做任何删减；
• 双语文档的双语键值对保留：护照信息页采用英文/法文双语字段（如Surname/Nom (1)、Given names/Prénoms (2)），模型以"字段标签 + 值"的 Markdown 粗体键值结构还原，数字编号（1）～（10）也一一对应；
• 机读码（MRZ）按原样保留：底部的两行 MRZ 字符串未被当成普通文本改写，保持了 OCR 结果的原始可校验性；
• "Return only the markdown with no explanation text"：输出没有任何解释性旁白，可直接作为结构化数据消费。

从证件 OCR 角度看，这份输出的信息抽取质量较高：国籍（BRITISH CITIZEN）、出生地（CROYDON）、签发机构（IPS）、性别（F）、签发/到期日期等均被正确分类到对应字段；MRZ 第一行P<GBRUK<SPECIMEN<<ANGELA<ZOE<<<<<<<<<<<<<<<<与第二行9256002538GBR8809117F2007162<<<<<<<<<<<<<<06中，护照号（925600253）、出生日期（8809117）、性别（F）、有效期（2007162）与上方的可视字段相互印证，说明视觉模型完成了"可视区 ↔ 机读区"的一致识别。

护照识别结果的回归验证：test.json 关键词体系

0040 这个案例并非孤立产出。仓库在 shared/test.json 中为 40 份输入文档各维护了一组expectedKeywords，其中第 0040.png 的期望关键词（见该文件末尾）包括：

{ "file": "0040.png", "expectedKeywords": [ [ "OBSERVATIONS OFFICIELLES (11)", "UNITED KINGDOM OF GREAT BRITAIN AND NORTHERN IRELAND", "Code/Code", "925600253", "UK SPECIMEN", "Prénoms (2)", "ANGELA ZOE", "Nationality", "Nationalité", "CROYDON", "16 JUL / JUIL 10", "Holder's signature", "P<GBRUK<SPECIMEN<<ANGELA<ZOE<<<<<<<<<<<<<<<<", "9256002538GBR8809117F2007162" ] ] }

对照 shared/outputs/0040.md 的文本，这些关键词几乎全部命中：OBSERVATIONS OFFICIELLES (11)、UNITED KINGDOM OF GREAT BRITAIN AND NORTHERN IRELAND、护照号925600253、持有人UK SPECIMEN/ANGELA ZOE、出生地CROYDON、签发日期16 JUL / JUIL 10、以及两行 MRZ 原文，均逐字出现在输出中。这套机制的运行方式记录在 node-zerox/tests/README.md 中：测试脚本读取shared/inputs下的文档，用 Zerox 实时 OCR，再与test.json的期望关键词比对，输出命中/缺失计数与汇总表；README 明确指出这是"针对已知文档关键词的快速回归测试，虽然不覆盖版面布局，但能很好地发现回归问题"。也就是说，0040.md 既是一份 OCR 结果，同时也是一份"可回归验证"的基线样本，读者可用npm run test在配置好 OpenAI Key 后复现这一校验过程。

从图像到 Markdown：Zerox 的处理链路与源码印证

0040.md 的产生路径，可以从源码中完整还原。以 Python SDK 为例，入口函数zerox位于 py_zerox/pyzerox/core/zerox.py，其执行流程与 0040 这个案例一一对应：

1. 校验与下载：file_path为空时抛出FileUnavailable；随后download_file将本地路径或 URL 的文件落入临时目录，并生成规范化文件名（非字母数字字符转为_，截断至 255 字符）；
2. 页选择（可选）：若传入select_pages，先创建仅含所选页的子 PDF（create_selected_pages_pdf），并自动排序页号保证输出顺序一致；
3. PDF 转图像：convert_pdf_to_images基于pdf2image，默认参数定义在 py_zerox/pyzerox/constants/conversion.py：DPI=300、格式 PNG、尺寸(None, 1056)、线程数 4、启用pdftocairo。对 0040 这类本身就是单张 PNG 的输入，Node 版会直接走"图像直通"分支，不再经过 PDF 转换（见 node-zerox/src/index.ts 中针对.png/.jpg/.jpeg的imagePaths = [localPath]处理）；
4. 逐页送视觉模型：默认并发 10（concurrency=10），通过process_pages_in_batches以asyncio.Semaphore限流批量处理，每个页面调用litellmmodel.completion获取 Markdown（见 py_zerox/pyzerox/processor/pdf.py）；
5. Markdown 清洗与聚合：format_markdown通过正则剔除模型可能输出的 markdown/代码块围栏标记（见 py_zerox/pyzerox/processor/text.py），随后"\n\n".join聚合各页，可选写入output_dir/{file_name}.md；
6. 结果封装：返回ZeroxOutput，包含completion_time（毫秒）、file_name、input_tokens、output_tokens与pages列表（Page由content、content_length、page组成，见 py_zerox/pyzerox/core/types.py）。

值得强调的是maintain_format选项：当设为 True 时，Zerox 会将上一页的 Markdown 作为下一页的附加上下文传入，形成"Request #1 => page_1_image; Request #2 => page_1_markdown + page_2_image; Request #3 => ..."的串行链。这要求请求同步执行、速度更慢，但对跨页表格等场景价值明显；从 py_zerox/pyzerox/core/zerox.py 源码可以看到，maintain_format=True与select_pages同时使用时还会触发一条友好警告，提示该组合存在限制。

复现与扩展：在本地跑通同类型证件 OCR

要复现 0040 这类输出，可按 SDK 类型选择调用方式（完整示例见 README.md）。

Python 方式（依赖系统安装 poppler，pip install py-zerox）：

from pyzerox import zerox import asyncio async def main(): result = await zerox( file_path="./shared/inputs/0040.png", # 本地路径或 URL 均可 model="gpt-4o-mini", # LiteLLM 格式的视觉模型名 output_dir="./output_test", # 可选：落盘聚合 Markdown select_pages=None, # None 处理全部页面，也可传 int 或 list ) return result result = asyncio.run(main()) print(result)

Node 方式（依赖 graphicsmagick 与 ghostscript，npm install zerox）：

import { zerox } from "zerox"; const result = await zerox({ filePath: "shared/inputs/0040.png", credentials: { apiKey: process.env.OPENAI_API_KEY }, modelProvider: "OPENAI", model: "gpt-4o", outputDir: "shared/outputs", // 可选：保存合并后的 result.md });

调用时可针对证件类场景调整的关键参数（均以仓库 README 与源码为准）：

• concurrency：并发页数，默认 10；多页护照扫描件可适当调低以控制成本；
• maintain_format/maintain_format：默认 False；若护照有多页且存在跨页表格，可开启，但要接受串行带来的延迟；
• select_pages/pagesToConvertAsImages：默认处理全部页面，支持按 1 起始页号选取指定页，Node 版默认 -1 表示全部转换；
• custom_system_prompt/prompt：Python 版可用custom_system_prompt覆盖 shared/systemPrompt.txt 中的默认系统提示词（覆盖时会触发友好警告），例如追加"机读码必须原样保留、字段标签双语都要输出"等约束，进一步强化证件场景；
• cleanup：默认 True，处理完成后清理临时目录；
• output_dir：指定后把聚合结果写入{file_name}.md，与 shared/outputs/0040.md 的生成方式一致。

总结

shared/outputs/0040.md 是一个极具代表性的 Zerox 实战样本：它以一张多层防伪、双语文案、含 ICAO 机读码的英国护照样本页为输入，完整产出了可被 AI 系统直接消费的 Markdown 键值结构，并且与 shared/test.json 中 0040.png 的关键词基线逐条吻合。结合 README.md、py_zerox/pyzerox/core/zerox.py 与 node-zerox/src/index.ts 的源码，可以清楚看到这套"图像 → 视觉模型 → Markdown → 关键词回归"的完整闭环。对于护照、驾照、身份证、税单等强视觉特征证件的 OCR 需求，Zerox 提供了一条不需要维护模板、开箱即用的落地路径：传入文件、配上视觉模型凭证，即可获得结构化、可校验的 Markdown 输出。

• OCR
• AI 应用