Skip to content

MinerU安装与使用 ​

MinerU安装 ​

介绍 ​

MinerU 是一款智能文档解析工具,专注于将复杂的 PDF 和 Office 文档高质量地转换为机器可读的格式(如 Markdown、JSON),以便用于大模型训练、数据分析和文档数字化等场景。

  • 比LlamaIndex 默认解析器效果好
  • 建议使用GPU加速,纯 CPU 环境建议至少 16 核 CPU 和 8GB 内存
  • MinerU 4.0 支持文档格式
类别支持格式
PDF.pdf(支持文本型、扫描型、混合型)
图片.png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff, .jp2
Word.doc, .docx
PowerPoint.ppt, .pptx
Excel.xls, .xlsx
Rich Text.rtf
OpenDocument.odt, .ods, .odp
电子书.epub
OFD.ofd
网页/归档.html, .htm, .shtml, .mhtml, .mht
表格.csv, .tsv

准备环境 ​

安装 UV 与 Python

bash
# 全局安装:打开 Window CMD 运行
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 查看是否安装成功
uv --version

通过 UV 安装 Python

bash
# 查看可用python版本
uv python list

# 安装指定版本
uv python install 3.12.13

# (可选)设置全局默认 Python 版本为 3.12
uv python pin --global 3.12.13

安装MinerU ​

新建项目目录,例如 my-mineru 。进入目录,打开终端或CMD运行

bash
# 创建虚拟环境
cd my-mineru
uv venv --python 3.12.13
uv init

# 安装MinerU
uv add "mineru>=4.0,<5"
# 更新
uv pip install -U "mineru>=4.0,<5"

配置MinerU

bash
# 激活 uv 环境
.venv\Scripts\activate # Windows 环境
# source .venv/bin/activate # Linux/macOS 环境

# 下载模型,并验证
mineru-kit models download --tier basic --source modelscope
mineru-kit models download --tier standard --source modelscope
mineru-kit models verify --tier basic
mineru-kit models verify --tier standard
mineru-kit models show

MinerU使用 ​

WebUI使用 ​

启动WebUI

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

浏览器访问:http://127.0.0.1:7860/

image-20261012180536860

(如果解析等级 standard 报错,设置为 basic)

API 服务使用 ​

启动API 服务

bash
mineru-kit api-server --host 0.0.0.0 --port 8100 --tier standard

访问 http://127.0.0.1:8100/docs 查看自动生成的 OpenAPI 接口文档

使用 SDK 调用 MinerU API

python
from pathlib import Path
from mineru.parser import MinerUApiParser

parser = MinerUApiParser(
    api_url="http://127.0.0.1:8100",
    api_key="",
    tier="flash",  # flash/basic/standard/advanced
    include_images=True,
)
result = parser.parse("./data/西安交通大学.pdf", page_range="1-3")

# 查看 Markdown 结果
print(result.markdown())
Path("result.md").write_text(result.markdown(), encoding="utf-8")

# 查看 JSON 结果
# print(result.to_json())
# Path("result.json").write_text(result.to_json(), encoding="utf-8")

命令行直接使用 ​

bash
mineru-kit parse document.pdf -o document --tier flash
mineru-kit parse document.pdf -o document --tier basic
mineru-kit parse 西安交通大学.pdf -o document --tier standard # 如果报错,尝试Docker安装

文档解析效果 ​

MinerU 与 LlamaIndex 效果对比

python
########## MinerU 加载 PDF 文档
from pathlib import Path
from mineru.parser import MinerUApiParser

parser = MinerUApiParser(
    api_url="http://127.0.0.1:8100",
    api_key="",
    tier="basic",  # flash/basic/standard/advanced
    include_images=False,
)
result = parser.parse("./data/跨境电商数据Q&A_part1.xlsx")

# 查看 Markdown 结果
# print(result.markdown())
Path("./data/result_mineru.md").write_text(result.markdown(), encoding="utf-8")

########## 效果对比
from llama_index.core import SimpleDirectoryReader
from llama_index.readers.file import (
    PptxReader,
    DocxReader,
    PandasExcelReader,
    PDFReader,
)

file_extractor = {
    ".pptx": PptxReader(),
    ".docx": DocxReader(),
    ".xlsx": PandasExcelReader(),
    ".pdf": PDFReader(),
}

# 加载指定文件
documents = SimpleDirectoryReader(
    input_files=["./data/跨境电商数据Q&A_part1.xlsx"], file_extractor=file_extractor
).load_data()
print(len(documents))
print(documents[0].metadata)

# 将内容保存到文件
# Path("./data/result_llama.md").write_text(documents[0].text, encoding="utf-8")

# 将内容保存到文件:多个 Document
combined_text = "\n\n".join([doc.get_content() for doc in documents])
Path("./data/result_llama.md").write_text(combined_text, encoding="utf-8")

Docker方式安装 ​

准备环境 ​

安装Docker 环境,过程略。可参考《WSL与Docker》

安装MinerU ​

Dockerfile 包含构建 Docker 镜像所需的全部指令。

  • --concurrency 2:Job 级调度并发(应用层),这个参数是 mineru-kit api-server 的 CLI 选项,控制的是同时运行的解析任务(Job)数量。
dockerfile
# 详见devops\docker\mineru\Dockerfile

