MinerU 官方镜像构建：基于 Sglang 的 Dockerfile 实践

记录基于 sglang 基础镜像构建 MinerU 官方 Docker 镜像的过程：安装 mineru core 依赖、下载并配置模型权重、设置容器入口命令，并说明视觉语言模型在整个文档解析链路中的角色定位。

https://hf-mirror.com/opendatalab/MinerU2.0-2505-0.9B

一、mineru:v2.0.6版本镜像

1、MinerU镜像官网方式构建

1、基于lmsysorg/sglang:v0.4.7-cu124构建mineru:v2-sh

# Use the official sglang image
FROM lmsysorg/sglang:v0.4.7-cu124

# install mineru latest
RUN python3 -m pip install -U 'mineru[core]' -i https://mirrors.aliyun.com/pypi/simple --break-system-packages

# Download models and update the configuration file
RUN mineru-models-download -s modelscope -m all

# Set the entry point to activate the virtual environment and run the command line tool
ENTRYPOINT ["/bin/sh", "-c", "export MINERU_MODEL_SOURCE=local; exec \"$@\"", "--"]

2、启动服务

sudo docker run --gpus '"device=0"' \
  --shm-size 32g \
  -p 30000:30000 \
  --ipc=host \
  mineru:v2-sh \
  mineru-sglang-server --host 0.0.0.0 --port 30000

3、启动日志

