Zerox OCR 上手指南:PDF、Word、图片如何快速转成 Markdown【免费下载链接】zeroxOCR Document Extraction using vision models项目地址: https://gitcode.com/GitHub_Trending/ze/zeroxZerox 是一个开源的 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 的整个流程只有四步:传入文件(PDF、DOCX、图片等 20 多种格式);借助graphicsmagick、ghostscript、libreoffice等把文件转成逐页图片;把每页图片发给视觉模型,提示词要求只输出 Markdown,不带解释文字;聚合所有页面响应,返回合并后的 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_pathpath/to/document.pdf, modelgpt-4o-mini, output_dir./output, concurrency10, maintain_formatFalse, ) result asyncio.run(main())API Key 通过环境变量提供(如OPENAI_API_KEY),模型选择规则参考 LiteLLM 的 providers 文档即可。两套 SDK 能力差异一览能力Node.jsPythonPDF 转图依赖graphicsmagickpoppler模型接入OpenAI/Azure/Bedrock/GoogleLiteLLM,覆盖更广Schema 结构化抽取支持不支持自定义系统提示词不支持支持custom_system_prompt并发concurrency支持支持完整对照表在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考