Summary
Find out whether OXR handles your documents with one command, no GPU, signup, or API key. When you're ready to self-host, the same code works after changing one URL.
The best test of a document parser is your own documents. With OXR you can run them before you deploy anything: call the free API with one command, or open the online demo.
OXR is a 1.3B open-source document parsing model from the team behind SoMark, a production-grade document parsing engine for agents. It turns PDFs and document images into Agent-Friendly data, in Markdown or JSON, and ranks #1 on olmOCR-Bench, OmniDocBench, and DocParsingBench. Its API is compatible with SoMark's, so the same SDK and CLI work from the free API to your own server.
This guide goes from a first test to self-hosting: try the free API and the demo, plug OXR into your app, then run it on your own GPU.
Try OXR before you deploy anything
Free API
OXR provides a free API for testing on your own documents, with no registration and no API key. It works with SoMark's official CLI, so it takes two steps. Install the CLI with Python or JavaScript:
# using Python
pip install somark
# or using JavaScript
npm install -g somark-js
Then parse a document:
somark --base-url https://free-oxr.somark.ai/api/v1 --api-key dummy \
parse document.pdf --formats md,json --out ./parsed-output/
Replace document.pdf with the path to your file. dummy is a placeholder, and you don't need a real API key.
We ran the command on a two-column page from an academic paper, with a figure, body text, and a table. It took about 20 seconds and wrote two files:
parsed-output/
├── document.md # the page as Markdown, in reading order
└── document.json # every block with its type, position, and content
Here is an excerpt of document.json, with long values shortened and coordinates rounded:
{
"pages": [{
"page_num": 0,
"page_size": { "w": 1241, "h": 1654 },
"blocks": [
{ "idx": 4, "type": "Text", "bbox": [75, 753, 606, 908],
"content": "For a comparison of the relevance of different research themes ... ‘communication in" },
{ "idx": 5, "type": "Text", "bbox": [636, 487, 1166, 529],
"content": "marketing' (248.8), 'advertising-psychological aspects' (220.5) and 'pricing' (206.3)." },
...
{ "idx": 11, "type": "Table", "bbox": [75, 977, 1169, 1398],
"content": "<table><tr><td>Author</td><td>Papers</td> ...", "format": "html" }
]
}]
}
Block 4 is the bottom of the left column, and block 5 picks up the same sentence at the top of the right column. Blocks come back in reading order, each with its type and position on the page. Tables are returned as HTML, and figures as image links in the Markdown.
| Global | Mirror | |
|---|---|---|
| Base URL | https://free-oxr.somark.ai/api/v1 | https://free-oxr.somark.cn/api/v1 |
| API documentation | https://docs.somark.ai/api-reference | https://docs.somark.cn/api-reference |
somark.cn is a mirror of somark.ai, so use whichever is faster for your region. The API stays free until our servers can no longer handle the load. It isn't meant for production: there is no stability guarantee, and requests are queued, so speed varies. For production, self-host OXR.
Prefer to look first? Try the online demo
Open the online demo, upload a PDF or an image, and compare the result with the original page: the Markdown preview, the layout boxes, and the reading order. There is nothing to install.
Plug OXR into your app
OXR's API is compatible with SoMark's, so SoMark's official Python and JavaScript SDKs and CLI work with OXR. The same code runs against the free API and your own deployment, and you only change the base URL. The SDK and CLI docs cover the details. A few SoMark-only options (image understanding, inline images, table images) are accepted but ignored, because open-source OXR implements only keep_header_footer. If you see a warning about them, it is harmless.
To call the HTTP API directly, use these endpoints, relative to the base URL:
| Endpoint | Purpose |
|---|---|
| POST {base URL}/parse/sync | Upload a file and wait for the result |
| POST {base URL}/parse/async | Submit a file and get a task_id |
| POST {base URL}/parse/async_check | Check the async status and result by task_id |
Output formats are set per request with the output_formats field. For example, against the free API:
curl --fail-with-body https://free-oxr.somark.ai/api/v1/parse/sync \
-F 'file=@document.pdf' \
-F 'api_key=dummy' \
-F 'output_formats=markdown' \
-F 'output_formats=json'
document.pdf can be a local PDF or any document image that OpenCV can decode. To call your own deployment instead, use http://localhost:8000/v1 as the base URL.
Run OXR on your own GPU
The free API is enough to evaluate OXR. Self-host when your documents must stay in your environment, or when you want to tune throughput or swap in your own layout model. Layout analysis is a pluggable module, so you keep OXR's recognition and reading order.
You need Linux and an NVIDIA GPU with BF16 support, with a driver compatible with CUDA 13.0. A single 24GB GPU is enough for low-concurrency testing, and 48GB or more is recommended for long documents and higher concurrency. Running with Docker also requires Docker and the NVIDIA Container Toolkit.
Download the code and weights
The OXR-1.0 weights (BF16) are on Hugging Face and ModelScope. They include a lightweight layout analysis model in the layout_analysis folder.
git clone https://github.com/SoMarkAI/OXR.git
cd OXR
# pip install -U huggingface_hub
hf download SoMarkAI/OXR-1.0 --local-dir ./models/OXR-1.0
# or using ModelScope
# pip install -U modelscope-hub
modelscope download SoMark/OXR-1.0 --local_dir ./models/OXR-1.0
Start with Docker
We recommend Docker, which starts all services together:
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
When the startup logs show that the services are ready, open http://localhost:8000/demo or http://localhost:8000/docs. The first start can take a while, and the default startup timeout is 900 seconds.
Prefer to run the three services (the OXR model, the layout analysis model, and the document parsing API) yourself? Follow "Run from Source" in the OXR README. The official vLLM release does not support OXR inference yet, so we ship an out-of-tree plugin and a loading script in the weights folder on Hugging Face. You can use it directly with the official vLLM Docker image or CLI, with no recompiling.
Check the result and call your server
Open http://localhost:8000/demo and upload a PDF or image. You can view the original file, the Markdown preview and source, the layout boxes, and the reading order, and download the Markdown. Interactive API documentation is at http://localhost:8000/docs. The demo keeps results in a temporary cache for 1 hour by default, renewed while a file is processing, so download what you need.
To call your server from code, use the same CLI command with your local base URL:
somark --base-url http://localhost:8000/v1 --api-key dummy \
parse document.pdf --formats md,json --out ./parsed-output/
Tune for your hardware
The defaults suit most single-GPU setups. To fit OXR into less GPU memory or a specific workload, adjust these parameters:
| Parameter | Default | Description |
|---|---|---|
| VLLM_GPU_MEMORY_UTILIZATION | 0.70 | Fraction of GPU memory budgeted for vLLM, greater than 0 and less than 1. Leave GPU memory for the layout analysis service. |
| VLLM_MAX_MODEL_LEN | 16384 | Context token limit for a single model request, including the image, prompt, and output. |
| OXR_OXR_MODEL_MAX_TOKENS | 8192 | Maximum output tokens for a single region recognition request. Set it together with the context limit. |
| OXR_OXR_MODEL_MAX_CONCURRENCY | 16 | Concurrency limit for model requests shared within the API process, including region recognition and reading order requests. |
| OXR_LAYOUT_ANALYZE_MODEL_BATCH_SIZE | 8 | Number of pages per layout analysis request. |
| OXR_LAYOUT_ANALYZE_MODEL_MAX_CONCURRENCY | 2 | Concurrency limit for layout analysis requests within a single document parsing job. |
| DFINE_CUDA_GRAPH | 1 | CUDA Graph switch for layout analysis. Set it to 0 to turn it off. |
Input tokens plus the maximum output tokens can't exceed VLLM_MAX_MODEL_LEN, and lowering MAX_TOKENS may truncate long text or tables. This example limits concurrency and turns CUDA Graph off:
docker run --rm --gpus all --ipc=host \
-p 127.0.0.1:8000:8000 \
-v "$PWD/models/OXR-1.0:/models/oxr-model:ro" \
-e OXR__OXR_MODEL__MAX_CONCURRENCY=8 \
-e OXR__LAYOUT_ANALYZE_MODEL__BATCH_SIZE=4 \
-e OXR__LAYOUT_ANALYZE_MODEL__MAX_CONCURRENCY=1 \
-e DFINE_CUDA_GRAPH=0 \
-e VLLM_EXTRA_ARGS="--enforce-eager --max-num-batched-tokens 8192" \
oxr-1.0
Tools around OXR
The SoMark team has built a few more tools for document parsing. If they help, a ⭐ is welcome.
| Tool | Description | Project URL |
|---|---|---|
| SoMarkDown | The official Markdown parsing and rendering library for SoMark and OXR | https://github.com/SoMarkAI/SoMarkDown |
| SoMarkDownViewer | A live editing application for SoMarkDown | https://github.com/SoMarkAI/SoMarkDownViewer |
| SoPDF | A high-performance PDF processing library with a permissive open-source license | https://github.com/SoMarkAI/SoPDF |
| Docision | MultiModal Jev for Document. | https://github.com/SoMarkAI/docision |
| somark-py | The official Python SDK & CLI for SoMark and OXR | https://github.com/SoMarkAI/somark-py |
| somark-js | The official JS / TS SDK & CLI for SoMark and OXR | https://github.com/SoMarkAI/somark-js |
Try it on your own documents
Run OXR on the documents you work with every day, including the ones with tables and complex layouts, and tell us where it parses them wrong. Questions, sample pages, and ideas are also welcome on GitHub.
About OXR and SoMark
OXR is a 1.3B open-source document parsing model from the team behind SoMark. It ranks #1 on olmOCR-Bench, OmniDocBench, and DocParsingBench and delivers SOTA parsing speed. The model uses a recursive self-improvement (RSI) loop during post-training.
If OXR saves you time, give it a ⭐ on GitHub: https://github.com/SoMarkAI/OXR




Top comments (0)