MinerU

https://opendatalab.github.io/MinerU/
Admin
MinerU is a tool that converts PDFs into machine-readable formats like markdown and JSON, with...
Tokens:75,379
Snippets:472
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start MinerU WebUI

Source: https://opendatalab.github.io/MinerU/zh/quick_start/docker_deployment

Starts the MinerU WebUI inside the container, binding to all interfaces on port 7860. Run this after entering the interactive container.

```bash
mineru-kit webui --server-name 0.0.0.0 --server-port 7860

```

--------------------------------

### Download MinerU model inside container

Source: https://opendatalab.github.io/MinerU/zh/usage/plugin/RagFlow

Run these five commands sequentially inside the container to create a virtual environment and install MinerU with the core extra using the Aliyun PyPI mirror.

```bash
mkdir uv_tools
cd uv_tools
uv venv .venv
source .venv/bin/activate
uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple

```

--------------------------------

### Start Docker Compose services by profile

Source: https://opendatalab.github.io/MinerU/zh/quick_start/docker_deployment

Starts the Docker Compose services for the selected profile. Profiles: webui (document parsing UI at http://127.0.0.1:7860), api (V1 API at http://127.0.0.1:8000/v1/health), router (multi-service/multi-GPU V1 entry at http://127.0.0.1:8002/v1/health), and openai-server (OpenAI-compatible VLM inference at http://127.0.0.1:30000/health). Plan GPU memory and allocation when running multiple model services.

```bash
docker compose -f docker/compose.yaml --profile webui up -d
docker compose -f docker/compose.yaml --profile api up -d
docker compose -f docker/compose.yaml --profile router up -d
docker compose -f docker/compose.yaml --profile openai-server up -d

```

--------------------------------

### Start V1 API server with mineru-kit api-server

Source: https://opendatalab.github.io/MinerU/zh/usage/quick_usage

Starts a self-hosted V1 API server. Access the OpenAPI documentation at http://127.0.0.1:8000/docs. The service only exposes /v1/* endpoints, including health check, capability discovery, upload, file, parse task, and usage query.

```bash
mineru-kit api-server --host 0.0.0.0 --port 8000 --tier standard

```

--------------------------------

### Start mineru-router for multi-service orchestration

Source: https://opendatalab.github.io/MinerU/zh/usage/quick_usage

Starts the mineru-router for multi-service or multi-GPU orchestration. It exposes the full /v1/* API. Use --upstream-url to aggregate multiple V1 api-servers, or --local-gpus to automatically start mineru-kit api-server workers. --preload-models only affects locally hosted workers; remote upstreams keep their own startup configuration. Router does not pass through unknown model engine parameters.

```bash
mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto --worker-tier standard

```

--------------------------------

### Start PPU Docker Container

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/THead

Starts the PPU Docker container with the vllm image. Replace the image with mineru:ppu-lmdeploy-latest for lmdeploy. Enters an interactive terminal; replace /bin/bash with a service start command to launch a MinerU service.

```bash
docker run --privileged=true \
  --name mineru_docker \
  --device=/dev/alixpu \
  --device=/dev/alixpu_ctl \
  --ipc=host \
  --network=host \
  --ulimit memlock=-1 \
  --ulimit stack=67108864 \
  --shm-size=500g \
  -v /mnt:/mnt \
  -v /datapool:/datapool \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e MINERU_MODEL_SOURCE=local \
  -it mineru:ppu-vllm-latest \
  /bin/bash

```

--------------------------------

### structured_content() output example

Source: https://opendatalab.github.io/MinerU/zh/reference/output_files

Example of the JSON structure returned by structured_content(), showing pages, blocks, metadata, extensions, and is_full_document fields.

```json
{
  "pages": [
    {
      "page_idx": 0,
      "blocks": [
        {
          "type": "text",
          "content": "Hello MinerU"
        }
      ]
    }
  ],
  "metadata": {
    "file_suffix": "html",
    "producer": {
      "name": "mineru",
      "version": "4.0.0"
    }
  },
  "extensions": {
    "mineru": {
      "tier": "flash",
      "parse_mode": "txt"
    }
  },
  "is_full_document": true
}
```

--------------------------------

### Install MinerU with version constraint for legacy platforms

Source: https://opendatalab.github.io/MinerU/zh/usage/compatibility

Shows the version constraint for MinerU <4 on the 13 legacy platforms. The command only illustrates the constraint; actual deployment must follow each platform's Dockerfile to keep vendor Torch, engines, and patches, and must not blindly run a full upgrade inside the vendor image.

```bash
python -m pip install "mineru[core]>=3.4.0,<4"
```

--------------------------------

### Start Docker container

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Cambricon

Runs the MinerU Docker container with the necessary device mappings and environment variables for Cambricon acceleration.

```bash
docker run --name mineru_docker \
   --privileged \
   --ipc=host \
   --network=host \
   --shm-size=400g \
   --ulimit memlock=-1 \
   -v /dev:/dev \
   -v /lib/modules:/lib/modules:ro \
   -v /usr/bin/cnmon:/usr/bin/cnmon \
   -e MINERU_MODEL_SOURCE=local \
   -e MINERU_LMDEPLOY_DEVICE=camb \
   -it mineru:mlu-lmdeploy-latest \
   /bin/bash

```

--------------------------------

### Run interactive MinerU container

Source: https://opendatalab.github.io/MinerU/zh/quick_start/docker_deployment

Starts an interactive container with GPU access and shared memory, exposing ports for WebUI (7860), API (8000), router (8002), and OpenAI server (30000). Use this to enter the container and run commands like starting the WebUI.

```bash
docker run --gpus all --shm-size 32g --ipc=host \
  -p 7860:7860 -p 8000:8000 -p 8002:8002 -p 30000:30000 \
  -it mineru:4 /bin/bash

```

--------------------------------

### Start Tecorigin Docker container for MinerU

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Tecorigin

Starts a privileged detached container named 'mineru_docker' with SYS_PTRACE and SYS_ADMIN capabilities, host network, and a large shared memory size, using the Tecorigin vLLM image.

```bash
docker run -dit --name mineru_docker \
    --privileged \
    --cap-add SYS_PTRACE \
    --cap-add SYS_ADMIN \
    --network=host \
    --shm-size=500G \
    mineru:sdaa-vllm-latest \
    /bin/bash

```

--------------------------------

### Build and verify MinerU version

Source: https://opendatalab.github.io/MinerU/zh/quick_start/docker_deployment

Builds the image with an explicit version tag and verifies the installed version inside the container. The assertion fails (non-zero exit) if the actual version does not match the expected one, helping detect tag/version mismatches. Note that interval-based installation is not reproducible by tag alone.

```bash
docker build -t mineru:4.0.0 -f docker/china/Dockerfile .
docker run --rm mineru:4.0.0 python3 -c '
from mineru.version import __version__
expected = "4.0.0"
print(f"actual={__version__}, expected={expected}")
raise SystemExit(0 if __version__ == expected else 1)'

```

--------------------------------

### Start OpenAI-compatible VLM server with mineru-kit vlm-server

Source: https://opendatalab.github.io/MinerU/zh/usage/quick_usage

Starts an OpenAI-compatible VLM service. The --engine auto option selects the VLM engine automatically. Model engine parameters only apply to commands that explicitly declare them.

```bash
mineru-kit vlm-server --engine auto --port 30000

```

--------------------------------

### Start Docker Container for MinerU

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Enflame

Launches a Docker container with root privileges, host networking, and IPC, setting `MINERU_MODEL_SOURCE=local` to enter an interactive bash shell for running MinerU commands.

```bash
docker run -u root --name mineru_docker \
    --network=host \
    --ipc=host \
    --privileged \
    -e MINERU_MODEL_SOURCE=local \
    -it mineru:gcu-vllm-latest \
    /bin/bash

```

--------------------------------

### Distributable source image Dockerfile

Source: https://opendatalab.github.io/MinerU/zh/quick_start/docker_deployment

Defines a distributable source image that copies the source into the image and installs it. The tag should record the commit SHA. After replacing the installed package with another source version, re-verify the pre-downloaded models with `mineru-kit models verify --tier standard --small-backend torch --vlm-engine vllm`.

```dockerfile
FROM mineru:4.0.0
COPY . /src
RUN python3 -m pip install "/src[torch]"

```

--------------------------------

### Check MinerU version constraint for vendor image

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Tecorigin

Run inside the vendor-provided container to verify MinerU is <4. The command prints the installed version and asserts it satisfies '<4'; otherwise it raises an error.

```bash
python -c "from importlib.metadata import version; from packaging.specifiers import SpecifierSet; v = version('mineru'); print(v); assert v in SpecifierSet('<4'), 'Use the vendor image for MinerU <4'"

```

--------------------------------

### Test Platform Information

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/THead

Platform information used for testing the THead PPU acceleration card setup.

```text
os: Ubuntu 22.04   
cpu: INTEL x86_64
ppu: ZW810E  
driver: 1.4.0
docker: 26.1.4

```

--------------------------------

### Enter RAGFlow core container

Source: https://opendatalab.github.io/MinerU/zh/usage/plugin/RagFlow

Run this command to enter the RAGFlow core container after starting the service with docker compose up -d. The command prompt will change from C:\...> to root@...

```bash
docker compose exec ragflow-cpu bash

```

--------------------------------

### Run source-debug container with mounted checkout

Source: https://opendatalab.github.io/MinerU/zh/quick_start/docker_deployment

Runs a source-debug container that mounts the current checkout and installs it in editable mode before parsing a PDF. This container depends on host mounting and is not distributable. Use it to test specific source versions, debug, or reproduce patches.

```bash
docker run --gpus all --shm-size 32g --ipc=host -it \
  -v "$PWD":/src mineru:4.0.0 /bin/bash -c \
  "python3 -m pip install -e '/src[torch]' && mineru-kit parse /src/document.pdf -o /src/document.md"

```

--------------------------------

### 使用 Dockerfile 构建镜像 (vllm)

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Kunlunxin

下载 kxpu.Dockerfile 并使用 docker build 构建 MinerU 的 Kunlunxin vllm 镜像。

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/kxpu.Dockerfile
docker build --network=host -t mineru:kxpu-vllm-latest -f kxpu.Dockerfile .

```

--------------------------------

### Restart RAGFlow to load MinerU

Source: https://opendatalab.github.io/MinerU/zh/usage/plugin/RagFlow

After installing MinerU, exit the container and run this command to restart RAGFlow so it loads the newly installed MinerU.

```bash
docker compose restart ragflow-cpu

```

--------------------------------

### 启动 Docker 容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Kunlunxin

启动 Kunlunxin 加速卡的 Docker 容器，挂载设备、目录并设置环境变量，进入交互式终端。

```bash
docker run -u root --name mineru_docker \
    --device=/dev/xpu0:/dev/xpu0 \
    --device=/dev/xpu1:/dev/xpu1 \
    --device=/dev/xpu2:/dev/xpu2 \
    --device=/dev/xpu3:/dev/xpu3 \
    --device=/dev/xpu4:/dev/xpu4 \
    --device=/dev/xpu5:/dev/xpu5 \
    --device=/dev/xpu6:/dev/xpu6 \
    --device=/dev/xpu7:/dev/xpu7 \
    --device=/dev/xpuctrl:/dev/xpuctrl \
    --net=host \
    --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
    --tmpfs /dev/shm:rw,nosuid,nodev,exec,size=32g \
    --cap-add=SYS_PTRACE \
    -v /home/users/vllm-kunlun:/home/vllm-kunlun \
    -v /usr/local/bin/xpu-smi:/usr/local/bin/xpu-smi \
    -w /workspace \
    -e MINERU_MODEL_SOURCE=local \
    -e MINERU_VLLM_DEVICE=kxpu \
    -it mineru:kxpu-vllm-latest \
    /bin/bash

```

--------------------------------

### 管理本地文档库服务（mineru server）

Source: https://opendatalab.github.io/MinerU/zh/usage/cli_tools

使用 mineru server 管理本地文档库服务，包括启动、状态查询和停止。各命令的权威参数以 mineru <command> --help 为准。

```bash
mineru server start
mineru server status
mineru server stop
```

--------------------------------

### Build PPU Docker Image with vllm

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/THead

Builds the PPU Docker image with vllm support. Requires downloading the ppu.Dockerfile first.

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/ppu.Dockerfile
docker build --network=host -t mineru:ppu-vllm-latest -f ppu.Dockerfile .

```

--------------------------------

### 使用 Dockerfile 构建镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/MooreThreads

下载 musa.Dockerfile 并使用 docker build 构建 MinerU 镜像，适用于 MooreThreads 平台。

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/musa.Dockerfile
docker build --network=host -t mineru:musa-vllm-latest -f musa.Dockerfile .

```

--------------------------------

### Build Docker image with vllm

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Cambricon

Downloads the mlu.Dockerfile, switches the base image from lmdeploy to vllm using sed, and builds the Docker image with vllm support.

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/mlu.Dockerfile
# 将基础镜像从 lmdeploy 切换为 vllm
sed -i -e '3,4s/^/# /' -e '6,7s/^# //' mlu.Dockerfile
docker build --network=host -t mineru:mlu-vllm-latest -f mlu.Dockerfile .

```

--------------------------------

### 启动 Docker 容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Ascend

启动 MinerU 的 Docker 容器，挂载所有 davinci 设备、驱动和工具，并设置必要的环境变量。进入容器后可运行 MinerU 命令或启动服务。

```bash
docker run -u root --name mineru_docker --privileged=true \
    --ipc=host \
    --network=host \
    --device=/dev/davinci0 \
    --device=/dev/davinci1 \
    --device=/dev/davinci2 \
    --device=/dev/davinci3 \
    --device=/dev/davinci4 \
    --device=/dev/davinci5 \
    --device=/dev/davinci6 \
    --device=/dev/davinci7 \
    --device=/dev/davinci_manager \
    --device=/dev/devmm_svm \
    --device=/dev/hisi_hdc \
    -v /var/log/npu/:/usr/slog \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -e VLLM_WORKER_MULTIPROC_METHOD=spawn \
    -e MINERU_MODEL_SOURCE=local \
    -e MINERU_LMDEPLOY_DEVICE=ascend \
    -it mineru:npu-vllm-latest \
    /bin/bash

```

--------------------------------

### GET /v1/usage

Source: https://opendatalab.github.io/MinerU/zh/usage/sdk_api

Retrieves usage information from the self-hosted V1 API server.

```APIDOC
## GET /v1/usage

### Description
Retrieves usage information from the self-hosted V1 API server.

### Method
GET

### Endpoint
/v1/usage

### Response
#### Success Response (200)
- **usage** (object) - Usage details (structure not specified in source)

### Example
```bash
curl http://127.0.0.1:8000/v1/usage
```
```

--------------------------------

### 下载并加载 vllm 镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Biren

下载壁仞提供的 MinerU vllm 镜像并加载到 Docker。链接获取需联系壁仞内部人员。

```bash
wget http://birentech.com/xxx/MinerU/mineru-vllm.tar 链接获取请联系壁仞内部人员（邮箱：MonaLiu@birentech.com）
docker load -i mineru-vllm.tar
```

--------------------------------

### 进入容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/VastAI

进入已启动的 vllm_service 容器。

```bash
sudo docker exec -it vllm_service bash
```

--------------------------------

### 构建 vllm 环境镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/METAX

从 metax 官方仓库拉取基础镜像后，使用 Dockerfile 构建 MinerU 的 vllm 环境镜像。

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/maca.Dockerfile
docker build --network=host -t mineru:maca-vllm-latest -f maca.Dockerfile .

```

--------------------------------

### 设置模型源环境变量并解析文档

Source: https://opendatalab.github.io/MinerU/zh/usage/model_source

环境变量优先于文件配置。此示例设置 MINERU_MODEL_SOURCE 为 modelscope，然后运行 mineru-kit parse 命令解析文档。

```bash
export MINERU_MODEL_SOURCE=modelscope
mineru-kit parse document.pdf -o document.md --tier standard

```

--------------------------------

### 设置环境变量

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/AMD

该命令用于设置两个环境变量，以便在 AMD 加速卡上正常使用 MinerU。

```bash
export MINERU_MODEL_SOURCE=modelscope
export TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1

```

--------------------------------

### ParseResult.save(writer) usage with FileBasedDataWriter

Source: https://opendatalab.github.io/MinerU/zh/reference/output_files

Example of saving a ParseResult using FileBasedDataWriter, which writes markdown.md, middle_json.json, structured_content.json, and images/ assets.

```python
from mineru.parser.writer import FileBasedDataWriter

result.save(FileBasedDataWriter("output"))
```

--------------------------------

### 使用 Dockerfile 构建镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/IluvatarCorex

下载 corex.Dockerfile 并构建名为 mineru:corex-vllm-latest 的镜像。

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/corex.Dockerfile
docker build --network=host -t mineru:corex-vllm-latest -f corex.Dockerfile .

```

--------------------------------

### 下载和验证 NVIDIA/vLLM 部署模型

Source: https://opendatalab.github.io/MinerU/zh/usage/model_source

在无 GPU 的构建机上为目标后端下载模型，必须显式指定 small-backend 为 torch、vlm-engine 为 vllm。

```bash
mineru-kit models download --tier standard --small-backend torch --vlm-engine vllm --source modelscope
mineru-kit models verify --tier standard --small-backend torch --vlm-engine vllm

```

--------------------------------

### 下载和验证 CPU 小模型与 llama.cpp 组合

Source: https://opendatalab.github.io/MinerU/zh/usage/model_source

显式指定 small-backend 为 onnx、vlm-engine 为 llama-cpp，从 Hugging Face 下载并验证 Standard 模型。

```bash
mineru-kit models download --tier standard --small-backend onnx --vlm-engine llama-cpp --source huggingface
mineru-kit models verify --tier standard --small-backend onnx --vlm-engine llama-cpp

```

--------------------------------

### Check Compose config and view logs

Source: https://opendatalab.github.io/MinerU/zh/quick_start/docker_deployment

Checks the Compose configuration and views logs for the mineru-webui service. When upgrading from an old Compose setup, change the gradio profile to webui and the service name to mineru-webui.

```bash
docker compose -f docker/compose.yaml --profile webui config
docker compose -f docker/compose.yaml logs mineru-webui

```

--------------------------------

### 设置环境变量并解析文档（torch/vllm/local）

Source: https://opendatalab.github.io/MinerU/zh/usage/model_source

运行解析前使用与下载相同的组合，设置小模型后端、VLM 引擎和模型源环境变量，然后执行解析命令。

```bash
export MINERU_MODEL_SMALL_BACKEND=torch
export MINERU_MODEL_VLM_ENGINE=vllm
export MINERU_MODEL_SOURCE=local
mineru-kit parse document.pdf -o document.md --tier standard

```

--------------------------------

### 启动容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/VastAI

启动 vllm_service 容器，设置共享内存、网络等参数。

```bash
sudo docker run -it \
    --privileged=true \
    --shm-size=256g \
    --name vllm_service \
    --ipc=host \
    --network=host \
    harbor.vastaitech.com/ai_deliver/vllm_vacc:VVI-25.12.SP2 bash
```

--------------------------------

### Build MinerU 4.0 Docker image

Source: https://opendatalab.github.io/MinerU/zh/quick_start/docker_deployment

Builds the MinerU 4.0 Docker image from the repository root using the China Dockerfile. The base image retains vLLM 0.21.0 and installs mineru[torch]>=4.0,<5. Default CUDA is 13.0; for CUDA 12.9, enable the commented v0.21.0-cu129 base image in the Dockerfile.

```bash
docker build -t mineru:4 -f docker/china/Dockerfile .

```

--------------------------------

### 构建 vllm 镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Ascend

下载 npu.Dockerfile 并构建 vllm 版本的 MinerU 镜像。默认 tag 为 A2 适配版本，如需 A3 或 Atlas 300I Duo 需修改 Dockerfile 第三行的 tag。

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/npu.Dockerfile
docker build --network=host -t mineru:npu-vllm-latest -f npu.Dockerfile .

```

--------------------------------

### 使用 Dockerfile 构建镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Hygon

下载 dcu.Dockerfile 并构建名为 mineru:dcu-vllm-latest 的 Docker 镜像。

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/dcu.Dockerfile
docker build --network=host -t mineru:dcu-vllm-latest -f dcu.Dockerfile .

```

--------------------------------

### 启动 API 服务器

Source: https://opendatalab.github.io/MinerU/zh/quick_start

启动 API 服务器，提供 OpenAPI 文档。

```bash
mineru-kit api-server --host 127.0.0.1 --port 8000 --tier standard

```

--------------------------------

### mineru-kit parse 批量解析

Source: https://opendatalab.github.io/MinerU/zh/usage/cli_tools

使用 mineru-kit parse 进行无状态批量解析，支持本地解析和显式 V1 远程解析。tier、backend、页范围和输出参数以 mineru-kit parse --help 为准。

```bash
mineru-kit parse report.pdf -o report.md --tier standard
mineru-kit parse ./documents -o ./output --format zip
```

--------------------------------

### 在 qwen2_vl.py 中添加 Triton 卷积导入

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/AMD

在 vllm 的 qwen2_vl.py 文件第 33 行后添加 from .qwen2_vl_vision_kernels import triton_conv3d_patchify，以启用 Triton 卷积优化。

```python
from collections.abc import Iterable, Mapping, Sequence
from functools import partial
from typing import Annotated, Any, Callable, Literal, Optional, Union

import torch
import torch.nn as nn
import torch.nn.functional as F
from .qwen2_vl_vision_kernels import triton_conv3d_patchify
```

--------------------------------

### 启动 Docker 容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/MooreThreads

启动 MinerU Docker 容器，设置 MooreThreads 相关环境变量并进入交互式终端。

```bash
docker run -u root --name mineru_docker \
    --network=host \
    --ipc=host \
    --shm-size=80g \
    --privileged \
    -e MTHREADS_VISIBLE_DEVICES=all \
    -e MINERU_VLLM_DEVICE=musa \
    -e MINERU_MODEL_SOURCE=local \
    -it mineru:musa-vllm-latest \
    /bin/bash

```

--------------------------------

### 定位 vllm 安装位置

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/AMD

使用 pip show vllm 查看 vllm 的安装路径，以便后续修改 qwen2_vl.py 文件。

```bash
pip show vllm
```

--------------------------------

### 启动 Docker 容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/METAX

启动 MinerU 的 Docker 容器，进入交互式终端。可根据需要替换镜像标签为 lmdeploy 版本。

```bash
docker run --ipc host \
   --cap-add SYS_PTRACE \
   --privileged=true \
   --device=/dev/mem \
   --device=/dev/dri \
   --device=/dev/mxcd \
   --device=/dev/infiniband \
   --group-add video \
   --network=host \
   --shm-size '100gb' \
   --ulimit memlock=-1 \
   --security-opt seccomp=unconfined \
   --security-opt apparmor=unconfined \
   --name mineru_docker \
   -v /datapool:/datapool \
   -e MINERU_MODEL_SOURCE=local \
   -e MINERU_LMDEPLOY_DEVICE=maca \
   -it mineru:maca-vllm-latest \
   /bin/bash

```

--------------------------------

### 启动 Docker 容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/IluvatarCorex

启动名为 mineru_docker 的容器，进入交互式终端，可运行 MinerU 命令。也可替换 /bin/bash 为服务启动命令来启动 MinerU 服务。

```bash
docker run --name mineru_docker \
   -v /usr/src:/usr/src \
   -v /lib/modules:/lib/modules \
   -v /dev:/dev \
   --privileged \
   --cap-add=ALL \
   --pid=host \
   --group-add video \
   --network=host \
   --shm-size '400gb' \
   --ulimit memlock=-1 \
   --security-opt seccomp=unconfined \
   --security-opt apparmor=unconfined \
   -e VLLM_ENFORCE_CUDA_GRAPH=1 \
   -e MINERU_MODEL_SOURCE=local \
   -e MINERU_VLLM_DEVICE=corex \
   -it mineru:corex-vllm-latest \
   /bin/bash

```

--------------------------------

### 启动 Docker 容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Hygon

启动一个交互式 Docker 容器，挂载 Hygon 加速卡相关设备并设置环境变量 MINERU_MODEL_SOURCE=local。

```bash
docker run -u root --name mineru_docker \
    --network=host \
    --ipc=host \
    --shm-size=16G \
    --device=/dev/kfd \
    --device=/dev/mkfd \
    --device=/dev/dri \
    -v /opt/hyhal:/opt/hyhal \
    --group-add video \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    -e MINERU_MODEL_SOURCE=local \
    -it mineru:dcu-vllm-latest \
    /bin/bash

```

--------------------------------

### 无状态转换与文档库解析并显式等待

Source: https://opendatalab.github.io/MinerU/zh/usage/cli_tools

两个命令分别演示无状态转换（mineru-kit parse）和文档库解析并显式等待 10 分钟（mineru parse --wait 600）。等待超时是客户端期限，不是任务失败；解析会在文档库中继续执行。

```bash
# 无状态转换整份文档
mineru-kit parse document.pdf -o document.md --tier standard
```

```bash
# 文档库解析并完整导出，显式等待 10 分钟
mineru parse document.pdf --pages all -o document.md --wait 600
```

--------------------------------

### 激活虚拟环境 (Linux/macOS)

Source: https://opendatalab.github.io/MinerU/zh/quick_start

在 Linux 或 macOS 上激活已创建的虚拟环境。

```bash
source .venv/bin/activate

```

--------------------------------

### 通过 router 管理多卡 fastapi 服务

Source: https://opendatalab.github.io/MinerU/zh/usage/advanced_cli_parameters

使用 router 在4张显卡上启动 fastapi 服务并统一管理，通过 --local-gpus 指定 GPU 设备。

```bash
mineru-kit router --host 127.0.0.1 --port 8002 --local-gpus 0,1,2,3

```

--------------------------------

### Download and load the Tecorigin vLLM image

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Tecorigin

Downloads the vendor Docker image for the vLLM environment and loads it into Docker.

```bash
wget http://wb.tecorigin.com:8082/repository/teco-customer-repo/Course/MinerU/mineru-vllm.tar

docker load -i mineru-vllm.tar

```

--------------------------------

### 多卡启动两个 api-server 服务

Source: https://opendatalab.github.io/MinerU/zh/usage/advanced_cli_parameters

在多张显卡上，分别在卡0和卡1启动两个 fastapi 服务（api-server），并监听不同端口。

```bash
# 在终端1中
CUDA_VISIBLE_DEVICES=0 mineru-kit api-server --host 127.0.0.1 --port 8000
# 在终端2中
CUDA_VISIBLE_DEVICES=1 mineru-kit api-server --host 127.0.0.1 --port 8001

```

--------------------------------

### 启动 V1 API Server（mineru-kit api-server）

Source: https://opendatalab.github.io/MinerU/zh/usage/cli_tools

启动 V1 API Server，监听 127.0.0.1:8000。在浏览器打开 http://127.0.0.1:8000/docs 查看自动生成的 OpenAPI 文档。当前服务接口统一位于 /v1/*；已删除的 /file_parse 和 /tasks 不再提供。

```bash
mineru-kit api-server --host 127.0.0.1 --port 8000 --tier standard
```

--------------------------------

### 启动 Gradio WebUI（mineru-kit webui）

Source: https://opendatalab.github.io/MinerU/zh/usage/cli_tools

启动 Gradio WebUI，监听 127.0.0.1:7860。未传 --api-url 时，Gradio 会托管 loopback mineru-kit api-server；传入后只连接指定的 V1 服务。mineru-webui 保留为命令名兼容别名，接受相同的新版参数。

```bash
mineru-kit webui --server-name 127.0.0.1 --server-port 7860
```

--------------------------------

### 拉取 vllm_vacc 基础镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/VastAI

从 VastAI 仓库拉取 vllm_vacc 基础镜像。

```bash
sudo docker pull harbor.vastaitech.com/ai_deliver/vllm_vacc:VVI-25.12.SP2
```

--------------------------------

### 查看 mineru_vl_utils 安装位置

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/AMD

该命令用于查看 mineru_vl_utils 包的安装位置，以便后续修改其源码文件。

```bash
pip show mineru_vl_utils

```

--------------------------------

### Show effective runtime with mineru-kit models show

Source: https://opendatalab.github.io/MinerU/zh/usage/quick_usage

Displays the effective small backend and VLM engine, along with the configuration source for each value. It reports model readiness but does not fail if model files are missing; use mineru-kit models verify for a non-zero exit code when model files are incomplete. Neither command performs inference.

```bash
mineru-kit models show

```

--------------------------------

### 测试平台信息

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Biren

列出本指南测试使用的平台信息，包括操作系统、CPU、GPU、驱动和 Docker 版本。

```text
os: Ubuntu 22.04.4 LTS
cpu: Intel x86-64
gpu: Biren 106C
driver: 1.10.0
docker: 28.0.4
```

--------------------------------

### 启动 Docker 容器

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Biren

启动名为 mineru_docker 的 Docker 容器，设置环境变量以使用本地模型和 supa 设备，并进入交互式终端。

```bash
docker run -it --name mineru_docker \
    --privileged \
    --network=host \
    --shm-size=100G \
    -e MINERU_MODEL_SOURCE=local \
    -e MINERU_DEVICE_MODEL=supa \
    -e SHAPE_TRANSFORM_GRANK=true \
    mineru:biren-vllm-latest \
    /bin/bash
```

--------------------------------

### 多卡启动两个 vlm-server 服务

Source: https://opendatalab.github.io/MinerU/zh/usage/advanced_cli_parameters

在多张显卡上，分别在卡0和卡1启动两个 openai-server 服务（vlm-server），并监听不同端口。

```bash
# 在终端1中
CUDA_VISIBLE_DEVICES=0 mineru-kit vlm-server --engine vllm --port 30000
# 在终端2中
CUDA_VISIBLE_DEVICES=1 mineru-kit vlm-server --engine vllm --port 30001

```

--------------------------------

### 安装 mineru[full] 扩展包

Source: https://opendatalab.github.io/MinerU/zh/quick_start/extension_modules

使用 uv 安装包含完整推理引擎（Linux 上为 vLLM，Windows 上为 LMDeploy）的 MinerU 扩展包，适用于高吞吐部署。

```bash
uv pip install -U "mineru[full]>=4.0,<5"

```

--------------------------------

### 启动 WebUI 服务

Source: https://opendatalab.github.io/MinerU/zh/quick_start

启动本地 WebUI，默认托管本地 V1 API 服务。

```bash
mineru-kit webui --server-name 127.0.0.1 --server-port 7860

```

--------------------------------

### 使用 render_pdf 和 render 生成 PDF

Source: https://opendatalab.github.io/MinerU/zh/reference/output_files

展示如何通过 mineru.render 模块的 render_pdf 和 render 函数生成 PDF。render_pdf 使用 PdfLayout.ORIGINAL 布局，render 使用 PdfLayout.REFLOW 布局。

```python
from mineru.render import PdfLayout, PdfRenderOptions, RenderFormat, render, render_pdf

pdf_bytes = render_pdf(result.middle_json, layout=PdfLayout.ORIGINAL)
pdf_bytes = render(result.middle_json, RenderFormat.PDF,
                   options=PdfRenderOptions(layout=PdfLayout.REFLOW))

```

--------------------------------

### 测试平台信息

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Kunlunxin

列出本指南测试使用的平台信息，包括操作系统、CPU、XPU、驱动和 Docker 版本。

```text
os: Ubuntu 22.04.5 LTS  
cpu: Intel x86-64
xpu: P800
driver: 515.58
docker: 20.10.5

```

--------------------------------

### 原生文档解析与批量转换

Source: https://opendatalab.github.io/MinerU/zh/quick_start

解析单个 docx 文件或批量转换目录，输出为 Markdown 或 zip 格式。

```bash
mineru-kit parse report.docx -o report.md --tier flash
mineru-kit parse ./documents -o ./output --format zip

```

--------------------------------

### 安装 mineru[torch] 扩展包

Source: https://opendatalab.github.io/MinerU/zh/quick_start/extension_modules

使用 uv 安装包含 Torch 支持的 MinerU 扩展包，适用于使用 Torch 小模型的场景。

```bash
uv pip install -U "mineru[torch]>=4.0,<5"

```

--------------------------------

### Connect to self-deployed V1 API with MinerUApiParser

Source: https://opendatalab.github.io/MinerU/zh/usage/sdk_api

Creates a `MinerUApiParser` pointing to a local API server, parses a PDF with page range '1-3', and prints the markdown. The `api_url` is the service root before `/v1`; API key can be read from config or environment via `MINERU_API_KEY`.

```python
from mineru.parser import MinerUApiParser

parser = MinerUApiParser(
    api_url="http://127.0.0.1:8000",
    api_key="",
    tier="standard",
    include_images=True,
)
result = parser.parse("document.pdf", page_range="1-3")
print(result.markdown())

```

--------------------------------

### 4.0 配置示例：model 配置

Source: https://opendatalab.github.io/MinerU/zh/reference/migration_4

4.0 使用 $MINERU_HOME/config.yaml 配置，旧 mineru.json 不再读取。model.stack、MINERU_MODEL_STACK 和 --stack 已移除，改为独立配置。

```yaml
model:
  source: auto
  base_dir: ~/.mineru/models
  small_backend: auto
  vlm:
    engine: auto

```

--------------------------------

### 手动安装 aiter、vllm 和 amd-smi

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/AMD

从源码构建 aiter 和 vllm，并安装 amd-smi 等依赖。需要根据 GPU 架构设置 PYTORCH_ROCM_ARCH（例如 gfx1100），可通过 rocminfo | grep gfx 查询。

```bash
#手动安装aiter，vllm，amd-smi等，自行找一个位置clone，然后进入该目录吧
git clone --recursive https://github.com/ROCm/aiter.git
cd aiter
git submodule sync; git submodule update --init --recursive
python setup.py develop
cd ..
git clone https://github.com/vllm-project/vllm.git
cd vllm/
cp -r /opt/rocm/share/amd_smi ~/Pytorch/vllm/
pip install amd_smi/
pip install --upgrade numba \
    scipy \
    huggingface-hub[cli,hf_transfer] \
    setuptools_scm
pip install -r requirements/rocm.txt
export PYTORCH_ROCM_ARCH="gfx1100"   #根据自己的GPU架构 rocminfo | grep gfx
python setup.py develop
```

--------------------------------

### 构建 lmdeploy 环境镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/METAX

使用 Dockerfile 构建 lmdeploy 环境镜像，通过 sed 命令将基础镜像从 vllm 切换为 lmdeploy。

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/maca.Dockerfile
# 将基础镜像从 vllm 切换为 lmdeploy
sed -i '3s/^/# /' maca.Dockerfile && sed -i '5,6s/^# //' maca.Dockerfile
docker build --network=host -t mineru:maca-lmdeploy-latest -f maca.Dockerfile .

```

--------------------------------

### Connect WebUI to self-deployed API with mineru-kit webui

Source: https://opendatalab.github.io/MinerU/zh/usage/sdk_api

Launches the WebUI and connects it to the same API server address. This allows using the WebUI against the self-deployed V1 service.

```bash
mineru-kit webui --api-url http://127.0.0.1:8000

```

--------------------------------

### Build Docker Image with gcu.Dockerfile

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Enflame

Downloads the GCU-specific Dockerfile and builds the MinerU image with the tag `mineru:gcu-vllm-latest`.

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/gcu.Dockerfile
docker build --network=host -t mineru:gcu-vllm-latest -f gcu.Dockerfile .

```

--------------------------------

### 测试平台信息

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/VastAI

列出测试平台的操作系统、CPU、GPU、torch、vllm 等版本信息。

```text
os: Ubuntu-22.04.3-LTS-x86_64
cpu: Hygon C86-4G
gpu: VA16 / VA1L / VA10L
torch: 2.8.0+cpu
torch-vacc: 1.3.3.777
vllm: 0.11.1.dev0+gb8b302cde.d20251030.cpu
vllm-vacc: 0.11.0.777
driver: 00.25.12.30 d3_3_v2_9_a3_1 a76bf37 20251230
docker: 28.1.1
```

--------------------------------

### 无状态解析单个 PDF 文件

Source: https://opendatalab.github.io/MinerU/zh/quick_start

使用 mineru-kit parse 将 PDF 解析为 Markdown，指定输出文件。

```bash
mineru-kit parse document.pdf -o document.md --tier standard

```

--------------------------------

### 使用 vlm-engine 方式启动 MinerU

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/VastAI

设置模型源为 modelscope，并以 vlm-engine 方式启动解析任务。

```bash
export MINERU_MODEL_SOURCE=modelscope

# step1, 以`vlm-engine`方式启动MinerU解析任务
mineru -p image.png \
-o ./output \
-b vlm-engine \
--http-timeout 1200 \
--tensor-parallel-size 2 \
--enforce_eager \
--trust-remote-code \
--max-model-len 16384
```

--------------------------------

### 启动 Router 与 VLM Server（mineru-kit router / vlm-server）

Source: https://opendatalab.github.io/MinerU/zh/usage/cli_tools

启动 Router 和 VLM Server。mineru-router 保留为 mineru-kit router 的命令名别名。Router 只暴露 V1 API，并且只接受文档中声明的 worker 参数。

```bash
mineru-kit router --host 127.0.0.1 --port 8002 --local-gpus auto
mineru-kit vlm-server --engine auto --port 30000
```

--------------------------------

### 构建 lmdeploy 镜像

Source: https://opendatalab.github.io/MinerU/zh/usage/acceleration_cards/Ascend

下载 npu.Dockerfile 并修改基础镜像为 lmdeploy 版本，然后构建镜像。适用于 Atlas A2 和 Atlas 800I A2 系列设备。

```bash
wget https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/npu.Dockerfile
# 将基础镜像从 vllm 切换为 lmdeploy
sed -i '3s/^/# /' npu.Dockerfile && sed -i '5,6s/^# //' npu.Dockerfile
docker build --network=host -t mineru:npu-lmdeploy-latest -f npu.Dockerfile .

```

--------------------------------

### CUDA_VISIBLE_DEVICES 基本用法

Source: https://opendatalab.github.io/MinerU/zh/usage/advanced_cli_parameters

在命令行开头添加 CUDA_VISIBLE_DEVICES 环境变量来指定可见的 GPU 设备。适用于模型服务与解析命令，不适用于 mineru-router。

```bash
CUDA_VISIBLE_DEVICES=1 mineru-kit parse <input_path> -o <output_path>

```
Tokens:
Raw