DEV Community

Luming
Luming

Posted on Originally published at somark.ai

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

#ai #tutorial #opensource #ocr

how to use OXR

From your first parsed document to running OXR on your own GPU.

Summary

  • Start with the free API: parse your own documents with one command. No GPU, signup, or API key needed. Prefer to look first? The online demo shows the result in your browser.
  • What you get: OXR turns PDFs and document images into Agent-Friendly data in Markdown or JSON, with layout analysis results, using an open-source model with 1.3B parameters.
  • Easy to integrate: OXR's API is compatible with SoMark's, so you can call it with SoMark's official Python and JavaScript SDK and CLI. The same code works with the free API and your own deployment, and switching is a base URL change.
  • Self-host when you need it: keep documents in your own environment, control concurrency, or swap in your own layout model.

Give OXR a PDF or a document image, and you get back structured output your Agent or RAG pipeline can use directly: Markdown or JSON, along with the layout of the page and the order in which it should be read. The first two paths below need no GPU, no account, and no API key. Pick the one that fits:

Path Best for What you need
Free API Testing OXR on your own documents One command, no signup or API key
Online demo Seeing what OXR does before writing any code A browser
Self-hosting Keeping data in your environment, controlling throughput, or customizing layout analysis A Linux machine with an NVIDIA GPU

Start with the free API

OXR provides a free API so you can test parsing on your own documents without registering or requesting an API key. It works with SoMark's official CLI, so it takes two steps.

1. Install the CLI

# using Python
pip install somark

# or using JavaScript
npm install -g somark-js
Enter fullscreen mode Exit fullscreen mode

2. Parse your 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 just a placeholder; You don't need a real API key.

What you get back

We ran the command above on a two-column page from an academic paper, with a figure, body text, and a table. It took about 20 seconds, and parsed-output/ now holds 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.

Addresses and limits

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 domain of somark.ai. Choose the domain that works best for your region.
  • We'll keep the API free until our servers can no longer handle the load.
  • ⚠️ We do not recommend using the Free OXR API in production. We do not guarantee service stability, and requests are queued, so processing speed may vary slightly. For production, self-host OXR.

Prefer to look first? Try the online demo

Open the online demo, upload a PDF or an image, and look at the parsed result next to the original page: the Markdown preview, the layout boxes, and the reading order. It's the fastest way to see how OXR handles a document you know well.

Plug OXR into your app

OXR's document parsing API is compatible with SoMark's official document parsing API. That means you can reuse SoMark's Python and JavaScript SDKs and CLI, and move between the free API and your own deployment by changing one value: the base URL. You don't have to rewrite your calling code.

SoMark provides a full set of CLI and SDK tools for document parsing in Python and JavaScript. For more information, see https://docs.somark.ai/en/cli-sdk. SoMark's ecosystem fully supports deployed OXR services, but OXR does not support some of SoMark's specialized capabilities. You may see a warning that some SoMark-only options (image understanding, inline images, table images) are accepted but ignored. Open-source OXR only implements keep_header_footer, and the warning is harmless.

If you'd rather send a parsing request to the HTTP API directly, these are the endpoints, relative to the base URL. Output formats are set per request with the output_formats field:

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

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.

Self-host when you need it

The free API is enough to evaluate OXR. Run it locally when you need any of these:

  • Your documents stay in your environment. Parsing runs on your own hardware.
  • You control concurrency and throughput. Tune OXR to your hardware and workload.
  • You can swap in your own layout model. OXR's layout analysis is a pluggable module, so you can keep OXR's recognition and reading order while using a layout model that matches your business rules.

What you need: a Linux operating system and an NVIDIA GPU with BF16 support, with a driver compatible with CUDA 13.0. 24GB of GPU memory on a single GPU is enough for low-concurrency testing; 48GB or more is recommended for long documents and higher concurrency. Running with Docker also requires Docker and the NVIDIA Container Toolkit.

1. Download the code and model weights

Model Download links Precision Includes a lightweight layout analysis model?
OXR-1.0 🤗 Hugging Face / 🤖 ModelScope BF16 Yes, 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

2. Start everything with Docker

We recommend Docker to configure and start 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

Once the startup logs show that the services are ready, open http://localhost:8000/demo or http://localhost:8000/docs. The first startup may take longer. 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. One thing to know there: the official vLLM release does not yet support OXR inference, so we ship an out-of-tree plugin and a loading script in the model weights folder on Hugging Face. No recompilation is needed. You can use the plugin directly with the official vLLM Docker image or CLI.

3. Open the visual demo

Open http://localhost:8000/demo and upload a PDF or image. You can view the original file, Markdown preview, Markdown source, layout bounding boxes, and reading order, and download the Markdown.

The interactive API documentation is at http://localhost:8000/docs. The demo uses a temporary file cache that expires after 1 hour by default and is renewed during processing. Cached results become inaccessible once the cache expires or is cleared, so download your results promptly.

To call your deployment from code, use the same SDK command as before 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

4. Tune for your hardware

The defaults work for most single-GPU setups. If you need to fit OXR into less GPU memory or a specific workload, these are the parameters to adjust:

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.

The number of input tokens plus the maximum output tokens cannot exceed VLLM_MAX_MODEL_LEN. Lowering MAX_TOKENS may truncate long text or tables.

Example startup with limited concurrency and CUDA Graph turned 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 developed a range of tools for document parsing. If you find them helpful, please give them a ⭐ Star.

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

What's next

From parsing your first document to integrating OXR into your own application, you can start small and go deeper step by step. Bring real-world documents from your daily work and see how OXR handles text, tables, and complex layouts.

If something doesn't parse the way you expect, please share it through our feedback form. You can also bring feedback and new use cases to GitHub. We'd like OXR to become a practical, easy-to-use document parsing tool in more real-world scenarios, and your documents are how we get there.

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.

SoMark is a production-grade document parsing engine for agents, powered by an independent model. It supports more file formats, finer-grained recognition of document elements, and faster processing. It also offers extensive post-processing features, custom development, and model training services for different business needs.

If OXR saves you time, give it a ⭐ on GitHub: https://github.com/SoMarkAI/OXR

Top comments (0)