Zerox OCR 上手指南:PDF、Word、图片如何快速转成 Markdown

Zerox OCR 上手指南:PDF、Word、图片如何快速转成 Markdown

【免费下载链接】zeroxOCR & Document Extraction using vision models项目地址: https://gitcode.com/GitHub_Trending/ze/zerox

Zerox 是一个开源的 OCR 文档提取工具,核心思路一句话就能说清:它不靠传统的字符识别,而是把 PDF、Word、图片等文件逐页转成图片,再交给 GPT-4o 这类视觉模型,要求模型按 Markdown 格式输出,最后把每页的结果拼回一份完整文档。仓库里同时提供 Node.js 和 Python 两套 SDK(node-zerox/与py_zerox/pyzerox/),可以git clone https://gitcode.com/GitHub_Trending/ze/zerox拿到全部源码。

先看清楚它解决了什么问题

如果你做过文档数字化,大概率被下面这几件事坑过:

• 版式一乱,解析就崩。传统 OCR 按行读取文本,遇到多栏排版、图表、发票上的表格,输出常常是错位或残缺的文字流。Zerox 把每一页当作一张图整体交给视觉模型,版式再怪,模型也是"看着图说话",天然按视觉位置组织内容。
• 扫描件没法直接喂给大模型。很多文档进 RAG 或知识库之前,需要先变成干净的 Markdown。Zerox 的输出就是带标题层级和表格语法的 Markdown,可以直接入库,不用再做二次清洗。
• 想要的不是全文,是几个字段。比如只要发票号、金额、日期。Zerox 支持传一个 JSON Schema,让模型只抽取结构化数据,而不必先转全文。

需要说明的一点:它的处理方式是"逐页调模型",所以成本和耗时与页数正相关。对几百页的超长文档,建议先用页面筛选只转需要的部分(下面会讲)。

文档是怎么被转成 Markdown 的

整个流程只有四步:

1. 传入文件(PDF、DOCX、图片等 20 多种格式);
2. 借助graphicsmagick、ghostscript、libreoffice等把文件转成逐页图片;
3. 把每页图片发给视觉模型,提示词要求"只输出 Markdown,不带解释文字";
4. 聚合所有页面响应,返回合并后的 Markdown。

提示词本身很短,可以翻一下仓库里的 shared/systemPrompt.txt:它要求保留页眉页脚、把图表转成表格、纯图片用[图片描述]占位。也就是说,输出风格是可以预期且固定的。

Node.js 三步装好

第一步,安装 npm 包:

npm install zerox

第二步,Linux 环境下补上 PDF 转图片所需的系统依赖:

sudo apt-get update sudo apt-get install -y graphicsmagick

第三步,写好第一个调用:

import { zerox } from "zerox"; const result = await zerox({ filePath: "path/to/your/document.pdf", credentials: { apiKey: process.env.OPENAI_API_KEY }, }); console.log(result.pages[0].content);

返回结果里除了各页的content(Markdown 文本),还有inputTokens/outputTokens、completionTime、summary(每页成功/失败数),方便你在批量任务里做成本和稳定性监控。

只处理指定页面

处理整本文档前,可以先用pagesToConvertAsImages指定页码,传数组(如[1, 2, 3])或单个页码,-1表示全部。这样既能快速验证效果,也能给长文档省 token:

const result = await zerox({ filePath: "report.pdf", pagesToConvertAsImages: [1, 2], credentials: { apiKey: process.env.OPENAI_API_KEY }, });

跨页表格和长文档怎么处理

跨页表格:maintainFormat

默认情况下各页是独立请求,如果一张表格横跨两页,模型在第 2 页看不到第 1 页的表头,拼出来的 Markdown 表格容易断行。开启maintainFormat: true后,Zerox 会把上一页的输出作为上下文一起发给模型再转下一页:

请求 1 → 第 1 页图片 请求 2 → 第 1 页 Markdown + 第 2 页图片

代价是页与页之间变成串行执行,速度会明显下降。所以建议只给"表格多、经常跨页"的财务类、报告类文档开启,普通文本文档没必要。