WARNING:sglang.srt.models.registry:Ignore import error when loading sglang.srt.models.torch_native_llama. tensor model parallel group is not initialized
[2025-06-26 02:03:00] server_args=ServerArgs(model_path='/root/.cache/modelscope/hub/models/OpenDataLab/MinerU2___0-2505-0___9B', tokenizer_path='/root/.cache/modelscope/hub/models/OpenDataLab/MinerU2___0-2505-0___9B', tokenizer_mode='auto', skip_tokenizer_init=False, load_format='auto', trust_remote_code=False, dtype='auto', kv_cache_dtype='auto', quantization=None, quantization_param_path=None, context_length=None, device='cuda', served_model_name='/root/.cache/modelscope/hub/models/OpenDataLab/MinerU2___0-2505-0___9B', chat_template='chatml', completion_template=None, is_embedding=False, enable_multimodal=None, revision=None, impl='auto', host='0.0.0.0', port=30000, mem_fraction_static=0.88, max_running_requests=None, max_total_tokens=None, chunked_prefill_size=8192, max_prefill_tokens=16384, schedule_policy='fcfs', schedule_conservativeness=1.0, cpu_offload_gb=0, page_size=1, tp_size=1, pp_size=1, max_micro_batch_size=None, stream_interval=1, stream_output=False, random_seed=989644197, constrained_json_whitespace_pattern=None, watchdog_timeout=300, dist_timeout=None, download_dir=None, base_gpu_id=0, gpu_id_step=1, log_level='info', log_level_http=None, log_requests=False, log_requests_level=0, show_time_cost=False, enable_metrics=False, bucket_time_to_first_token=None, bucket_e2e_request_latency=None, bucket_inter_token_latency=None, collect_tokens_histogram=False, decode_log_interval=40, enable_request_time_stats_logging=False, kv_events_config=None, api_key=None, file_storage_path='sglang_storage', enable_cache_report=False, reasoning_parser=None, dp_size=1, load_balance_method='round_robin', ep_size=1, dist_init_addr=None, nnodes=1, node_rank=0, json_model_override_args='{}', preferred_sampling_params=None, lora_paths=None, max_loras_per_batch=8, lora_backend='triton', attention_backend=None, ds_channel_config_path=None, ds_heavy_channel_num=32, ds_heavy_token_num=256, ds_heavy_channel_type='qk', ds_sparse_decode_threshold=4096, disable_radix_cache=False, disable_cuda_graph=False, disable_cuda_graph_padding=False, enable_nccl_nvls=False, enable_tokenizer_batch_encode=False, disable_outlines_disk_cache=False, disable_custom_all_reduce=False, enable_mscclpp=False, disable_overlap_schedule=False, enable_mixed_chunk=False, enable_dp_attention=False, enable_dp_lm_head=False, enable_two_batch_overlap=False, enable_ep_moe=False, enable_deepep_moe=False, deepep_mode='auto', ep_num_redundant_experts=0, ep_dispatch_algorithm='static', init_expert_location='trivial', enable_eplb=False, eplb_algorithm='auto', eplb_rebalance_num_iterations=1000, eplb_rebalance_layers_per_chunk=None, expert_distribution_recorder_mode=None, expert_distribution_recorder_buffer_size=1000, enable_expert_distribution_metrics=False, deepep_config=None, enable_torch_compile=False, torch_compile_max_bs=32, cuda_graph_max_bs=None, cuda_graph_bs=None, torchao_config='', enable_nan_detection=False, enable_p2p_check=False, triton_attention_reduce_in_fp32=False, triton_attention_num_kv_splits=8, num_continuous_decode_steps=1, delete_ckpt_after_loading=False, enable_memory_saver=False, allow_auto_truncate=False, enable_custom_logit_processor=True, tool_call_parser=None, enable_hierarchical_cache=False, hicache_ratio=2.0, hicache_size=0, hicache_write_policy='write_through_selective', flashinfer_mla_disable_ragged=False, warmups=None, moe_dense_tp_size=None, disable_shared_experts_fusion=False, disable_chunked_prefix_cache=False, disable_fast_image_processor=False, mm_attention_backend=None, debug_tensor_dump_output_folder=None, debug_tensor_dump_input_file=None, debug_tensor_dump_inject=False, disaggregation_mode='null', disaggregation_bootstrap_port=8998, disaggregation_transfer_backend='mooncake', disaggregation_ib_device=None, pdlb_url=None)
`use_fast` is set to `True` but the image processor class does not have a fast version.  Falling back to the slow version.
[2025-06-26 02:03:01] Use chat template for the OpenAI-compatible API server: chatml
WARNING:sglang.srt.models.registry:Ignore import error when loading sglang.srt.models.torch_native_llama. tensor model parallel group is not initialized
`use_fast` is set to `True` but the image processor class does not have a fast version.  Falling back to the slow version.
WARNING:sglang.srt.models.registry:Ignore import error when loading sglang.srt.models.torch_native_llama. tensor model parallel group is not initialized
[2025-06-26 02:03:07] Attention backend not set. Use flashinfer backend by default.
[2025-06-26 02:03:07] Automatically reduce --mem-fraction-static to 0.792 because this is a multimodal model.
[2025-06-26 02:03:07] Init torch distributed begin.
[2025-06-26 02:03:08] Init torch distributed ends. mem usage=0.00 GB
[2025-06-26 02:03:08] Load weight begin. avail mem=78.65 GB
Loading safetensors checkpoint shards:   0% Completed | 0/1 [00:00<?, ?it/s]
Loading safetensors checkpoint shards: 100% Completed | 1/1 [00:00<00:00,  2.17it/s]
Loading safetensors checkpoint shards: 100% Completed | 1/1 [00:00<00:00,  2.16it/s]

