efwfe/paddleocr-quality-onnx

PaddleOCR-VL Layer-12 Feature Extractor (ONNX)

Truncated PaddleOCR-VL vision encoder — 1152D intermediate features for document image quality assessment.

Layer 12 of the PaddleOCR-VL vision encoder captures mid-level visual patterns (texture, edge structure, compression artifacts, noise patterns) that are highly predictive of OCR readability. This ONNX model extracts those features with zero PyTorch dependency — just onnxruntime + numpy + Pillow.

Why Layer 12?

From a sensitivity analysis across all 27 encoder layers:

Layer 12 was chosen because:

• —Highest intra/inter-class distance ratio (0.29) — features cluster by quality level, not degradation type
• —Cross-resolution consistency >0.99 — same image at 224² vs 728² produces nearly identical features
• —Good balance: deeper than noise-sensitive layers, shallower than semantic layers

Domain & Positioning: 这个模型做什么、不做什么

一句话定位

这是一个"OCR 场景的文档图片质量特征提取器"，不是通用图片质量打分器，也不是 OCR 识别器。

它的核心假设是：如果一张图在 PaddleOCR-VL 的中间层特征空间里和清晰参考图很接近，那这张图大概率能被 OCR 正确识别。

使用场景

与同类模型的关键区别

1. vs 完整 PaddleOCR-VL（端到端 OCR 模型）

选择指南：如果你需要的是"这张图能读吗"的答案 → 用本模型提取特征 + 轻量回归器。如果你需要"图里写了什么" → 直接用完整 PaddleOCR-VL。

2. vs DINOv3（通用视觉特征提取器）

关键差异：DINOv3 是"通才"，擅长判断"这是什么物体"；本模型是"文档专才"，擅长判断"这文档还能读吗"。在文档质量任务上，本模型的特征 + 轻量回归器（84K 参数）达到 ρ=0.74，优于直接对 DINOv3 特征做 XGBoost。

实测对比（合成文档质量数据集，12 种退化）：

3. vs Qwen3-VL-Embedding / CLIP Embedding（通用 VLM 特征）

核心差异：CLIP/Qwen3-VL 的 embedding 回答"这两张图内容像不像"；本模型的特征回答"这张图和清晰版差多远"。对于文档质量任务，你不想要语义相似度——模糊的身份证和清晰的身份证在语义上是同一张证，但在质量维度上区别巨大。

4. vs Q-ReAlign（通用 VLM 质量评分）

Q-ReAlign 是直接用 VLM 做质量评分的方案（将质量分数映射到离散 token 做软分类）。

选择指南：Q-ReAlign 适合自然照片（"这张风景照好看吗"），不适合文档（"这张扫描件能 OCR 吗"）。

5. vs 传统 CV 质量指标（Laplacian / FFT / Canny）

结论：两者互补。传统 CV 覆盖亮度/对比度（模型的盲区），模型覆盖噪声/压缩（CV 的盲区）。最佳方案是双塔融合：本模型 1152D + CV 6D → 联合回归器。

模型选型速查表

Model Architecture

Input Image (any size)
    │
    ▼
PaddleOCRVLImageProcessor (smart_resize + normalize + patchify)
    │
    ▼
Patch Embedding + Position Encoding
    │
    ▼
Transformer Encoder Layers 0 → 12  ← TRUNCATED HERE (original: 27 layers)
    │
    ▼
Mean Pooling across patches
    │
    ▼
1152-D Feature Vector

Installation

pip install onnxruntime numpy Pillow opencv-python

No PyTorch, no transformers, no CUDA required. CPU inference is ~50-200ms per image.

Quick Start

from inference.onnx_inference import Layer12ONNXExtractor
from PIL import Image, ImageFilter

# Load model
extractor = Layer12ONNXExtractor("model.onnx")

# Extract features
img = Image.open("document.jpg").convert("RGB")
features = extractor.extract(img)  # → np.ndarray shape (1152,)

