Zerox：开源AI视觉OCR框架，复杂文档一键转结构化Markdown

一、Zerox是什么

Zerox是一款面向AI数据摄入场景的开源光学字符识别工具，核心定位是用极简方式把各类视觉形态的文档，转换成AI可直接处理的结构化Markdown格式。它由getomni-ai团队开发并维护，采用MIT开源协议，在GitHub上已获得大量开发者关注，成为文档数字化、知识管理、自动化办公领域的热门工具。

传统OCR工具依赖规则引擎与字符特征匹配，面对复杂排版、表格、公式、手写体、模糊扫描件时，经常出现错位、乱码、结构丢失。Zerox跳出传统思路，以视觉大模型为核心识别引擎，先把文档统一转为图像，再让模型像人“阅读”一样理解版面、内容、层级关系，最终输出干净、标准、可直接二次编辑的Markdown文本。

它的核心运行逻辑非常清晰：

1. 输入文件：支持PDF、DOCX、PPTX、图片（JPG/PNG）、HTML等20+格式；

2. 格式统一：将所有文件转为一页页图像；

3. 视觉识别：把图像送入GPT-4o、Gemini、Claude 3等视觉大模型；

4. 结构化输出：模型返回Markdown，工具聚合后输出完整结果。

Zerox不只是“把字抠出来”，而是理解文档、还原结构、保留格式，解决了从非结构化文档到结构化数据的最后一公里问题，让扫描件、图片、复杂PDF能直接进入知识库、RAG系统、Notion、Obsidian等工具。

二、功能特色

1. 多格式全覆盖，输入无门槛

Zerox支持几乎所有常见办公与文档格式，无需提前转换，直接上传即可处理：

• 文档类：PDF（扫描版/可复制版）、DOC、DOCX、ODT、RTF、TXT；

• 表格类：XLS、XLSX、ODS、CSV、TSV；

• 演示类：PPT、PPTX、ODP；

• 图片类：JPG、PNG、WEBP；

• 网页类：HTML、XML。

同时支持本地文件路径与远程URL两种输入方式，兼顾本地批量处理与云端文件接入。

2. 复杂版面精准还原，表格公式不丢失

这是Zerox最核心的优势。传统OCR很难处理：

• 嵌套表格、跨页表格；

• 分栏排版、左右图文混排；

• 数学公式、化学方程式、代码块；

• 手写批注、签名、潦草笔记。

Zerox借助视觉模型的理解能力，可完整保留：

• 标题层级（H1-H6）；

• 列表（有序/无序）；

• 表格（对齐、合并单元格）；

• 公式（LaTeX格式）；

• 代码块（带语言标识）；

• 段落间距与排版逻辑。

3. 零样本开箱即用，无需训练与微调

不同于传统OCR需要针对字体、语言、场景训练，Zerox完全零样本。

• 不用上传样本、不用标注数据；

• 不用微调模型、不用配置规则；

• 印刷体、手写体、模糊扫描件、低像素照片都能稳定识别。

对个人用户、中小企业、快速开发场景极度友好，开箱即用。

4. 双语言SDK支持，覆盖主流技术栈

Zerox同时提供Node.js与Python两套SDK，满足不同开发者与业务场景：

• Node.js：适合前端、全栈、自动化脚本、云函数；

• Python：适合数据分析、AI工程、学术研究、批量处理。

两者核心能力高度对齐，同时保留各自生态的灵活配置。

5. 多厂商视觉模型兼容，自由切换

Zerox基于LiteLLM封装，支持市面上几乎所有主流视觉大模型，用户可按精度、成本、合规需求自由选择：

• OpenAI：gpt-4o、gpt-4o-mini；

• Azure OpenAI：与OpenAI一致的模型；

• Anthropic：Claude 3系列；

• AWS Bedrock：Claude、Llama 2等；

• Google：Gemini系列；

• Vertex AI（仅Python）。

6. 结构化Markdown原生输出，无缝对接生态

识别结果直接输出标准Markdown，可：

• 一键导入Notion、Obsidian、Yuque、语雀；

• 直接用于RAG检索增强生成；

• 快速生成网页、博客、文档；

• 轻松复制、编辑、整理、检索。

