PaddleOCR-VL-MLX

PaddleOCR-VL MLX - Apple Silicon Native OCR Model

🚀 World's First MLX-Native Implementation of PaddleOCR-VL

This is a high-performance MLX conversion of PaddlePaddle/PaddleOCR-VL, optimized for Apple Silicon (M1/M2/M3/M4) chips. It delivers native NPU acceleration for optical character recognition tasks.

🌟 Highlights

• ✅ 100% MLX Native: Fully converted from PyTorch to MLX framework
• ⚡ NPU Accelerated: Leverages Apple Neural Engine for maximum performance
• 🎯 Production Ready: Successfully tested on M4 Max with 128GB RAM
• 📦 Lightweight: Optimized weight format for faster loading
• 🔧 Easy Integration: Drop-in replacement for the original model

📊 Performance Benchmarks

Tested on 384x384 images with default settings

🚀 Quick Start

Installation

pip install mlx transformers pillow

Basic Usage

import mlx.core as mx
from PIL import Image
from transformers import AutoTokenizer
from modeling_paddleocr_vl import PaddleOCRVLForConditionalGeneration

# Load model and tokenizer
model = PaddleOCRVLForConditionalGeneration.from_pretrained(
    "gamhtoi/PaddleOCR-VL-MLX",
    trust_remote_code=True
)
tokenizer = AutoTokenizer.from_pretrained(
    "gamhtoi/PaddleOCR-VL-MLX",
    trust_remote_code=True
)

# Load and process image
image = Image.open("document.jpg")
inputs = tokenizer(
    text="OCR:",
    images=image,
    return_tensors="np"
)

# Convert to MLX arrays
input_ids = mx.array(inputs['input_ids'])
pixel_values = mx.array(inputs['pixel_values'])

# Generate OCR result
outputs = model.generate(
    input_ids=input_ids,
    pixel_values=pixel_values,
    max_new_tokens=512
)

# Decode result
result = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(result)

Advanced Usage with Streaming

# For real-time OCR with progress tracking
def ocr_with_progress(image_path, prompt="OCR:"):
    image = Image.open(image_path)
    inputs = tokenizer(text=prompt, images=image, return_tensors="np")
    
    input_ids = mx.array(inputs['input_ids'])
    pixel_values = mx.array(inputs['pixel_values'])
    
    # Stream generation
    for token in model.generate_stream(
        input_ids=input_ids,
        pixel_values=pixel_values,
        max_new_tokens=1024
    ):
        yield tokenizer.decode(token, skip_special_tokens=True)

# Usage
for partial_result in ocr_with_progress("complex_document.pdf"):
    print(partial_result, end='', flush=True)

🏗️ Architecture

This model consists of:

• Vision Encoder: 27-layer ViT with spatial merging (1152 hidden dim)
• Language Model: 18-layer decoder with GQA (1024 hidden dim)
• 3D RoPE: Advanced rotary position embeddings for multi-modal fusion

Key features:

• Multi-resolution image processing (up to 384x384)
• Grouped Query Attention (16 heads, 2 KV heads)
• Optimized for document understanding and OCR tasks

📁 Model Files

• model-00001-of-00002.safetensors: Vision encoder weights
• model-00002-of-00002.safetensors: Language model weights
• modeling_paddleocr_vl.py: MLX implementation
• configuration_paddleocr_vl.py: Model configuration
• tokenizer.json: Fast tokenizer
• config.json: Model metadata

🔧 Technical Details

Conversion Process

This model was converted from PyTorch to MLX using a custom conversion pipeline:

1. Weight Extraction: Extracted from original safetensors format
2. Architecture Mapping: Rebuilt all layers using MLX primitives
3. Numerical Validation: Verified output consistency with original model
4. Optimization: Applied MLX-specific optimizations for Apple Silicon

Key Differences from Original

• Native MLX operations (no PyTorch dependency)
• Optimized memory layout for Metal GPU
• Streamlined inference pipeline
• Better integration with Apple's Neural Engine

🎯 Use Cases

• Document Digitization: Convert scanned documents to editable text
• Receipt/Invoice Processing: Extract structured data from receipts
• Academic Paper OCR: Preserve formatting and equations
• Multi-language Support: Handles Chinese, English, and mixed text
• Real-time Translation: Combine with translation models for instant document translation

🛠️ Requirements

• Hardware: Apple Silicon (M1/M2/M3/M4)
• OS: macOS 12.0+
• Python: 3.9+
• Dependencies:
  • mlx >= 0.4.0
  • transformers >= 4.40.0
  • Pillow >= 10.0.0

📚 Citation

If you use this model in your research, please cite:

@misc{paddleocr-vl-mlx-2024,
  author = {gamhtoi},
  title = {PaddleOCR-VL MLX: Apple Silicon Native OCR},
  year = {2024},
  publisher = {Hugging Face},
  howpublished = {\url{https://huggingface.co/gamhtoi/PaddleOCR-VL-MLX}}
}

@article{paddleocr-vl-2024,
  title={PaddleOCR-VL: A Vision-Language Model for Optical Character Recognition},
  author={PaddlePaddle Team},
  year={2024}
}

🤝 Acknowledgments

• Original model by PaddlePaddle Team
• MLX framework by Apple ML Research
• Conversion and optimization by gamhtoi

📄 License

This model inherits the license from the original PaddleOCR-VL model. Please refer to the original repository for license details.

🐛 Issues & Contributions

Found a bug or want to contribute? Please open an issue or PR on the GitHub repository.

🔗 Related Models

• Hunyuan-MT-Chimera-7B-MLX-Q8: Translation model optimized for MLX
• PaddleOCR-VL (Original): PyTorch version

---

Made with ❤️ for the Apple Silicon community