构建与运行命令

  • OMP_NUM_THREADS:控制 OpenMP 并行区域的默认线程数。默认为4

  • MKL_NUM_THREADS:专门控制 Intel MKL(数学核心库)使用的线程数。默认为4

  • MINERU_INTRA_OP_NUM_THREADS:控制单个算子内部的并行线程数(intra-op)。默认为4

  • MINERU_INTER_OP_NUM_THREADS:控制不同算子之间的并行度(inter-op),即同时可以有多少个相互独立的算子并行执行。默认为4

    • 建议将上述变量设置为 CPU 物理核数(非CPU逻辑核数),提升单任务性能。查看CPU物理和逻辑核数:lscpu
  • MINERU_API_MAX_CONCURRENT_REQUESTS=2:API 请求层并发(接入层),服务端使用的是信号量阻塞等待机制,而非“超限即拒绝”。例如:8 个请求都被 API 接收并返回了 202,但它们并不是全部在同时推理。实际有且仅有 2 个任务在执行,其余 6 个在队列中安静等待。

bash
# 创建目录
mkdir /opt/mineru && cd /opt/mineru
# 将上面 Dockerfile 放在该目录

# 构建
docker build -t mineru-cpu:1.0.0 .

# 运行
docker run -d --name mineru-cpu --restart unless-stopped \
  -p 8100:8100 \
  -e MINERU_TIER=standard \
  -e OMP_NUM_THREADS=12 \
  -e MKL_NUM_THREADS=12 \
  -e MINERU_INTRA_OP_NUM_THREADS=12 \
  -e MINERU_INTER_OP_NUM_THREADS=12 \
  -e MINERU_API_MAX_CONCURRENT_REQUESTS=2 \
  mineru-cpu:1.0.0

GPU加速 ​

MinerU模型 ​

MinerU 3 架构

模型体系对应后端具体模型 / 架构关键特点
专用小模型组合Pipeline 模式布局检测:DocLayout-YOLO (默认)、YOLO-v10、LayoutLMv3 公式检测:YOLOv8 公式识别:UniMERNet OCR:PaddleOCR 表格识别:PaddleOCR+TableMaster, StructEqTable模块化,专精单项任务,稳定可控
多模态大模型 (VLM)VLM / Hybrid 模式MinerU2.5-Pro (1.2B 参数)-18 基于 Qwen2-VL 架构 (Qwen2VLForConditionalGeneration)-18端到端解析,精度 SOTA,单个模型完成复杂理解

MinerU 4 最重要的架构调整,是用一套 “解析档位(Tier)” 系统取代了之前混杂的“后端(Backend)”概念。

  • 小模型后端:可在 onnx 和 torch 之间选择。
  • VLM 引擎:可在 llama-cpp、vllm、lmdeploy、mlx 之间独立选择。
档位 (Tier)对应解析模式核心组件适用场景
basic原 Pipeline 模式小模型(ONNX 或 Torch)速度优先,资源占用低,可纯 CPU 运行
standard原 Hybrid 模式小模型 + vLLM 加速的 VLM官方默认,平衡速度与精度
advanced原 VLM 模式整页 VLM 大模型精度优先,处理最复杂的版面
bash
mineru-kit models show

# CPU环境下,输出 ...
生效的小模型后端: onnx
生效的 VLM 引擎: llama-cpp
仓库:
  MinerU-4_models_torch: 缺失
  MinerU-4_models_onnx: 就绪
  MinerU2.5-Pro-2605-1.2B: 缺失
  MinerU2.5-Pro-2605-1.2B-GGUF: 就绪
模型档位:
  basic: MinerU-4_models_onnx
  standard: MinerU-4_models_onnx, MinerU2.5-Pro-2605-1.2B-GGUF

torch加速 ​

使用 torch 加速 MinerU-4_models_torch 模型

  • --concurrency 1 为最优
bash
mkdir /opt/my-mineru
cd /opt/my-mineru
uv venv -p 3.12.13
source .venv/bin/activate

# 安装 pytorch
uv pip install torch torchvision torchaudio \
  --index-url https://download.pytorch.org/whl/rocm7.2 \
  --upgrade --force-reinstall
# 查看 pytorch 是否正确安装:应包含 "+rocm7.2" 之类的后缀
uv pip list

# 安装 mineru
uv pip install "mineru[torch]>=4.0,<5"

# 下载 Torch 格式的小模型资源包
mineru-kit models download MinerU-4_models_torch --source modelscope
mineru-kit models show

# 开启服务
# 可选: export MINERU_MODEL_SMALL_BACKEND=torch
# 必须执行下面命令,否则内存一直增长
export MINERU_MALLOC_TRIM=1
mineru-kit api-server --host 0.0.0.0 --port 8600 --tier standard --concurrency 1 --preload-models --retention-seconds 600

(可选)启动负载均衡才是真正的并行,--worker-concurrency 2/4/8 只会更慢

  • 需要足够的内存和显存:1个Worker 进程,占1份显存和内存
  • --preload-models \按需设置
bash
cd /opt/my-mineru
source .venv/bin/activate

# 启动2个独立的 Worker 进程,占用2份显存和内存
export MINERU_MALLOC_TRIM=1
mineru-router \
  --host 0.0.0.0 \
  --port 8800 \
  --local-gpus 0,0 \
  --worker-tier standard \
  --worker-concurrency 1 \
  --retention-seconds 600

vLLM加速 ​

使用 vLLM 加速 MinerU2.5-Pro-2605-1.2B

bash
# 下载模型
mineru-kit models download --tier standard --small-backend torch --vlm-engine vllm --source modelscope
mineru-kit models show

# 方式一:设置环境变量(推荐,写入你的启动脚本)
export MINERU_MODEL_VLM_ENGINE=vllm

排错 ​

注意内存只增不减问题

bash
# 先找到 mineru api-server 的 PID
pgrep -af mineru

# 假设 PID 是 12345,查看其内存
ps -p 12345 -o pid,rss,vsz,pmem,cmd

解决方案:设置变量

bash
# 必须执行下面命令,否则内存一直增长
export MINERU_MALLOC_TRIM=1