> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OXR

> 了解 OXR 如何将 PDF 和文档图片解析为 Markdown 与带版面坐标的 JSON，以及怎样选择部署方式。

## 什么是 OXR

**OXR（Optical Everything Recognition）** 是 SoMark 团队发布的文档解析模型，参数量为 13 亿，公开提供源码和模型权重。它将 PDF 和文档图片转换成按阅读顺序排列的 Markdown，也能输出包含版面坐标的 JSON。你可以用 Markdown 建立检索索引，用 JSON 定位原页上的文字、表格和公式。

> [card] [GitHub 仓库](https://github.com/SoMarkAI/OXR/blob/main/README_CN.md)
>
> 查看中文 README、源码和解析样例。

> [card] [OXR-1.0 模型](https://huggingface.co/SoMarkAI/OXR-1.0)
>
> 下载 BF16 模型和随附的轻量版面分析权重。

## 如何使用

* **在线试用**。上传 PDF 或图片，对照原页查看 Markdown 和版面框。[打开在线 Demo](https://free-oxr.somark.ai/)
* **Free API**。通过 HTTP API、CLI 或 SDK 提交文件。[查看接入指南](#oxr-free-api)
* **自部署**。在自己的 NVIDIA GPU 服务器上运行模型，通过本地 Web Demo、HTTP API 或 SoMark CLI 提交文件。[查看自部署步骤](#自部署)

## 能解析哪些内容

OXR 定义了 13 类版面元素，覆盖标题、正文、页眉、页脚、脚注、图表说明、图片、表格、数学公式、化学方程式、化学结构式、代码块和印章。默认输出会过滤页眉和页脚。[完整元素和格式表](https://github.com/SoMarkAI/OXR/blob/main/README_CN.md#why-oxr)

| 文档示例 | 你可以得到什么 |
| - | - |
| 学术论文与研究报告 | 按阅读顺序排列的正文，以及表格、脚注和 LaTeX 公式 |
| 化学资料与试卷 | 支持 mhchem 语法的化学方程式，以及 SMILES 或图片形式的化学结构式 |
| 报表与扫描件 | HTML 或 Markdown 表格，以及可用于原页核对的区域坐标 |

## OXR Free API

OXR Free API 提供开源 OXR 模型的免费在线服务。你可以直接上传 PDF 或图片，无需注册或申请 API 密钥。

### 接入信息

| 接入项 | 配置 |
| - | - |
| Base URL | `https://free-oxr.somark.ai/api/v1` |
| 鉴权 | `api_key` 可省略 |
| 文件提交 | 通过 `file` 直接上传文件 |
| 文件格式 | PDF、PNG、JPG、JPEG、BMP、TIF、TIFF、WebP |
| 单次上限 | **10 MB、20 页** |
| 输出格式 | 默认返回 Markdown 和 JSON |
| 请求处理 | 请求排队处理，处理时间可能波动。收到 HTTP `429` 时，等待当前任务完成后重试 |

### 接口列表

同步解析在同一次请求中返回结果。异步解析先返回 `task_id`，再通过查询接口获取进度和结果。

| 接口 | 请求 | 文档 |
| - | - | - |
| 同步解析 | `POST /parse/sync` | [同步解析](https://docs.somark.ai/open-source-tools/oxr/sync.md) |
| 异步提交 | `POST /parse/async` | [提交任务](https://docs.somark.ai/open-source-tools/oxr/async-submit.md) |
| 异步查询 | `POST /parse/async_check` | [查询结果](https://docs.somark.ai/open-source-tools/oxr/async-check.md) |

### 使用 CLI 或 SDK

使用 [SoMark CLI 或 SDK](https://docs.somark.ai/cli-sdk/index.md) 时，将 Base URL 设为上表地址。CLI 的 `--api-key` 可填 `dummy`。

```bash theme={null}
somark --base-url https://free-oxr.somark.ai/api/v1 --api-key dummy \
  parse document.pdf --formats md,json --out ./parsed-output/
```

从 SoMark API 切换时，请参阅 [SoMark与OXR接入差异](https://docs.somark.ai/open-source-tools/oxr/integration)。

## 自部署

在自己的服务器上部署 OXR 后，可以通过本地 Web Demo、HTTP API 或 SoMark CLI 提交文档。

### 准备自部署环境

在 Linux 主机上准备支持 BF16 的 NVIDIA GPU、兼容 CUDA 13.0 的驱动，以及支持 `--gpus all` 的 Docker 环境。官方建议单卡 24 GB 显存用于低并发试用，长文档或较高并发建议单卡 48 GB 或以上。使用 Python 3.12 环境安装模型下载工具。[部署条件与常见问题](https://github.com/SoMarkAI/OXR/blob/main/docs/FAQ_CN.md)

### 下载模型并启动服务

克隆 OXR 仓库并下载完整的 `OXR-1.0` 模型目录。这个目录同时包含识别模型和 `layout_analysis/` 中的版面分析权重。

```bash theme={null}
git clone https://github.com/SoMarkAI/OXR.git
cd OXR
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U huggingface_hub
hf download SoMarkAI/OXR-1.0 --local-dir ./models/OXR-1.0
```

在仓库根目录构建镜像并运行容器。容器会一起启动识别模型、版面模型和文档解析 API。

```bash theme={null}
docker build -f docker/Dockerfile.allinone -t oxr-1.0 .
docker run --rm --gpus all --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$PWD/models/OXR-1.0:/models/oxr-model:ro" \
  oxr-1.0
```

等待日志显示服务就绪。在部署主机上打开 `http://localhost:8000/demo` 体验解析，或打开 `http://localhost:8000/docs` 查看接口。示例将端口绑定到部署主机的回环地址。

### 调用自部署的解析接口

将 `document.pdf` 放在终端当前目录，用以下命令向本机服务提交同步解析请求。两个 `output_formats` 字段分别请求 Markdown 和 JSON。

```bash theme={null}
curl --fail-with-body http://localhost:8000/v1/parse/sync \
  -F 'file=@document.pdf' \
  -F 'api_key=dummy' \
  -F 'output_formats=markdown' \
  -F 'output_formats=json'
```

当响应的 `code` 为 `0` 时，从 `data.result.outputs.markdown` 读取 Markdown，从 `data.result.outputs.json` 读取带版面信息的 JSON。

如果希望把输出直接保存到文件，可使用 SoMark CLI。把 **Base URL** 指向本机服务的 `/v1`，并用 `md,json` 选择输出格式。

```bash theme={null}
python -m pip install somark

somark --base-url http://localhost:8000/v1 --api-key dummy \
  parse document.pdf --formats md,json --out ./parsed-output/
```

使用 Markdown 阅读和检索内容，使用 JSON 中的元素类型与 `bbox` 坐标定位原页区域。接入应用时，先查看 OXR 支持的接口和参数。[SoMark与OXR接入差异](https://docs.somark.ai/open-source-tools/oxr/integration)

### 从源码启动

如果你要分别部署识别和版面模型，按仓库说明先启动两个模型服务，再将各自地址填入文档解析服务的配置文件。[官方源码部署步骤](https://github.com/SoMarkAI/OXR/blob/main/README_CN.md#122-源码启动)

## 公开评测

![OXR-1.0 在 OmniDocBench、olmOCR-bench 和 DocParsingBench 的总体得分榜单](https://mintcdn.com/soulcode-9c5983db/-0FjCS9t0Ocp6dgn/images/oxr/benchmark-leaderboards.png?fit=max\&auto=format\&n=-0FjCS9t0Ocp6dgn\&q=85\&s=d4f0ec91ca438f51608aabb12cf703cc)

在 2026 年 10 月 5 日的对比快照中，OXR-1.0 在 `OmniDocBench`、`olmOCR-bench` 和 `DocParsingBench` 的总体得分分别为 **97.18**、**87.84** 和 **87.76**，在各自列出的模型中排名第一。[官网榜单](https://somark.ai/oxr#benchmark)

项目还在一张 96 GB NVIDIA RTX PRO 6000 Blackwell 上测试了固定的 100 页 OmniDocBench 样本。OXR 的端到端吞吐量约为 **0.99 页/秒**，包含版面分析、内容识别和阅读顺序处理。[评测条件与完整结果](https://github.com/SoMarkAI/OXR/blob/main/docs/benchmark.md)

OXR 采用基于 Apache 2.0 的 OXR 许可证，并附加商业授权及署名条款。[许可证全文](https://github.com/SoMarkAI/OXR/blob/main/LICENSE)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.