[2025-06-26 02:03:09] Load weight end. type=Mineru2QwenForCausalLM, dtype=torch.bfloat16, avail mem=76.83 GB, mem usage=1.82 GB.
[2025-06-26 02:03:09] KV Cache is allocated. #tokens: 5282908, K size: 30.23 GB, V size: 30.23 GB
[2025-06-26 02:03:09] Memory pool end. avail mem=15.80 GB
[2025-06-26 02:03:09] Capture cuda graph begin. This can take up to several minutes. avail mem=15.31 GB
[2025-06-26 02:03:09] Capture cuda graph bs [1, 2, 4, 8, 16, 24, 32, 40, 48, 56, 64, 72, 80, 88, 96, 104, 112, 120, 128, 136, 144, 152, 160]
Capturing batches (avail_mem=13.94 GB): 100%|██████████| 23/23 [00:22<00:00,  1.01it/s]
[2025-06-26 02:03:32] Capture cuda graph end. Time elapsed: 22.96 s. mem usage=1.38 GB. avail mem=13.93 GB.
[2025-06-26 02:03:32] max_total_num_tokens=5282908, chunked_prefill_size=8192, max_prefill_tokens=16384, max_running_requests=4096, context_len=32768, available_gpu_mem=13.93 GB
[2025-06-26 02:03:33] INFO:     Started server process [1]
[2025-06-26 02:03:33] INFO:     Waiting for application startup.
[2025-06-26 02:03:33] INFO:     Application startup complete.
[2025-06-26 02:03:33] INFO:     Uvicorn running on http://0.0.0.0:30000 (Press CTRL+C to quit)
[2025-06-26 02:03:34] INFO:     127.0.0.1:38352 - "GET /get_model_info HTTP/1.1" 200 OK
[2025-06-26 02:03:34] Prefill batch. #new-seq: 1, #new-token: 6, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 0
[2025-06-26 02:03:38] INFO:     127.0.0.1:38356 - "POST /generate HTTP/1.1" 200 OK
[2025-06-26 02:03:38] The server is fired up and ready to roll!
[2025-06-26 02:22:08] Prefill batch. #new-seq: 1, #new-token: 1, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 0
[2025-06-26 02:22:09] INFO:     10.33.27.93:54441 - "GET /health_generate HTTP/1.1" 200 OK
[2025-06-26 02:22:10] INFO:     10.33.27.93:54444 - "GET /get_model_info HTTP/1.1" 200 OK

4、调用服务

mineru
doclayout_yolo
ultralytics
rapid_table
openai

客户端显示的日志

服务端的日志

2、MinerU模型分析

{
    "bucket_info": {
        "bucket-name-1": [
            "ak",
            "sk",
            "endpoint"
        ],
        "bucket-name-2": [
            "ak",
            "sk",
            "endpoint"
        ]
    },
    "latex-delimiter-config": {
        "display": {
            "left": "$$",
            "right": "$$"
        },
        "inline": {
            "left": "$",
            "right": "$"
        }
    },
    "llm-aided-config": {
        "title_aided": {
            "api_key": "your_api_key",
            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "model": "qwen2.5-32b-instruct",
            "enable": false
        }
    },
    "models-dir": {
        "pipeline": "/root/.cache/modelscope/hub/models/OpenDataLab/PDF-Extract-Kit-1___0",
        "vlm": "/root/.cache/modelscope/hub/models/OpenDataLab/MinerU2___0-2505-0___9B"
    },
    "config_version": "1.3.0"
}

MinerU2.0-2505-0.9B（2.0G）：https://huggingface.co/opendatalab/MinerU2.0-2505-0.9B，单模型涵盖所有文档解析任务

       ┌──────────────────────────────┐
       │   图像输入（任意分辨率）      │
       └────────────┬─────────────────┘
                    ↓
┌─────────────── Vision Encoder ───────────────┐
│     SigLIP (google/siglip-so400m-patch14-384)│
└─────────────────────┬────────────────────────┘
                      ↓
           MLP Projector (2层GELU)
                      ↓
  映射为嵌入后插入语言模型（作为Token）
                      ↓
┌─────────────── Qwen-like Transformer ───────────────┐
│       支持长上下文（32K tokens），24层，KV头=2       │
└─────────────────────────────────────────────────────┘
                      ↓
             生成/多模态对齐输出

其整体架构和 Qwen2.5-VL没有本质上的差别。VLM解析方法能有效提取大表格的内部信息，并进行标题、正文划分。VLM模型需要将图像编码成token，一旦图像分辨率很高，图像编码所带来的显存占用，甚至会远高于模型本身的显存占用。

3、VLM的角色定位