7. 高性能批量处理，效率拉满

• 支持并发处理，一次同时处理多页，大幅提速；

• 自动图像压缩，降低API成本与传输耗时；

• 自动方向校正、边缘裁剪，提升识别率；

• 临时文件自动管理，处理完自动清理。

8. 本地部署优先，数据安全可控

Zerox支持完全本地运行（除模型API调用外）：

• 文件不上传第三方服务器；

• 中间图像、临时数据本地存储；

• 适合处理合同、票据、病历、财务报表等敏感内容；

• 满足企业合规、隐私保护要求。

三、Node.js 与 Python 版本功能对比

四、技术细节

1. 整体架构

Zerox采用分层解耦架构，保证扩展性与稳定性：

1. 输入层：接收文件/URL，做格式校验与解析；

2. 转换层：统一转为图像，做方向校正、裁剪、压缩；

3. 模型层：通过LiteLLM对接各大厂商视觉模型，统一请求/响应；

4. 输出层：聚合Markdown，做格式规整、错误处理；

5. 工具层：临时文件、并发控制、日志、异常处理。

2. 核心技术点

• 文档转图像：Node.js用graphicsmagick+ghostscript；Python用poppler+pdf2image，保证跨平台一致性。

• 图像优化：自动调整DPI（默认300）、压缩体积、校正倾斜、切除白边，提升识别率并降低token消耗。

• 视觉模型Prompt工程：内置优化的系统提示，让模型专注于结构还原、公式转LaTeX、表格标准化。

• 并发调度：控制同时请求模型的页数，避免超限与崩溃。

• 错误重试：模型超时、限流、网络异常时自动重试，提升成功率。

• 格式一致性：开启maintainFormat后，跨页面保持标题、列表、表格风格统一。

3. 依赖说明

• Node.js：必须安装graphicsmagick、ghostscript；

• Python：必须安装poppler-utils；

• 模型依赖：需要用户提供对应厂商的API Key。

4. 性能表现

• 单页处理：1–5秒（取决于模型与网络）；

• 图像压缩：体积减少60%+，token消耗降低；

• 批量处理：10页并发默认配置，可按需调高；

• 识别准确率：印刷体≥98%，手写体≥90%，表格/公式≥95%。

五、应用场景

1. 知识管理与笔记

• 扫描书籍、论文、笔记→转Markdown→导入Obsidian/Notion；

• 照片白板、手写草稿→结构化文本；

• 多文件统一格式，构建个人/企业知识库。

2. 办公自动化

• 合同、发票、收据→提取关键信息→自动录入系统；

• 批量扫描件→可编辑文档→归档/检索；

• 报表、表单→转表格Markdown→数据分析。

3. AI与RAG系统

• 非结构化PDF/扫描件→结构化数据→喂给大模型；

• 构建企业内部知识库，支持精准检索；

• 客服、法律、金融文档自动化解析。

4. 学术与研究

• 论文、期刊、古籍→转可编辑文本；

• 公式、图表→LaTeX/结构化描述；

• 文献批量数字化。

5. 内容创作与自媒体

• 图片文章、扫描稿件→快速排版发布；

• 课程PPT、讲义→转Markdown笔记；

• 多来源内容统一格式。

6. 法律与金融

• 合同条款提取、比对；

• 银行流水、票据识别；

• 敏感文件本地处理，保障隐私。

六、使用方法

（一）Node.js 版本使用步骤

1. 安装系统依赖

• macOS：brew install graphicsmagick ghostscript

• Ubuntu/Debian：apt-get install graphicsmagick ghostscript

• Windows：官网下载安装包，配置环境变量

2. 安装SDK
   npm install zerox

3. 最小化示例代码
   import { zerox } from "zerox";
   import path from "path";

   const result = await zerox({
   filePath: path.resolve(__dirname, "document.pdf"),
   credentials: { apiKey: process.env.OPENAI_API_KEY },
   });

   console.log(result.markdown);

4. 常用配置项

• concurrency：并发页数，默认10

• model：指定模型，如gpt-4o-mini

• maintainFormat：保持跨页格式

• correctOrientation：自动校正方向

• cleanup：自动清理临时文件

• tempDir：自定义临时目录

