name

deploy-mineru-vlm-docker

description

Create, reproduce, validate, troubleshoot, or package a MinerU 3.4.4 GPU deployment using Docker Desktop/WSL2 or Linux, NVIDIA CUDA 12.9, vLLM 0.21.0, the vlm-engine backend, baked-in offline models, and FastAPI. Use when Codex needs to deploy MinerU without the low-accuracy pipeline backend, prepare a reusable/offline Docker image, diagnose MinerU CUDA or container startup failures, or generate the validated RTX 3060 12GB deployment template.

Deploy MinerU 3.4.4 VLM with Docker

Deploy the validated MinerU GPU profile and require a real CUDA/PyTorch check before declaring success.

Target profile

Pin MinerU to 3.4.4.
Use docker.m.daocloud.io/vllm/vllm-openai:v0.21.0-cu129.
Use vlm-engine, never silently substitute pipeline.
Bake all models into the image with ModelScope and run with MINERU_MODEL_SOURCE=local.
Expose FastAPI on 127.0.0.1:8000 by default.
Start with one concurrent request, processing window 32, and vLLM GPU memory utilization 0.75.
Treat RTX 3060 12GB on Windows Docker Desktop/WSL2 as the validated reference host.

If the host has no usable NVIDIA GPU, stop and explain that pure CPU local MinerU requires pipeline; do not claim this VLM profile supports CPU inference.

Workflow

Inspect nvidia-smi, Docker engine status, Linux-container mode, free disk, and available GPU memory.
On Windows, ensure Docker Desktop and WSL are current. Do not install a Linux display driver inside WSL.

Scaffold a deployment directory:

powershell -ExecutionPolicy Bypass -File scripts/scaffold-deployment.ps1 -TargetPath <target-directory>

Review compose.yaml before running:
- Change device_ids only when the target GPU is not index 0.
- Lower --gpu-memory-utilization to 0.65 when other desktop applications occupy substantial VRAM.
- Keep the loopback port binding unless the user explicitly authorizes LAN exposure and firewall changes.
On Windows, run install.cmd. On Linux, run docker compose build --pull, execute the PyTorch CUDA smoke test from build-and-start.ps1, then run docker compose up -d.
Require all of these success conditions:
- nvidia-smi works inside a CUDA container.
- torch.cuda.get_device_name(0) works inside the built MinerU image.
- Container health is healthy after VLM preload.
- GET http://127.0.0.1:8000/health succeeds.
- A representative PDF succeeds with backend=vlm-engine.
Use test-pdf.ps1 for the representative parse. Inspect Markdown, tables, formulas, reading order, and output JSON rather than accepting HTTP 200 as sufficient quality validation.
For offline transfer, export the tested image with docker save, record a SHA-256 checksum, transfer both, then docker load inside the isolated network.

Never run docker system prune, delete unrelated images/volumes, expose the API publicly, or modify host GPU drivers without explicit authorization.

Resources

Run scripts/scaffold-deployment.ps1 to copy the validated files from assets/mineru-gpu-template without overwriting existing files unless -Force is supplied.
Read references/troubleshooting.md when a build, CUDA initialization, health check, or API request fails.
Use assets/mineru-gpu-template as output boilerplate; do not edit the master template for a one-off deployment unless the change should apply to future users.

Deploy MinerU 3.4.4 VLM with Docker

Deploy the validated MinerU GPU profile and require a real CUDA/PyTorch check before declaring success.

Target profile

Pin MinerU to 3.4.4.

Use docker.m.daocloud.io/vllm/vllm-openai:v0.21.0-cu129.

Use vlm-engine, never silently substitute pipeline.

Bake all models into the image with ModelScope and run with MINERU_MODEL_SOURCE=local.

Expose FastAPI on 127.0.0.1:8000 by default.

Start with one concurrent request, processing window 32, and vLLM GPU memory utilization 0.75.

Treat RTX 3060 12GB on Windows Docker Desktop/WSL2 as the validated reference host.

If the host has no usable NVIDIA GPU, stop and explain that pure CPU local MinerU requires pipeline; do not claim this VLM profile supports CPU inference.

Workflow

Inspect nvidia-smi, Docker engine status, Linux-container mode, free disk, and available GPU memory.

On Windows, ensure Docker Desktop and WSL are current. Do not install a Linux display driver inside WSL.

Scaffold a deployment directory:

powershell -ExecutionPolicy Bypass -File scripts/scaffold-deployment.ps1 -TargetPath <target-directory>

Review compose.yaml before running:

Change device_ids only when the target GPU is not index 0.
Lower --gpu-memory-utilization to 0.65 when other desktop applications occupy substantial VRAM.
Keep the loopback port binding unless the user explicitly authorizes LAN exposure and firewall changes.

On Windows, run install.cmd. On Linux, run docker compose build --pull, execute the PyTorch CUDA smoke test from build-and-start.ps1, then run docker compose up -d.

Require all of these success conditions:

nvidia-smi works inside a CUDA container.
torch.cuda.get_device_name(0) works inside the built MinerU image.
Container health is healthy after VLM preload.
GET http://127.0.0.1:8000/health succeeds.
A representative PDF succeeds with backend=vlm-engine.

Use test-pdf.ps1 for the representative parse. Inspect Markdown, tables, formulas, reading order, and output JSON rather than accepting HTTP 200 as sufficient quality validation.

For offline transfer, export the tested image with docker save, record a SHA-256 checksum, transfer both, then docker load inside the isolated network.

Never run docker system prune, delete unrelated images/volumes, expose the API publicly, or modify host GPU drivers without explicit authorization.

Resources

Run scripts/scaffold-deployment.ps1 to copy the validated files from assets/mineru-gpu-template without overwriting existing files unless -Force is supplied.

Read references/troubleshooting.md when a build, CUDA initialization, health check, or API request fails.

Use assets/mineru-gpu-template as output boilerplate; do not edit the master template for a one-off deployment unless the change should apply to future users.