MinerU provides a comprehensive Docker-based deployment ecosystem to simplify environment setup and ensure compatibility across diverse hardware architectures. This includes support for standard NVIDIA GPUs, Huawei Ascend NPUs, and various specialized hardware accelerators (MLU, MUSA, GCU, DCU, PPU, MACA, CAMB, COREX, KXPU, NPU).
The MinerU Docker strategy relies on specialized base images (primarily vllm-openai or hardware-vendor-specific PyTorch images) to provide hardware-accelerated inference out of the box. The deployment is divided into region-specific configurations (Global vs. China) to optimize model download speeds and dependency resolution.
The following diagram illustrates how the Docker environment bridges host hardware to the MinerU application layers.
Container-to-Hardware Mapping
Sources: docker/global/Dockerfile1-24 docker/china/Dockerfile1-24 docs/zh/quick_start/docker_deployment.md16-25
MinerU provides two primary Dockerfiles for standard GPU environments, differing mainly in their model sources and mirror registries.
vllm/vllm-openai:v0.21.0) and downloads models from HuggingFace via mineru-models-download -s huggingface -m all docker/global/Dockerfile5-24docker.m.daocloud.io mirrors and downloads models from ModelScope via mineru-models-download -s modelscope -m all docker/china/Dockerfile5-24The default base image is vllm/vllm-openai:v0.21.0, which supports Volta, Turing, Ampere, Ada Lovelace, Hopper, and Blackwell architectures (7.0 <= Compute Capability <= 12.1) docker/global/Dockerfile1-6 For CUDA 12.9 compatibility, a specific -cu129 tag is provided as an alternative docker/china/Dockerfile6
MinerU uses Docker Compose profiles to manage different service components. The docker/compose.yaml file defines services for the OpenAI-compatible server, the FastAPI backend, the Router, and the Gradio frontend.
| Profile | Service | Entrypoint | Default Port |
|---|---|---|---|
openai-server | mineru-openai-server | mineru-openai-server | 30000 |
api | mineru-api | mineru-api | 8000 |
router | mineru-router | mineru-router | 8002 |
gradio | mineru-gradio | mineru-gradio | 7860 |
Sources: docker/compose.yaml1-123 docs/zh/quick_start/docker_deployment.md41-97
MinerU supports a wide array of hardware accelerators through specialized Dockerfiles. These images often include specific versions of numpy and opencv-python to ensure compatibility with vendor-provided environments docker/china/mlu.Dockerfile26-28 docker/china/gcu.Dockerfile20-23
Domestic cards often support multiple inference backends (typically vllm or lmdeploy). For example, the Cambricon MLU configuration allows switching between these by modifying the BACKEND argument in the Dockerfile, which affects which virtual environment is activated and which helper packages (like qwen-vl-utils) are installed docker/china/mlu.Dockerfile4-7 docker/china/mlu.Dockerfile20-32
The following table summarizes the specialized Docker configurations for various accelerators:
| Hardware | Dockerfile | Base Image Example | Key Dependencies |
|---|---|---|---|
| MLU (Cambricon) | mlu.Dockerfile | lmdeploy_dlinfer/camb:mineru25 | numpy==1.26.4, opencv-python==4.11.0.86 docker/china/mlu.Dockerfile26-27 |
| NPU (Ascend) | npu.Dockerfile | ascend/vllm-ascend:v0.11.0 | TORCH_DEVICE_BACKEND_AUTOLOAD=0 during model download docker/china/npu.Dockerfile32 |
| MACA (Metax) | maca.Dockerfile | maca/vllm:maca.ai3.1.0.7... | torchvision version patching docker/china/maca.Dockerfile20-21 |
| GCU (Enflame) | gcu.Dockerfile | gcu:docker_images_topsrider... | Custom APT sources for Ubuntu Noble docker/china/gcu.Dockerfile6-15 |
| PPU (T-Head) | ppu.Dockerfile | mineru/ppu:ppu-pytorch2.6.0... | mineru[core]>=3.4.0, numpy==1.26.4 docker/china/ppu.Dockerfile21-22 |
| MUSA (MooreThreads) | musa.Dockerfile | vllm-musa-qy2-py310:v0.8.4 | vision.git manual build for MUSA docker/china/musa.Dockerfile18-20 |
| COREX (Iluvatar) | corex.Dockerfile | corex:4.4.0_torch2.7.1... | mineru[core]>=3.4.0 docker/china/corex.Dockerfile17 |
Sources: docker/china/mlu.Dockerfile1-45 docker/china/npu.Dockerfile1-35 docker/china/maca.Dockerfile1-38 docker/china/gcu.Dockerfile1-30 docker/china/ppu.Dockerfile1-34 docker/china/musa.Dockerfile1-33 docker/china/corex.Dockerfile1-27
All MinerU Dockerfiles share a common ENTRYPOINT pattern to ensure models are loaded from the local cache bundled during the build phase by setting MINERU_MODEL_SOURCE=local docker/global/Dockerfile27 docker/china/Dockerfile27
To reduce startup latency, models are pre-downloaded during the docker build process using the mineru-models-download command. In China-region Dockerfiles, this uses the -s modelscope flag docker/china/Dockerfile24 For hardware like MLU, the backend choice (vllm/lmdeploy) determines which virtual environment is activated before running the download docker/china/mlu.Dockerfile35-39
The docker/compose.yaml and standard docker run commands implement specific resource constraints:
32g or higher via --shm-size to support large VLM tensors and IPC communication docs/en/quick_start/docker_deployment.md31memlock: -1 and stack: 67108864 are configured in compose.yaml to prevent memory allocation failures during heavy inference docker/compose.yaml16-18--gpu-memory-utilization parameter can be passed to services (defaulting to 0.5 in comments) to mitigate VRAM shortages docker/compose.yaml15The Docker environment often launches specialized servers defined in the CLI layer. For instance, the mineru-router can aggregate multiple mineru-api upstream instances or manage local workers using --local-gpus auto docker/compose.yaml70-78
Hardware-Specific Implementation Diagram
Sources: docker/china/mlu.Dockerfile1-45 docker/compose.yaml9-16 docker/china/npu.Dockerfile31-35 docker/compose.yaml60-80
Sources:
docker/global/Dockerfile:1-27docker/china/Dockerfile:1-27docker/china/mlu.Dockerfile:1-45docker/china/npu.Dockerfile:1-35docker/china/maca.Dockerfile:1-38docker/china/gcu.Dockerfile:1-30docker/china/ppu.Dockerfile:1-34docker/china/musa.Dockerfile:1-33docker/china/corex.Dockerfile:1-27docker/compose.yaml:1-123docs/zh/quick_start/docker_deployment.md:1-97docs/en/quick_start/docker_deployment.md:1-98Refresh this wiki