（二）Python 版本使用步骤

1. 安装系统依赖

• macOS：brew install poppler

• Ubuntu/Debian：apt-get install poppler-utils

• Windows：下载poppler并配置环境变量

2. 安装SDK
   pip install py-zerox

3. 最小化示例代码
   from pyzerox import zerox
   import asyncio

   async def main():
   result = await zerox(
   filePath="document.pdf",
   api_key="your-api-key",
   model="gpt-4o-mini"
   )
   print(result.markdown)
   asyncio.run(main())

4. 常用配置项

• custom_system_prompt：自定义提示词

• maintain_format：格式保持

• output_dir：结果保存目录

• temp_dir：临时目录

（三）在线演示（无需代码）

官方提供在线Demo，直接上传文件即可体验：
https://getomni.ai/ocr-demo

七、常见问题解答（FAQ）

Zerox 是免费的吗？

Zerox本身是开源免费的，采用MIT协议，可商用、可修改、可分发。但使用视觉模型（如GPT-4o）会产生厂商的API费用，这部分由用户自行承担。

Zerox 可以完全本地运行，不上传文件吗？

可以。文件处理、转图像、临时存储都在本地完成，只有处理后的图像会发送给模型API做识别，不会上传原始文档。

支持中文、英文、多语言混合识别吗？

支持。只要所使用的视觉模型支持该语言，Zerox就能正常输出。默认模型对中英混合支持极佳。

扫描件模糊、倾斜、有阴影可以识别吗？

可以。Zerox会自动做方向校正、边缘裁剪、对比度优化，配合视觉模型，模糊扫描件、手机拍摄文档都能稳定识别。

能识别手写体、签名、批注吗？

可以。视觉模型对手写体的理解能力远强于传统OCR，签名、潦草笔记、批注都能识别。

处理表格时会丢失结构吗？

不会。Zerox专门优化了表格识别，会输出标准Markdown表格，支持合并单元格、跨页表格、嵌套表格。

公式可以转成LaTeX吗？

可以。内置提示词会让模型把数学公式、化学方程式输出为LaTeX格式，可直接在Markdown编辑器渲染。

Node.js和Python版本该怎么选？

前端/全栈/云函数选Node.js；数据分析/AI/学术/批量处理选Python。两者核心识别能力一致。

处理大文件（几百页PDF）会崩溃吗？

不会。Zerox采用分页处理+并发控制，支持长文档。建议适当调低concurrency避免API超限。

可以用于商业项目吗？

可以。MIT协议允许商用，无需授权，可集成到SaaS、客户端、内部系统。

需要GPU吗？

不需要。图像转换与识别都由CPU与模型API完成，本地无需GPU。

如何降低API成本？

优先使用gpt-4o-mini，开启图像压缩，调低DPI，只处理需要的页面，都能显著降低token消耗。

支持加密PDF吗？

不支持。需要先解密再处理，这是出于版权与安全考虑。

输出的Markdown可以直接导入Notion吗？

可以。输出标准通用Markdown，Notion、Obsidian、Yuque、GitBook都能完美兼容。

报错缺少graphicsmagick/poppler怎么办？

这是系统依赖，按对应系统安装即可，是文档转图像的必需工具。

八、相关链接

• GitHub 仓库：https://github.com/getomni-ai/zerox

• 官方文档：https://docs.getomni.ai/zerox

• 在线演示地址：https://getomni.ai/ocr-demo

• Node.js 文档：https://docs.getomni.ai/zerox/nodejs

• Python 文档：https://docs.getomni.ai/zerox/python

九、总结

Zerox是一款以视觉大模型为核心、面向AI时代的开源文档识别工具，它通过“文档转图像+视觉理解+结构化输出”的创新路径，解决了传统OCR在复杂版面、表格、公式、手写体上的痛点，提供开箱即用、零样本、高精度、结构化的文档转换能力，同时支持Node.js与Python双SDK、多厂商模型切换、本地部署与批量处理，可广泛应用于知识管理、办公自动化、AI系统搭建、学术研究、法律金融等场景，以极简架构、稳定表现和高度灵活性，成为个人与企业实现文档数字化、结构化、智能化的首选工具。