• 解析模块的核心：VLM（如vlm-transformers或vlm-sglang后端）专门负责高精度的文档理解，包括：
• 非全流程覆盖：全流程为预处理-解析-后处理。VLM不参与预处理（如PDF去噪、页码过滤）或后处理（如Markdown格式转换），这些由pipeline后端或其他模块处理
• MinerU的VLM模块是一个端到端的多模态文档理解模型，覆盖了从视觉感知到结构化输出的完整解析链路
• VLM模块的token输入格式：<|box_start|>x0 y0 x1 y1<|box_end|><|ref_start|>type<|ref_end|><|md_start|>content<|md_end|>

  模块	VLM的作用	其他模块的作用
  预处理	不参与	由pipeline处理（如页眉页脚移除）
  解析	核心作用（布局分析、OCR、公式识别）	pipeline使用传统OCR/模型
  后处理	输出结构化JSON/Markdown	统一由中间格式middle_json处理

PDF-Extract-Kit-1.0（2.4G）：Layout MFD MFR OCR ReadingOrder TabRec

https://pdf-extract-kit.readthedocs.io/zh-cn/latest/

Layout（文档布局分析 (Detectron2)）：YOLO——doclayout_yolo_docstructbench_imgsz1280_2501.pt（38M）

MFD（数学公式检测 (PyTorch)）：YOLO——yolo_v8_ft.pt（334M）

MFR（数学公式识别 (BERT-based)）：unimernet_hf_small_2503（776M）

OCR：paddleocr_torch（522M）

ReadingOrder：layout_reader（681M）

TabRec（表格识别与重建 (T5-based)）：SlanetPlus（7.5M）

通过 -b 或 --backend参数，可指定使用基础解析方式或vlm解析方式：

• pipeline：基础解析方式
• vlm-transformers：vlm解析方式
• vlm-sglang-engine：vlm加速解析方式
• vlm-sglang-client：vlm加速解析方式(连接sglang 服务调用)

  二、mineru:v1.3.12版本镜像

1、MinerU镜像官网方式构建

1、基于ubuntu:22.04构建mineru:wangkaihan-test

# Use the official Ubuntu base image
FROM ubuntu:22.04

# Set environment variables to non-interactive to avoid prompts during installation
ENV DEBIAN_FRONTEND=noninteractive

