bsq0418/mineru

MinerU Docker Image Guide

Overview

This repository builds a Docker image for the MinerU PDF intelligence toolkit. The image ships with magic-pdf[full] and the required configuration so you can convert PDFs into Markdown, JSON, and other structured formats right inside the container. It is based on the Arm-optimized armswdev/pytorch-arm-neoverse base image, making it ideal for Apple Silicon, AWS Graviton, and other arm64 hosts.

For details on MinerU capabilities, algorithm components, and configuration options, refer to the official documentation:

• MinerU GitHub: https://github.com/opendatalab/MinerU
• MinerU User Guide: https://opendatalab.github.io/MinerU/

Supported Scenarios & Limitations

• This image targets the MinerU Pipeline release and includes the traditional YOLO + OCR + table/formula models. It does not provide the latest vision-language (VLM) pipeline from the official project.
• All required models are pre-downloaded under /mineru/models; no extra setup is needed.
• The build enables NEON instructions on arm64, delivering solid throughput even in CPU-only environments.
• Best suited to Arm CPU deployments—Apple Silicon, AWS Graviton, etc.—where you want pure CPU acceleration without a GPU dependency.

Image Highlights

• Bundles magic-pdf[full], huggingface_hub, and dependencies required for layout, OCR, formula, and table recognition.
• Ships with a ready-to-use magic-pdf.json configuration so the container works out of the box.
• Installs libgl1 to ensure OpenCV and PaddleOCR operate correctly in headless environments.
• Caches PDF Extract Kit and LayoutReader assets in /mineru/models, tuned for Arm CPU/NEON to cut down on cold-start latency.

Quick Start

1. Pull the image

   bash
   docker pull <dockerhub-namespace>/mineru:<tag>
   

   Replace <dockerhub-namespace> and <tag> with the repository and tag published on Docker Hub.

2. Launch the container with a mounted workspace

   bash
   docker run --name mineru-dev \
     -v $(pwd)/data:/workspace \
     -it <dockerhub-namespace>/mineru:<tag> /bin/bash
   

   • $(pwd)/data hosts PDFs to process and the output artifacts.
   • The default working directory is /mineru; magic-pdf.json is copied to both /root/ and /home/ubuntu/.

3. Run a conversion task inside the container

   bash
   magic-pdf run \
     --config /root/magic-pdf.json \
     --input /workspace/input.pdf \
     --output /workspace/output_dir \
     --task pdf2md
   

   • Switch --task to pdf2json, pdf2html, etc., as needed. Consult the official docs for the full CLI reference.
   • To process standalone images, check the picture_test.py example script in this repo.

Repository Layout

• Dockerfile: Build instructions for the image.
• magic-pdf.json: Default configuration covering model locations, OCR/table/formula toggles, and optional LLM hooks.
• models/: Pre-staged MinerU/MoTao model cache.
• download_models_hf.py: Script to refresh models/config via Hugging Face Hub.
• picture_test.py: Sample script for running layout + OCR on a single image.
• docker_start.sh: Example startup script that mounts the repo root at /app.

Updating Models & Config

• To sync newer models, run python download_models_hf.py inside the container. It leverages huggingface_hub.snapshot_download and rewrites magic-pdf.json with the new paths.
• Formula and table recognition are enabled by default; adjust the corresponding sections in /root/magic-pdf.json to disable them or to activate LLM-assisted features.
• To enable Tongyi Qianwen or other LLM helpers, populate the api_key and base_url fields in the config and set enable to true.

FAQ

• Architecture: Built for arm64. Only useful for arm64.
• Model Size: Bundled models are large; ensure sufficient bandwidth and disk space when pulling.
• Network Access: If you need to re-download assets, grant the container outbound access to Hugging Face Hub.
• GPU Support: This base image targets CPU workflows. For GPU/ACL acceleration, swap the base image per the official documentation and adjust device-mode.

Credits

This image extends the MinerU solution by the OpenDataLab community. Thanks to the project maintainers and contributors for the extraction pipelines and pretrained assets. For advanced scenarios—region-based extraction, batch pipelines, production deployment—refer to the official MinerU documentation.