Skip to content

README.md

Latest commit

 

History

History
185 lines (130 loc) · 5.53 KB

README.md

File metadata and controls

185 lines (130 loc) · 5.53 KB

Docker Development Environments

Pre-configured Docker images for developing and testing RapidOCR with each supported inference engine.

Prerequisites

Available Images

Image Engine Base Image GPU Required
onnxruntime-cpu ONNX Runtime (CPU) python:3.10-slim-bookworm No
onnxruntime-gpu ONNX Runtime (CUDA) nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04 Yes
tensorrt NVIDIA TensorRT nvcr.io/nvidia/deepstream:7.0-gc-triton-devel Yes
paddle PaddlePaddle (CPU) python:3.10-slim-bookworm No
openvino Intel OpenVINO python:3.10-slim-bookworm No
pytorch PyTorch (CPU) python:3.10-slim-bookworm No
mnn MNN python:3.10-slim-bookworm No

Quick Start

All commands run from the repository root.

Build an image

make build-onnxruntime-cpu

Run tests

make test-onnxruntime-cpu

Open an interactive shell

make shell-onnxruntime-cpu

Build all images

make build-all

Clean up

make clean

Using docker compose directly

# Build
docker compose -f docker/docker-compose.yaml build onnxruntime-cpu

# Run tests
docker compose -f docker/docker-compose.yaml run --rm onnxruntime-cpu pytest tests/ -v

# Run a single test
docker compose -f docker/docker-compose.yaml run --rm onnxruntime-cpu pytest tests/test_engine.py -k "onnxruntime" -v

# Interactive shell
docker compose -f docker/docker-compose.yaml run --rm onnxruntime-cpu bash

GPU Images

GPU images (onnxruntime-gpu, tensorrt) require the NVIDIA Container Toolkit and a compatible NVIDIA GPU.

Verify your GPU is accessible:

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Then build and use GPU images normally:

make build-tensorrt
make test-tensorrt
make shell-tensorrt

Note: TensorRT builds optimized engine files from ONNX models on first run. This takes several minutes per model. Subsequent runs use cached engines from the persistent model volume.

How It Works

Source Code Mounting

Your local python/ directory is bind-mounted into the container at /app. Any code changes you make on the host are immediately reflected inside the container — no rebuild needed.

Model Caching

A shared Docker volume (rapidocr-models) is mounted at /app/rapidocr/models/. Models are automatically downloaded on first use and cached in this volume. The cache persists across container rebuilds, so models are only downloaded once.

To clear the model cache:

docker volume rm rapidocr-models

Architecture

docker/
├── Dockerfile.base              # Shared base: Python 3.10, system deps, core pip packages
├── Dockerfile.onnxruntime-cpu   # extends base + onnxruntime
├── Dockerfile.onnxruntime-gpu   # standalone CUDA image + onnxruntime-gpu
├── Dockerfile.tensorrt          # standalone DeepStream image + tensorrt + cuda-python
├── Dockerfile.paddle            # extends base + paddlepaddle
├── Dockerfile.openvino          # extends base + openvino
├── Dockerfile.pytorch           # extends base + torch
├── Dockerfile.mnn               # extends base + MNN
├── docker-compose.yaml          # Service definitions, volumes, GPU reservations
└── .dockerignore                # Excludes .git, models, build artifacts
Makefile                         # Convenience targets (repo root)

CPU images extend Dockerfile.base. GPU images (onnxruntime-gpu, tensorrt) use NVIDIA base images and replicate the base setup because they need CUDA pre-installed.

Examples

Run OCR from the command line

make shell-onnxruntime-cpu
# Inside container:
python -c "
from rapidocr import RapidOCR
engine = RapidOCR()
result = engine('tests/test_files/ch_en_num.jpg')
print(result)
"

Run with a specific engine

make shell-pytorch
# Inside container:
python -c "
from rapidocr import RapidOCR, EngineType
engine = RapidOCR(params={
    'Det.engine_type': EngineType.TORCH,
    'Cls.engine_type': EngineType.TORCH,
    'Rec.engine_type': EngineType.TORCH,
})
result = engine('tests/test_files/ch_en_num.jpg')
print(result)
"

Run a specific test file

docker compose -f docker/docker-compose.yaml run --rm onnxruntime-cpu \
    pytest tests/test_engine.py::test_ppocrv5_rec_mobile -v

Troubleshooting

docker compose command not found

Ensure you have Docker Compose v2 installed. On older systems, the command may be docker-compose (with hyphen) instead of docker compose (with space).

GPU not detected inside container

  1. Verify the NVIDIA driver: nvidia-smi
  2. Verify the container toolkit: docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
  3. If using Docker Desktop, enable GPU support in Settings > Resources > GPU.

TensorRT CUDA initialization failure with error: 35

This means the TensorRT or CUDA Python version doesn't match your host driver. The Dockerfile pins tensorrt>=8.6,<8.7 and cuda-python>=12.0,<13.0 for DeepStream 7.0. If your driver is older, you may need to adjust these versions.

Models re-download every time

Ensure the rapidocr-models volume is mounted. Check with docker volume ls | grep rapidocr.