DEV Community

Luming
Luming

Posted on Edited on Originally published at somark.ai

How to use OXR: From the free API to self-hosting

How to use OXR: From Free API to Self-Hosting

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
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

Replace document.pdf with the path to your file. dummy is a placeholder, and you don't need a real API key.

Animated OXR parsing example

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
Enter fullscreen mode Exit fullscreen mode

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" }
    ]
  }]
}
Enter fullscreen mode Exit fullscreen mode

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.

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

The OXR online demo after uploading a document: the original page with layout boxes on the left, and the parsed Markdown preview on the right.

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'
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

The OXR online demo before a file is uploaded: drop a PDF or image on the page, and the parsed result appears on the right.

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/
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)