README.md

---
license: apache-2.0
language:
- en
- zh
- ja
- ko
pipeline_tag: image-to-text
tags:
- mlx
- mlx-weights
- paddlepaddle-ocr
- ppocrv5
- ppocrv6
- ppdoclayoutv3
- pp-structure
- apple-silicon
---

# PP-Structure / PP-OCR Models — MLX

This repository is an **[MLX](https://github.com/ml-explore/mlx)** conversion of the
PaddlePaddle **PP-Structure** and **PP-OCR** model families. Every subdirectory holds a
converted MLX weights file (`model.mlx.safetensors`) alongside the original source weights
and configs, so the models can run natively and efficiently on Apple Silicon (M-series).

The models are converted from the official PaddlePaddle / Hugging Face
[`transformers`](https://github.com/huggingface/transformers) safetensors checkpoints. They
cover the full document-intelligence pipeline: layout analysis, text detection &
recognition, orientation & rectification, table recognition, and formula recognition.

> See each subdirectory's own `README.md` for model-specific details, accuracy metrics, and
> the original PaddlePaddle usage examples.

## Repository layout

Models are grouped by pipeline stage. Below, `↳` links each folder to its source model.

### Document layout analysis

| Folder | Model | Description |
| --- | --- | --- |
| [`doclayoutv3/`](./doclayoutv3) | PP-DocLayoutV3 | RT-DETR-style detector (HGNetV2-L backbone) for 25 document layout regions (title, text, figure, table, formula, …). |

### Text detection (PP-OCRv5 / v6)

| Folder | Model | Description |
| --- | --- | --- |
| [`det/`](./det) | PP-OCRv5_mobile_det | Legacy mobile text-line detector (LCNetV3 backbone, scale 0.75). |
| [`det_v6_medium/`](./det_v6_medium) | PP-OCRv6_medium_det | Largest v6 detector — LCNetV4 backbone + RepLKFPN neck, 15.5M params. |
| [`det_v6_small/`](./det_v6_small) | PP-OCRv6_small_det | Mid-tier v6 detector, 2.48M params. |
| [`det_v6_tiny/`](./det_v6_tiny) | PP-OCRv6_tiny_det | Smallest v6 detector, 0.43M params. |

### Text recognition (PP-OCRv5 / v6)

| Folder | Model | Description |
| --- | --- | --- |
| [`rec/`](./rec) | PP-OCRv5_mobile_rec | Legacy mobile recognizer (LCNetV3 backbone). |
| [`en_rec/`](./en_rec) | PP-OCRv5_mobile_rec (EN) | English-dictionary variant of the mobile recognizer. |
| [`server_rec/`](./server_rec) | PP-OCRv5_server_rec | Server-grade recognizer for ZH/EN/JA + handwriting, vertical text, pinyin, rare characters. |
| [`rec_v6_medium/`](./rec_v6_medium) | PP-OCRv6_medium_rec | Largest v6 recognizer — LCNetV4 + EncoderWithLightSVTR, CTC+NRTR heads, 50 languages, 19M params. |
| [`rec_v6_small/`](./rec_v6_small) | PP-OCRv6_small_rec | Mid-tier v6 recognizer, 5.2M params, 50 languages. |
| [`rec_v6_tiny/`](./rec_v6_tiny) | PP-OCRv6_tiny_rec | Smallest v6 recognizer, 1.1M params, 49 languages. |

### Orientation & rectification

| Folder | Model | Description |
| --- | --- | --- |
| [`ori/`](./ori) | PP-LCNet_x1_0_doc_ori | Document image orientation classifier (0°/90°/180°/270°), 99.06% avg accuracy. |
| [`uvdoc/`](./uvdoc) | UVDoc | Document image unwarping / geometric rectification (CER 0.179 on DocUNet benchmark). |

### Table recognition

| Folder | Model | Description |
| --- | --- | --- |
| [`table_cls/`](./table_cls) | PP-LCNet_x1_0_table_cls | Wired vs. wireless table classifier, 94.2% Top-1. |
| [`table_structure/`](./table_structure) | SLANet | Legacy table-structure recognition (LCNet backbone, scale 1). |
| [`table_wired/`](./table_wired) | SLANeXt_wired | Wired-table structure recognition, 69.65% accuracy, 351M. |
| [`table_wireless/`](./table_wireless) | SLANeXt_wireless | Wireless-table structure recognition, 69.65% accuracy, 351M. |
| [`table_cell_wired/`](./table_cell_wired) | RT-DETR-L_wired_table_cell_det | Wired-table cell detector (RT-DETR-L), 82.7% Top-1, 124M. |
| [`table_cell_wireless/`](./table_cell_wireless) | RT-DETR-L_wireless_table_cell_det | Wireless-table cell detector (RT-DETR-L), 82.7% Top-1, 124M. |

### Formula recognition

| Folder | Model | Description |
| --- | --- | --- |
| [`formula/`](./formula) | PP-FormulaNet_plus-L | Encoder-decoder vision-language model that converts formula images to LaTeX (~182M params, 50k-token vocabulary). |

## Pipeline

These modules compose into the standard PP-Structure document pipeline:

```
                ┌────────────┐
   page image → │  doc ori   │  (optional) orient the page
                └─────┬──────┘
                ┌─────▼──────┐
                │  uvdoc     │  (optional) dewarp the page
                └─────┬──────┘
                ┌─────▼──────┐
                │ doclayoutv3│  detect layout regions
                └─────┬──────┘
            ┌─────────┼──────────┐
            ▼         ▼          ▼
       text branch  table      formula
       ┌──────┐   ┌───────┐   ┌───────┐
       │ det  │   │ cls   │   │formula│
       └──┬───┘   └───┬───┘   └───────┘
          │       ┌───┴──────┐
          ▼       ▼          ▼
       ┌────┐  cell det   structure
       │rec │ (wired/     (wired/
       └────┘ wireless)   wireless)
```

For the OCR sub-pipeline, PP-OCRv6 pairs `det_v6_*` with the matching `rec_v6_*` tier
(e.g. `det_v6_medium` + `rec_v6_medium`), selectable across medium / small / tiny for
server-to-edge trade-offs.

## Loading the MLX weights

Each folder follows the same convention — the MLX weights live in `model.mlx.safetensors`
and the architecture in `config.json`:

```
<model>/
├── model.mlx.safetensors   # MLX-converted weights (load with mlx.nn / mlx-vlm)
├── model.safetensors       # original source weights
├── config.json             # architecture config
└── preprocessor_config.json (or processor_config.json)
```

Load with MLX (Python):

```python
import mlx.core as mx
from mlx.utils import tree_unflatten

weights = mx.load("det_v6_medium/model.mlx.safetensors")
params = tree_unflatten(list(weights.items()))
```

> These are weight conversions only. A matching MLX model implementation (e.g. via
> [mlx-vlm](https://github.com/Blaizzy/mlx-vlm) or a custom MLX module) is required to run
> inference. Refer to each subdirectory's `config.json` for the exact architecture.

## Model sources

Original checkpoints and documentation from the
[PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) project and the
[PaddlePaddle](https://huggingface.co/PaddlePaddle) Hugging Face organization.

## License

Apache 2.0. See the [LICENSE](./LICENSE) of the upstream PaddleOCR project for details.