π Awesome OCR multiple programing languages toolkits based on ONNX Runtime, OpenVINO, MNN, PaddlePaddle, TensorRT and PyTorch.
feat(docker): add per-engine Docker dev environments (#649)
locviettri1f78b76eb470
diff --git a/Makefile b/Makefilenew file mode 100644index 0000000..77be62f--- /dev/null+++ b/Makefile@@ -0,0 +1,37 @@+# RapidOCR Docker Dev Environments+COMPOSE_FILE := docker/docker-compose.yaml+ENGINES := onnxruntime-cpu onnxruntime-gpu tensorrt paddle openvino pytorch mnn++.PHONY: help build-all clean $(foreach e,$(ENGINES),build-$(e) test-$(e) shell-$(e))++help:+ @echo "RapidOCR Docker Dev Environments"+ @echo ""+ @echo "Usage:"+ @echo " make build-{engine} Build a dev image"+ @echo " make test-{engine} Run tests in container"+ @echo " make shell-{engine} Open bash shell in container"+ @echo " make build-all Build all images"+ @echo " make clean Remove all containers and images"+ @echo ""+ @echo "Engines: $(ENGINES)"+ @echo ""+ @echo "Examples:"+ @echo " make build-tensorrt"+ @echo " make test-onnxruntime-cpu"+ @echo " make shell-pytorch"++build-%:+ docker compose -f $(COMPOSE_FILE) build $*++test-%:+ docker compose -f $(COMPOSE_FILE) run --rm $* pytest tests/ -v++shell-%:+ docker compose -f $(COMPOSE_FILE) run --rm $* bash++build-all:+ docker compose -f $(COMPOSE_FILE) build++clean:+ docker compose -f $(COMPOSE_FILE) down --rmi local --volumesdiff --git a/README.md b/README.mdindex 8895269..5809836 100755--- a/README.md+++ b/README.md@@ -71,6 +71,22 @@ print(result)result.vis("vis_result.jpg")```+### π³ Docker++Docker development environments are available for all supported inference engines:++```bash+# Build and test with ONNX Runtime (CPU)+make build-onnxruntime-cpu+make test-onnxruntime-cpu++# Or use any engine: onnxruntime-gpu, tensorrt, paddle, openvino, pytorch, mnn+make build-tensorrt+make shell-tensorrt+```++See [docker/README.md](./docker/README.md) for full setup instructions, GPU configuration, and troubleshooting.+### π DocumentationFull documentation can be found on [docs](https://rapidai.github.io/RapidOCRDocs/), in Chinese.diff --git a/docker/.dockerignore b/docker/.dockerignorenew file mode 100644index 0000000..8b3de09--- /dev/null+++ b/docker/.dockerignore@@ -0,0 +1,20 @@+.git+__pycache__+*.pyc+*.pyo+*.egg-info+dist/+build/+.tox/+.pytest_cache/+.mypy_cache/+python/rapidocr/models/+python/benchmark_*+python/pred.txt+python/merged_benchmark_report_*+python/tensorrt_build_logs_*+python/validate_benchmark_*+python/generate_merged_report.py+python/mnn_benchmark_reference.md+*.engine+.mcp.jsondiff --git a/docker/Dockerfile.base b/docker/Dockerfile.basenew file mode 100644index 0000000..f4b658c--- /dev/null+++ b/docker/Dockerfile.base@@ -0,0 +1,35 @@+FROM python:3.10-slim-bookworm++ENV DEBIAN_FRONTEND=noninteractive+ENV PYTHONDONTWRITEBYTECODE=1+ENV PYTHONUNBUFFERED=1+ENV PYTHONPATH=/app++WORKDIR /app++# System dependencies for opencv, pyclipper, shapely C extensions+RUN apt-get update && apt-get install -y --no-install-recommends \+ libgl1 \+ libglib2.0-0 \+ libsm6 \+ libxext6 \+ libxrender1 \+ gcc \+ g++ \+ && rm -rf /var/lib/apt/lists/*++# Copy only requirements first for layer caching+COPY python/requirements.txt /tmp/requirements.txt++# Install core deps with opencv-headless (no GUI needed in container)+RUN pip install --no-cache-dir --upgrade pip && \+ pip install --no-cache-dir -r /tmp/requirements.txt && \+ pip uninstall -y opencv-python 2>/dev/null; \+ pip install --no-cache-dir opencv-python-headless && \+ pip install --no-cache-dir pytest && \+ rm /tmp/requirements.txt++# Copy source (bind-mounted at runtime for live editing via docker-compose)+COPY python/ /app/++CMD ["bash"]diff --git a/docker/Dockerfile.mnn b/docker/Dockerfile.mnnnew file mode 100644index 0000000..68ce284--- /dev/null+++ b/docker/Dockerfile.mnn@@ -0,0 +1,5 @@+FROM rapidocr-base:latest++RUN pip install --no-cache-dir MNN++CMD ["bash"]diff --git a/docker/Dockerfile.onnxruntime-cpu b/docker/Dockerfile.onnxruntime-cpunew file mode 100644index 0000000..30b1179--- /dev/null+++ b/docker/Dockerfile.onnxruntime-cpu@@ -0,0 +1,5 @@+FROM rapidocr-base:latest++RUN pip install --no-cache-dir onnxruntime++CMD ["bash"]diff --git a/docker/Dockerfile.onnxruntime-gpu b/docker/Dockerfile.onnxruntime-gpunew file mode 100644index 0000000..5a0c645--- /dev/null+++ b/docker/Dockerfile.onnxruntime-gpu@@ -0,0 +1,49 @@+FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04++ENV DEBIAN_FRONTEND=noninteractive+ENV PYTHONDONTWRITEBYTECODE=1+ENV PYTHONUNBUFFERED=1+ENV PYTHONPATH=/app++WORKDIR /app++# Install Python 3.10 and system deps+RUN apt-get update && apt-get install -y --no-install-recommends \+ software-properties-common \+ && add-apt-repository ppa:deadsnakes/ppa \+ && apt-get update \+ && apt-get install -y --no-install-recommends \+ python3.10 \+ python3.10-venv \+ python3.10-dev \+ python3-pip \+ libgl1 \+ libglib2.0-0 \+ libsm6 \+ libxext6 \+ libxrender1 \+ gcc \+ g++ \+ && rm -rf /var/lib/apt/lists/*++# Make python3.10 the default+RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1 && \+ update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1++# Copy and install deps+COPY python/requirements.txt /tmp/requirements.txt++RUN python -m pip install --no-cache-dir --upgrade pip && \+ pip install --no-cache-dir -r /tmp/requirements.txt && \+ pip uninstall -y opencv-python 2>/dev/null; \+ pip install --no-cache-dir opencv-python-headless && \+ pip install --no-cache-dir pytest && \+ rm /tmp/requirements.txt++# Install ONNX Runtime GPU+RUN pip install --no-cache-dir onnxruntime-gpu++# Copy source (bind-mounted at runtime for live editing via docker-compose)+COPY python/ /app/++CMD ["bash"]diff --git a/docker/Dockerfile.openvino b/docker/Dockerfile.openvinonew file mode 100644index 0000000..02af7bb--- /dev/null+++ b/docker/Dockerfile.openvino@@ -0,0 +1,5 @@+FROM rapidocr-base:latest++RUN pip install --no-cache-dir openvino==2023.3.0++CMD ["bash"]diff --git a/docker/Dockerfile.paddle b/docker/Dockerfile.paddlenew file mode 100644index 0000000..b54bf84--- /dev/null+++ b/docker/Dockerfile.paddle@@ -0,0 +1,7 @@+FROM rapidocr-base:latest++# PaddlePaddle CPU uses a special index URL+RUN pip install --no-cache-dir paddlepaddle==3.1.1 \+ -i https://www.paddlepaddle.org.cn/packages/stable/cpu/++CMD ["bash"]diff --git a/docker/Dockerfile.pytorch b/docker/Dockerfile.pytorchnew file mode 100644index 0000000..927cb49--- /dev/null+++ b/docker/Dockerfile.pytorch@@ -0,0 +1,7 @@+FROM rapidocr-base:latest++# PyTorch CPU from official index+RUN pip install --no-cache-dir torch torchvision torchaudio \+ --index-url https://download.pytorch.org/whl/cpu++CMD ["bash"]diff --git a/docker/Dockerfile.tensorrt b/docker/Dockerfile.tensorrtnew file mode 100644index 0000000..eb1c83a--- /dev/null+++ b/docker/Dockerfile.tensorrt@@ -0,0 +1,39 @@+FROM nvcr.io/nvidia/deepstream:7.0-gc-triton-devel++ENV DEBIAN_FRONTEND=noninteractive+ENV PYTHONDONTWRITEBYTECODE=1+ENV PYTHONUNBUFFERED=1+ENV PYTHONPATH=/app++WORKDIR /app++# System deps for opencv and build tools+RUN apt-get update && apt-get install -y --no-install-recommends \+ libgl1 \+ libglib2.0-0 \+ libsm6 \+ libxext6 \+ libxrender1 \+ gcc \+ g++ \+ python3-pip \+ && rm -rf /var/lib/apt/lists/*++# Copy and install deps+COPY python/requirements.txt /tmp/requirements.txt++RUN pip install --no-cache-dir --upgrade pip && \+ pip install --no-cache-dir -r /tmp/requirements.txt && \+ pip uninstall -y opencv-python 2>/dev/null; \+ pip install --no-cache-dir opencv-python-headless && \+ pip install --no-cache-dir pytest && \+ rm /tmp/requirements.txt++# TensorRT Python bindings must match the system TRT version (8.6.1 in DeepStream 7.0).+# cuda-python must match the container's CUDA 12.x toolkit.+RUN pip install --no-cache-dir "tensorrt>=8.6,<8.7" "cuda-python>=12.0,<13.0"++# Copy source (bind-mounted at runtime for live editing via docker-compose)+COPY python/ /app/++CMD ["bash"]diff --git a/docker/README.md b/docker/README.mdindex b208dcc..ac7585c 100644--- a/docker/README.md+++ b/docker/README.md@@ -1,25 +1,185 @@-# RapidOCR API Docker+# Docker Development Environments-## Quickstart+Pre-configured Docker images for developing and testing RapidOCR with each supported inference engine.++## Prerequisites++- [Docker](https://docs.docker.com/get-docker/) (20.10+)+- [Docker Compose](https://docs.docker.com/compose/install/) (v2)+- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) (GPU images only)++## 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```bash-docker pull qingchen0607/rapid-ocr-api:v20250619-docker run -itd --restart=always --name rapidocr_api -p 9005:9005 qingchen0607/rapid-ocr-api:v20250619+make build-onnxruntime-cpu+```++### Run tests-# http://<ip>:9005/docs+```bash+make test-onnxruntime-cpu```-## Local Build+### Open an interactive shell-```shell-cd docker+```bash+make shell-onnxruntime-cpu+```-#chmod +x docker_build&run.sh docker_stop&clean.sh+### Build all images-# build image and run-./docker_build&run.sh+```bash+make build-all+```-# stop and rm image-./docker_stop&clean.sh+### Clean up++```bash+make clean```+## Using docker compose directly++```bash+# 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:++```bash+docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi+```++Then build and use GPU images normally:++```bash+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:++```bash+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++```bash+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++```bash+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++```bash+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`.diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yamlnew file mode 100644index 0000000..06d2358--- /dev/null+++ b/docker/docker-compose.yaml@@ -0,0 +1,102 @@+services:+ onnxruntime-cpu:+ build:+ context: ..+ dockerfile: docker/Dockerfile.onnxruntime-cpu+ image: rapidocr-onnxruntime-cpu:latest+ working_dir: /app+ volumes:+ - models:/app/rapidocr/models+ - ../python:/app+ stdin_open: true+ tty: true++ onnxruntime-gpu:+ build:+ context: ..+ dockerfile: docker/Dockerfile.onnxruntime-gpu+ image: rapidocr-onnxruntime-gpu:latest+ working_dir: /app+ volumes:+ - models:/app/rapidocr/models+ - ../python:/app+ deploy:+ resources:+ reservations:+ devices:+ - driver: nvidia+ count: 1+ capabilities: [gpu]+ stdin_open: true+ tty: true++ tensorrt:+ build:+ context: ..+ dockerfile: docker/Dockerfile.tensorrt+ image: rapidocr-tensorrt:latest+ working_dir: /app+ volumes:+ - models:/app/rapidocr/models+ - ../python:/app+ deploy:+ resources:+ reservations:+ devices:+ - driver: nvidia+ count: 1+ capabilities: [gpu]+ stdin_open: true+ tty: true++ paddle:+ build:+ context: ..+ dockerfile: docker/Dockerfile.paddle+ image: rapidocr-paddle:latest+ working_dir: /app+ volumes:+ - models:/app/rapidocr/models+ - ../python:/app+ stdin_open: true+ tty: true++ openvino:+ build:+ context: ..+ dockerfile: docker/Dockerfile.openvino+ image: rapidocr-openvino:latest+ working_dir: /app+ volumes:+ - models:/app/rapidocr/models+ - ../python:/app+ stdin_open: true+ tty: true++ pytorch:+ build:+ context: ..+ dockerfile: docker/Dockerfile.pytorch+ image: rapidocr-pytorch:latest+ working_dir: /app+ volumes:+ - models:/app/rapidocr/models+ - ../python:/app+ stdin_open: true+ tty: true++ mnn:+ build:+ context: ..+ dockerfile: docker/Dockerfile.mnn+ image: rapidocr-mnn:latest+ working_dir: /app+ volumes:+ - models:/app/rapidocr/models+ - ../python:/app+ stdin_open: true+ tty: true++volumes:+ models:+ name: rapidocr-modelsdiff --git a/docker/docker_build&run.sh b/docker/docker_build&run.shdeleted file mode 100644index 12ce46a..0000000--- a/docker/docker_build&run.sh+++ /dev/null@@ -1,2 +0,0 @@-docker build -t rapidocr_api --network host .-docker run -itd --restart=always --name rapidocr_api -p 9005:9005 rapidocr_api\ No newline at end of filediff --git a/docker/docker_stop&clean.sh b/docker/docker_stop&clean.shdeleted file mode 100644index c50e4e7..0000000--- a/docker/docker_stop&clean.sh+++ /dev/null@@ -1,3 +0,0 @@-docker stop rapidocr_api-docker rm rapidocr_api-docker rmi rapidocr_api\ No newline at end of filediff --git a/docker/dockerfile b/docker/dockerfiledeleted file mode 100644index df4f670..0000000--- a/docker/dockerfile+++ /dev/null@@ -1,8 +0,0 @@-FROM python:3.10.11-slim-buster-ENV DEBIAN_FRONTEND=noninteractive-WORKDIR /app-RUN pip install --no-cache-dir onnxruntime rapidocr_api -i https://mirrors.aliyun.com/pypi/simple-RUN pip uninstall -y opencv-python && \- pip install --no-cache-dir opencv-python-headless -i https://mirrors.aliyun.com/pypi/simple-EXPOSE 9005-CMD ["bash", "-c", "rapidocr_api -ip 0.0.0.0 -p 9005 -workers 2"]\ No newline at end of file