并发数怎么设

默认concurrency: 10,即同时最多 10 页在跑。页数多的文档可以按 API 限流情况往上加;如果发现请求开始报错,再往下调。配合失败重试与错误模式,批量任务不会因单页失败而整体中断:

const result = await zerox({ filePath: "large-document.pdf", concurrency: 15, maxRetries: 1, // 单页失败后的重试次数 errorMode: ErrorMode.IGNORE, // 或 ErrorMode.THROW });

另外imageDensity(默认 300 DPI)控制转图精度,文字偏小的扫描件可以适当调高,换取更清楚的识别。

只要字段,不要全文:按 Schema 抽取

如果目标是拿结构化数据,把extractOnly设为true并提供 JSON Schema,返回的就是按 schema 组织好的字段,而不是整页 Markdown:

const schema = { type: "object", properties: { invoiceNumber: { type: "string" }, totalAmount: { type: "number" }, date: { type: "string" }, }, }; const result = await zerox({ filePath: "invoice.pdf", extractOnly: true, schema, credentials: { apiKey: process.env.OPENAI_API_KEY }, });

两个补充:用extractPerPage: true可以按页抽取而不是整份文档一次性抽取;还可以单独指定extractionModel等参数,让"OCR"和"抽取"用不同模型。这部分是 Node.js 版独有的能力,Python 版暂不支持 schema 抽取。

上面这类带运单号、费用明细表格的发票,正好是 schema 抽取的适用对象:一次请求拿到发票号、金额、日期,后续对账脚本直接消费。

Python 版:基于 LiteLLM 的用法

Python 包叫py-zerox,底层走 LiteLLM,因此模型覆盖面更广(OpenAI、Azure OpenAI、Anthropic、Google Gemini、AWS Bedrock、Vertex AI 等),模型名按提供商/模型的格式书写。

安装前注意:PDF 转图依赖系统的poppler,需先在 PATH 中可用:

pip install py-zerox

调用是异步接口,核心参数比 Node 版精简,且多了一个custom_system_prompt,可以整体覆盖默认提示词:

from pyzerox import zerox import asyncio async def main(): return await zerox( file_path="path/to/document.pdf", model="gpt-4o-mini", output_dir="./output", concurrency=10, maintain_format=False, ) result = asyncio.run(main())

API Key 通过环境变量提供(如OPENAI_API_KEY),模型选择规则参考 LiteLLM 的 providers 文档即可。

两套 SDK 能力差异一览

完整对照表在 README.md 的功能矩阵里,选语言时可以直接照着挑。

常见坑与几个实用参数

• PDF 转图失败:先确认graphicsmagick(Node)或poppler(Python)已装进 PATH,postinstall脚本会自动尝试拉依赖,但部分系统仍需手动安装。
• 临时文件堆积:转换过程会在临时目录生成逐页图片,默认cleanup: true会在结束后清理;磁盘紧张时可用tempDir指定专用目录。
• 页面方向歪斜:默认correctOrientation: true会尝试识别并矫正页面朝向,trimEdges: true会裁掉页边与背景色相近的空白像素,两者对扫描件都有帮助。
• 单页失败:用errorMode: ErrorMode.IGNORE(默认)可跳过坏页继续跑,最后从summary.ocr.failed里核对失败页数;调试阶段建议换成THROW让问题立刻暴露。

整体来看,Zerox 把"文档 → 图片 → 视觉模型 → Markdown"这条链路封装成了一个函数调用,Node.js 和 Python 各有一套,功能上略有取舍但核心一致:表格和版式交给视觉模型,结构化抽取交给 schema,长文档交给并发和页面筛选。想继续了解内部实现,可以直接看 node-zerox/src/ 下的utils/file.ts(文件转图)和utils/model.ts(模型调用),Python 侧对应 py_zerox/pyzerox/processor/。

【免费下载链接】zeroxOCR & Document Extraction using vision models项目地址: https://gitcode.com/GitHub_Trending/ze/zerox