项目介绍
Zerox 把文档页面交给视觉模型解析,常用于转换为 Markdown。它适合复杂页面的结构化提取,使用在线模型时要考虑每页调用成本和文档数据去向。
页面先转换为模型可读取的图像,再通过视觉模型生成结构化文本。每页调用与重试都可能产生费用。
适合复杂版式文档提取。先用无隐私小样本,明确模型和输出要求。
核心功能
| 功能 | 作用与使用方式 |
|---|---|
| 页面转换 | 准备视觉输入 |
| 模型接入 | 选择受支持提供商 |
| Markdown 输出 | 保存可编辑内容 |
| 逐页核对 | 检查表格公式和标题 |
| 批量控制 | 限制并发与费用 |
界面展示

图 1:官方仓库提供的项目示意图,用于说明功能与布局。
项目信息
| 项目 | 说明 |
|---|---|
| 类型 | 项目指南 |
| 分类 | AI 与开发 |
| 项目仓库 | getomni-ai/zerox |
| 整理日期 | 2026-11-14 |
安装与运行
在 Linux、macOS 或 WSL 准备 Python 虚拟环境。Zerox 是文档解析库,调用视觉模型还需要自己配置供应商 API Key;没有独立网页后台。
1. 安装和初始化
python3 -m venv .venv
source .venv/bin/activate
python -m pip install py-zerox
2. 第一次使用
在同一个虚拟环境运行自己的解析脚本,先用一页不含敏感信息的 PDF 测试,再检查表格、换行和页码。JavaScript 项目可在已有项目目录用 npm install zerox 安装另一语言的库,不要把两个包当成同一命令行工具。
PDF 转图依赖需要按所选语言和操作系统准备,Python 方案检查 Poppler 是否可执行。模型服务地址、Key 与模型名必须配套;先设置小批量与并发限制,再处理整本文档。
常见问题
- 命令不存在:确认依赖已安装,关闭并重新打开终端,再检查实际使用的环境。Python 虚拟环境与系统 Python、Windows 与 WSL 的工具路径各自独立。
- 下载依赖失败:先查看具体失败的仓库和包名,检查该终端的网络;浏览器能访问不代表命令行已使用同一代理。
- 配置后仍报错:从当前项目目录启动,检查配置文件名、变量名和日志。真实账号与 API Key 放在本机私有配置中,不复制到公开教程或截图。
更新与备份
更新前保存项目配置、输入资料和输出结果。源码项目记录当前提交与依赖锁文件,比较新版本说明后再更新;安装包项目保留可回退的版本号。服务账号的授权与模型账单在对应平台管理,删除本地目录不会自动撤销授权。