# DeepSeek-OCR
DeepSeek-OCR is DeepSeek's 3B mixture-of-experts model for documents. LibreYOLO runs DeepSeek-OCR and DeepSeek-OCR-2 on the ocr task through a vendored PyTorch port: text lines with boxes, layout blocks, or the whole page as markdown.
Tasks: OCR. Install: pip install "libreyolo[vlm]".
Verified against LibreYOLO v1.8.0.

## Install

DeepSeek-OCR belongs to LibreYOLO's VLM tier and needs the `vlm` extra.

```bash
pip install "libreyolo[vlm]"
```

## Predict

Weights download on first use from byte-identical LibreYOLO mirrors,
`LibreYOLO/LibreDeepSeekOCR1` and `LibreYOLO/LibreDeepSeekOCR2`, pinned to a
revision. The architecture is a PyTorch port of the release's inference path;
no remote code runs.

**Python**

```python
from libreyolo import LibreVLM

model = LibreVLM("deepseek-ocr")      # weights download on first use
result = model.predict("page.png")     # a scanned or rendered page

for text, quad in zip(result.ocr.texts, result.ocr.polygons):
    print(text, quad.tolist())         # one region per text line
```

**Markdown**

```python
from libreyolo import LibreVLM

model = LibreVLM("deepseek-ocr", prompt="markdown")
result = model.predict("page.png")

print(result.ocr.markdown)             # the whole page as markdown
print(result.ocr.labels)               # layout category per block
```

**DeepSeek-OCR-2**

```python
from libreyolo import LibreVLM

model = LibreVLM("deepseek-ocr-2")     # resolution "gundam" or "base"
result = model.predict("page.png")
print(result.ocr.texts)
```

The family loads through `LibreVLM()`, or the `LibreDeepSeekOCR` class. The
`prompt` setting (constructor or `set_prompt()`) picks what lands in
`Results.ocr`:

| `prompt` | `Results.ocr` |
| --- | --- |
| `"ocr"` (default) | one region per text line, `labels` all `text`, `markdown` empty |
| `"markdown"` | one region per layout block, the layout category in `labels`, the page in `markdown` |
| `"free"` | no regions, the page text in `markdown` |
| any other string | whatever grounding the model emits, plus `markdown` |

Boxes come on the model's 0 to 999 grid and are scaled to the original image
as axis-aligned 4-point quads, sorted top to bottom then left to right. A
generative model emits no score, so `conf` and `det_conf` are a constant 1.0.
`model.chat("page.png", "Parse the figure.")` returns raw generated text for
any prompt. Decoding is greedy, up to 8192 new tokens, with
`no_repeat_ngram_size=20` as in the release.

## Variants

| Name | Model | Resolutions | License |
| --- | --- | --- | --- |
| `deepseek-ocr` | DeepSeek-OCR (size `1`) | `tiny` (512), `small` (640), `base` (1024), `large` (1280), `gundam` (default) | MIT |
| `deepseek-ocr-2` | DeepSeek-OCR-2 (size `2`) | `base` (1024), `gundam` (default) | Apache-2.0 |

`gundam` combines a 1024 px global view with local crops: 2 to 9 crops of
640 px on DeepSeek-OCR, up to 6 crops of 768 px on DeepSeek-OCR-2. DeepSeek-OCR-2
keeps the decoder and the SAM stage and replaces CLIP with a Qwen2 encoder;
prompts and outputs are the same.

CUDA runs the bf16 weights under `torch.autocast`, as the release does (fp16
on GPUs without bf16). CPU and MPS run float32 with eager attention, about
13 GB of memory; MPS has not been run on hardware. EXIF orientation is not
applied. On an RTX 3090 the port reproduces the release token for token on
17 cases for DeepSeek-OCR and 14 for DeepSeek-OCR-2. Benchmark numbers are in
the release papers and are not reproduced by LibreYOLO.

## Validate

`val()` runs the shared OCR validator and reports detection hmean,
end-to-end F1 and 1-NED.

**Python**

```python
from libreyolo import LibreVLM

model = LibreVLM("deepseek-ocr")
metrics = model.val(data="ocr_dataset/")   # det hmean, end-to-end F1, 1-NED
```

## Export

Inference only: `train()` and `export()` raise.

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: DeepSeek-OCR, DeepSeek
- Upstream license: MIT (size 1); Apache-2.0 (size 2)
- Upstream source: https://github.com/deepseek-ai/DeepSeek-OCR
- LibreYOLO code: MIT (DeepSeek-OCR); Apache-2.0 (DeepSeek-OCR 2)
- Weights: MIT (size 1); Apache-2.0 (size 2), republished at https://huggingface.co/LibreYOLO
- Interpretation: This family covers two releases with different permissive licences. Size "1" is DeepSeek-OCR (paper arXiv:2510.18234), released under MIT: commercial and closed-source use is allowed if you keep the copyright and license notice. Size "2" is DeepSeek-OCR 2 (paper arXiv:2601.20552, 'Visual Causal Flow'), released under Apache-2.0: commercial use is allowed if you keep the license text and notices, and it grants a patent license. LibreYOLO ports the inference path of the Hugging Face releases (deepseek-ai/DeepSeek-OCR at 9f30c71f441d010e5429c532364a86705536c53a and deepseek-ai/DeepSeek-OCR-2 at aaa02f3811945a91062062994c5c4a3f4c0af2b0) and runs none of their remote code; ported parts keep their lineage, Apache-2.0 for the DeepSeek-V2 decoder, the Transformers Llama and Qwen2 attention, the detectron2-derived SAM encoder and the FastChat template, MIT for the ConvNeXt LayerNorm (libreyolo/models/deepseekocr/NOTICE), while the adapter is MIT. Weights are byte-identical, ungated mirrors at LibreYOLO/LibreDeepSeekOCR1 and LibreYOLO/LibreDeepSeekOCR2 with no learned parameter changed.

DeepSeek-OCR is MIT and DeepSeek-OCR-2 is Apache-2.0, code and weights, both
by [DeepSeek](https://github.com/deepseek-ai/DeepSeek-OCR). Both allow
commercial use. The weights are byte-identical, ungated mirrors.

## Citation

```bibtex
@article{wei2025deepseek,
  title={DeepSeek-OCR: Contexts Optical Compression},
  author={Wei, Haoran and Sun, Yaofeng and Li, Yukun},
  journal={arXiv preprint arXiv:2510.18234},
  year={2025}
}
```

Copied from https://huggingface.co/deepseek-ai/DeepSeek-OCR#citation