# Quality via distance from pristine reference
pristine = Image.open("pristine.jpg").convert("RGB")
blurred = img.filter(ImageFilter.GaussianBlur(radius=5))
quality = extractor.quality_score(blurred, reference=pristine)
# → 0.0 (heavily degraded) ~ 1.0 (pristine)

See `inference/example.py` for a complete walkthrough.

Feature Quality Benchmarks

Run with: python benchmark/run_benchmark.py

1. Degradation Sensitivity (Spearman ρ)

Correlation between feature distance and degradation severity across 12 degradation types × 7 levels × 5 image types:

Mean |ρ| = 0.55 across all degradations.

2. Paired Ranking Accuracy

Given a pristine reference and two degraded copies at different severity levels, can the model correctly rank which is worse?

Overall: 89% across 200 random pairs.

3. Cross-Resolution Consistency

Same content at different resolutions → same features? Cosine similarity between features extracted at 224² vs 728²:

Mean: 0.997 — near-perfect consistency thanks to PaddleOCR-VL's smart_resize.

Use Cases

1. 1.Document upload quality gate — reject blurry/noisy scans before OCR
2. 2.Image preprocessing quality monitor — detect when enhancement pipeline degrades
3. 3.Reference-based quality scoring — compare against a known-good template
4. 4.Feature backbone for quality regression — use 1152D features as input to a lightweight quality regressor (e.g., Two-Tower MLP, XGBoost)

Limitations

• —Blind to brightness/contrast issues — these don't affect the feature space. Complement with traditional CV metrics (Laplacian variance, histogram stats).
• —Geometric degradations (rotation) have weak signal — the model uses position encoding, but rotated text still looks like text to mid-layer features.
• —Not a standalone quality scorer — this is a feature extractor. You need a downstream head (trained regressor, reference comparison, or CV complement) for final quality scores.
• —Original PaddleOCR-VL base model — the vision encoder is from PaddleOCR-VL, which is optimized for Chinese + English document OCR.

Recommended Quality Pipeline

For a robust document quality system, use a Two-Tower fusion:

PaddleOCR-VL Layer 12 (this model)     OpenCV traditional metrics
         │                                      │
   PCA → 128D                             6D vector
   Deep Tower MLP                         CV Tower MLP
         │                                      │
         └──────── concat (80D) ───────────────┘
                         │
                   Shared Head
                         │
                  quality_score [0, 1]

This approach achieves ρ = 0.74 on held-out data (vs 0.60 for XGBoost on raw features).

Open-Source Benchmarks for Evaluation

If you want to benchmark your quality model against published work:

Direct: OCR Quality Assessment

General Image Quality Assessment (IQA)

OCR Recognition Benchmarks

Recommended starting point: OCR-Quality — it's the only dataset that directly measures OCR quality assessment, with human annotations and per-page MOS scores. Our benchmark script includes a loader for it.

Files

paddleocr-quality-onnx/
├── README.md                        # This file
├── .gitattributes                   # HF LFS config
├── requirements.txt                 # Python dependencies
├── model.onnx           # ONNX model (~0.8 MB)
├── inference/
│   ├── __init__.py
│   ├── preprocessing.py             # Standalone image preprocessing (no torch)
│   ├── onnx_inference.py            # Layer12ONNXExtractor class
│   └── example.py                   # Complete usage example
└── benchmark/
    ├── run_benchmark.py             # Degradation sensitivity, ranking, resolution
    └── results/                     # Benchmark output

Citation

If you use this model in your research:

@software{paddleocr-quality-onnx,
  title = {PaddleOCR-VL Layer-12 Feature Extractor (ONNX)},
  year = {2025},
  note = {Truncated PaddleOCR-VL vision encoder for document image quality assessment},
  url = {https://huggingface.co/[your-username]/paddleocr-quality-onnx},
}

The original PaddleOCR-VL model is from PaddlePaddle. This is a derived work using only the vision encoder (layers 0-12), exported to ONNX for lightweight deployment.

License

This model is derived from PaddleOCR-VL, which is released under Apache 2.0. This ONNX export and accompanying code are also Apache 2.0.