Zerox 是一个专注于文档 OCR（光学字符识别）的工具库，核心目标是为 AI 数据摄入提供简单、高效的文档转 Markdown 能力，尤其适配包含复杂布局（表格、图表、不规则排版）的文档场景 —— 借助视觉模型处理这类视觉化文档更具优势。
核心能力与工作逻辑
Zerox 的核心流程：
- 传入目标文件（支持 PDF、DOCX、图片等格式）；
- 将文件转换为一系列图片；
- 调用视觉模型（如 OpenAI GPT 系列）解析图片内容，并要求返回 Markdown 格式结果；
- 聚合所有图片的解析结果，最终输出完整的 Markdown 文本。
核心特性
多语言支持
同时提供 Node.js 和 Python 两个版本的 SDK，覆盖不同技术栈需求：
- Node.js 版本：发布在 npm（包名
zerox）； - Python 版本：发布在 PyPI（包名
py-zerox）。
多服务商兼容
支持主流的 AI 服务商视觉模型，包括：
- OpenAI / Azure OpenAI；
- AWS Bedrock；
- Google Gemini（Python 版额外支持 Vertex AI）；
- Anthropic（Node 版支持）。
功能对比（Node.js vs Python）
表格
| 功能项 | Node.js | Python |
|---|---|---|
| PDF / 图片处理 | ✓（依赖 graphicsmagick） | ✓（依赖 poppler） |
| 自定义系统提示词 | ✗ | ✓（custom_system_prompt） |
| 数据提取（schema） | ✓ | ✗ |
| 按页提取 | ✓（extractPerPage） | ✗ |
| 格式保留 | ✓（maintainFormat） | ✓（maintain_format） |
| 并发处理 | ✓（concurrency） | ✓（concurrency） |
| 页面选择 | ✓（pagesToConvertAsImages） | ✓（select_pages） |
| 方向校正 / 边缘裁剪 | ✓ | ✗ |
| 错误处理模式 | ✓（errorMode） | ✗ |
| 临时目录管理 | ✓（tempDir） | ✓（temp_dir） |
仓库结构
plaintext
zerox/
├── .github/ # GitHub 配置（如 workflow）
├── examples/ # 示例代码（node/ 子目录对应 Node 示例）
├── py_zerox/ # Python 版核心代码（pyzerox/ 子包）
│ ├── scripts/ # Python 脚本
│ └── tests/ # Python 测试用例
├── node-zerox/ # Node.js 版核心代码
│ ├── src/ # TS 源码（含模型适配、核心逻辑）
│ ├── scripts/ # Node 脚本
│ └── tests/ # Node 测试用例
├── shared/ # 跨语言共享资源（如系统提示词、测试数据）
├── assets/ # 静态资源（示例文档、图片）
├── 配置文件 # package.json/tsconfig.json（Node）、pyproject.toml/setup.py（Python）
└── 构建/规范配置 # Makefile、pre-commit、jest.config.js 等
快速使用示例
Node.js 版
typescript
运行
import { zerox } from "zerox";
import path from "path";
// 本地文件示例
const result = await zerox({
filePath: path.resolve(__dirname, "./cs101.pdf"),
credentials: {
apiKey: process.env.OPENAI_API_KEY, // 或 Bedrock/Azure 等凭证
},
});
环境依赖
- Node.js 版：需安装
graphicsmagick+ghostscript（Linux 可通过apt-get install graphicsmagick安装）； - Python 版：需安装
poppler（PDF 转图片依赖）。
其他补充
- 提供托管演示版：https://getomni.ai/ocr-demo；
- 完整文档：https://docs.getomni.ai/zerox；
- 技术栈：Node 版基于 TypeScript，Python 版基于 Poetry 构建，均包含完善的测试用例和工程化配置（如 pre-commit、jest、Makefile）。
安装
- 在系统上安装poppler，路径变量里应该有它。请参阅pdf2image文档，了解按平台划分的说明。
- 安装py-zerox：
pip install py-zerox
该功能是一个异步API，通过视觉模型进行光学字符识别（OCR）以进行标记。它会处理PDF文件并将其转换为markdown格式。使用该 API 前，务必设置模型和模型提供者的环境变量。pyzerox.zerox
请参阅LiteLLM文档以设置环境并传递正确的模型名称。