# Update the package list and install necessary packages
RUN apt-get update && \
    apt-get install -y \
        software-properties-common && \
    add-apt-repository ppa:deadsnakes/ppa && \
    apt-get update && \
    apt-get install -y \
        python3.10 \
        python3.10-venv \
        python3.10-distutils \
        python3-pip \
        wget \
        git \
        libgl1 \
        libreoffice \
        fonts-noto-cjk \
        fonts-wqy-zenhei \
        fonts-wqy-microhei \
        ttf-mscorefonts-installer \
        fontconfig \
        libglib2.0-0 \
        libxrender1 \
        libsm6 \
        libxext6 \
        poppler-utils \
        && rm -rf /var/lib/apt/lists/*

# Set Python 3.10 as the default python3
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1

# Create a virtual environment for MinerU
RUN python3 -m venv /opt/mineru_venv

# Copy the configuration file template and install magic-pdf latest
RUN /bin/bash -c "wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/magic-pdf.template.json && \
    cp magic-pdf.template.json /root/magic-pdf.json && \
    source /opt/mineru_venv/bin/activate && \
    pip3 install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple && \
    pip3 install -U magic-pdf[full] -i https://mirrors.aliyun.com/pypi/simple"

# Download models and update the configuration file
RUN /bin/bash -c "pip3 install modelscope -i https://mirrors.aliyun.com/pypi/simple && \
    wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models.py -O download_models.py && \
    python3 download_models.py && \
    sed -i 's|cpu|cuda|g' /root/magic-pdf.json"

2、基于mineru:wangkaihan-test构建mineru:wangkaihan-test-20250610

FROM mineru:wangkaihan-test
ENTRYPOINT ["/bin/bash", "-c", "source /opt/mineru_venv/bin/activate && exec \"$@\"", "--"]

3、构建新的mineru:wangkaihan-test-20250610镜像

sudo docker build -t mineru:wangkaihan-test-20250610 .

4、基于mineru:wangkaihan-test-20250610创建容器

sudo docker run -it --name mineru --gpus=7 mineru:wangkaihan-test-20250610 /bin/bash -c "echo 'source /opt/mineru_venv/bin/activate' >> ~/.bashrc && exec bash"

2、MinerU自定义方式构建

1、基于mineru:wangkaihan-test构建mineru:wangkaihan-test-20250610095346

FROM mineru:wangkaihan-test
ENTRYPOINT ["/bin/sh", "-c", ". /opt/mineru_venv/bin/activate && exec \"$@\"", "--"]

2、构建mineru:wangkaihan-test-20250610095346新镜像（更换ENTRYPOINT兼容sh）

sudo docker build -t mineru:wangkaihan-test-20250610095346 .

3、基于自定义的mineru:wangkaihan-test-20250610095346构建容器

sudo docker run -it --name mineru-test-20250610095346 --gpus=7 mineru:wangkaihan-test-20250610095346 sh

3、MinerU服务启动

1、进入对应的mineru_project目录文件夹

cd mineru_project

2、安装mineru_project服务所需的pip包

pip install fastapi==0.115.12 loguru==0.7.3 tenacity==9.1.2 httpx==0.28.1 pymysql==1.1.1 python-multipart==0.0.20 uvicorn==0.34.3 -i https://pypi.tuna.tsinghua.edu.cn/simple

3、启动unvicorn服务

uvicorn main:app --host 0.0.0.0 --port 8888

4、服务curl调用

curl --location 'http://10.39.214.112:8998/pdf_parse_async?parse_method=auto&is_json_md_dump=false&return_images=true&env=dev' \
--form 'data_file=@"./Qwen3-Technical-Report.pdf"'

4、MinerU服务重新启动

1、将mineru-test-20250610095346容器打包成mineru:v1-20250610镜像

sudo docker commit mineru-test-20250610095346 mineru:v1-20250610

2、重新启动mineru容器

sudo docker run -it --name mineru-test-20250610135010 --gpus=7 -P -p 8998:8998 mineru:v1-20250610 sh

3、进入对应的mineru_project目录文件夹

cd mineru_project

4、启动unvicorn服务

uvicorn main:app --host 0.0.0.0 --port 8998

5、服务curl调用

curl --location 'http://10.39.214.112:8998/pdf_parse_async?parse_method=auto&is_json_md_dump=false&return_images=true&env=dev' \
--form 'data_file=@"./Qwen3-Technical-Report.pdf"'

6、服务端日志调用

三、Mineru v1.2.2版本

https://mineru.readthedocs.io/zh-cn/latest/user_guide/install/install.html

1、MinerU环境安装

1. 检测是否已安装 nvidia 驱动

nvidia-smi

如果看到类似如下的信息，说明已经安装了 nvidia 驱动，可以跳过步骤2

Important

CUDA Version 显示的版本号应 >=12.1，如显示的版本号小于12.1，请升级驱动

+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 537.34                 Driver Version: 537.34       CUDA Version: 12.2     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                     TCC/WDDM  | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA GeForce RTX 3060 Ti   WDDM  | 00000000:01:00.0  On |                  N/A |
|  0%   51C    P8              12W / 200W |   1489MiB /  8192MiB |      5%      Default |
|                                         |                      |                  N/A |
+-----------------------------------------+----------------------+----------------------+

2. 安装驱动

如没有驱动，则通过如下命令

sudo apt-get update
sudo apt-get install nvidia-driver-545

安装专有驱动，安装完成后，重启电脑

reboot

3. 安装 anacoda

如果已安装 conda，可以跳过本步骤

wget -U NoSuchBrowser/1.0 https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/Anaconda3-2024.06-1-Linux-x86_64.sh
bash Anaconda3-2024.06-1-Linux-x86_64.sh

最后一步输入yes，关闭终端重新打开

4. 使用 conda 创建环境

需指定 python 版本为3.10

conda create -n MinerU python=3.10
conda activate MinerU

5. 安装应用

pip install -U magic-pdf[full] --extra-index-url https://wheels.myhloli.com -i https://mirrors.aliyun.com/pypi/simple

下载完成后，务必通过以下命令确认magic-pdf的版本是否正确

magic-pdf --version

如果版本号小于0.7.0，请到issue中向我们反馈

2、MinerU模型下载

使用python脚本 从Hugging Face下载模型文件

pip install huggingface_hub
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models_hf.py -O download_models_hf.py
python download_models_hf.py

python脚本会自动下载模型文件并配置好配置文件中的模型目录

或者使用python脚本从 ModelScope 下载模型文件

pip install modelscope
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models.py -O download_models.py
python download_models.py

python脚本会自动下载模型文件并配置好配置文件中的模型目录

配置文件可以在用户目录中找到，文件名为magic-pdf.json

了解配置文件存放的位置

完成下载模型步骤后，脚本会自动生成用户目录下的magic-pdf.json文件，并自动配置默认模型路径。您可在【用户目录】下找到magic-pdf.json文件。

linux用户目录为 “/home/用户名”

3、MinerU服务启动

从仓库中下载样本文件，并测试

wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/demo/small_ocr.pdf
magic-pdf -p small_ocr.pdf -o ./output

测试CUDA加速

如果您的显卡显存大于等于 8GB ，可以进行以下流程，测试CUDA解析加速效果

首先修改【用户目录】中配置文件 magic-pdf.json 中”device-mode”的值

{
  "device-mode":"cuda"
}

然后运行以下命令测试 cuda 加速效果

magic-pdf -p small_ocr.pdf -o ./output

CUDA 加速是否生效可以根据 log 中输出的各个阶段 cost 耗时来简单判断，通常情况下， layout detection cost 和 mfr time 应提速10倍以上。

ocr 开启 cuda 加速

首先下载paddlepaddle-gpu, 安装完成后会自动开启ocr加速

python -m pip install paddlepaddle-gpu==3.0.0b1 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/

然后运行以下命令测试ocr加速效果

magic-pdf -p small_ocr.pdf -o ./output

CUDA 加速是否生效可以根据 log 中输出的各个阶段 cost 耗时来简单判断，通常情况下， ocr cost 应提速10倍以上。

示例

import os

from magic_pdf.data.data_reader_writer import FileBasedDataWriter, FileBasedDataReader
from magic_pdf.data.dataset import PymuDocDataset
from magic_pdf.model.doc_analyze_by_custom_model import doc_analyze

# args
pdf_file_name = "abc.pdf"  # replace with the real pdf path
name_without_suff = pdf_file_name.split(".")[0]

# prepare env
local_image_dir, local_md_dir = "output/images", "output"
image_dir = str(os.path.basename(local_image_dir))

os.makedirs(local_image_dir, exist_ok=True)

image_writer, md_writer = FileBasedDataWriter(local_image_dir), FileBasedDataWriter(
    local_md_dir
)
image_dir = str(os.path.basename(local_image_dir))

# read bytes
reader1 = FileBasedDataReader("")
pdf_bytes = reader1.read(pdf_file_name)  # read the pdf content

# proc
## Create Dataset Instance
ds = PymuDocDataset(pdf_bytes)

ds.apply(doc_analyze, ocr=True).pipe_ocr_mode(image_writer).dump_md(md_writer, f"{name_without_suff}.md", image_dir)

运行以上的代码，会得到如下的结果

output/
├── abc.md
└── images

除去初始化环境，如建立目录、导入依赖库等逻辑。真正将 pdf 转换为 markdown 的代码片段如下

# read bytes
reader1 = FileBasedDataReader("")
pdf_bytes = reader1.read(pdf_file_name)  # read the pdf content

# proc
## Create Dataset Instance
ds = PymuDocDataset(pdf_bytes)

ds.apply(doc_analyze, ocr=True).pipe_ocr_mode(image_writer).dump_md(md_writer, f"{name_without_suff}.md", image_dir)

ds.apply(doc_analyze, ocr=True) 会生成 InferenceResult 对象。 InferenceResult 对象执行 pipe_ocr_mode 方法会生成 PipeResult 对象。 PipeResult 对象执行 dump_md 会在指定位置生成 markdown 文件。