外观
MinerU安装与使用
MinerU安装
介绍
MinerU 是一款智能文档解析工具,专注于将复杂的 PDF 和 Office 文档高质量地转换为机器可读的格式(如 Markdown、JSON),以便用于大模型训练、数据分析和文档数字化等场景。
- 比LlamaIndex 默认解析器效果好
- 建议使用GPU加速,纯 CPU 环境建议至少 16 核 CPU 和 8GB 内存
- MinerU 4.0 支持文档格式
| 类别 | 支持格式 |
|---|---|
.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 showMinerU使用
WebUI使用
启动WebUI
bash
mineru-kit webui --server-name 0.0.0.0 --server-port 7860浏览器访问:http://127.0.0.1:7860/

(如果解析等级 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 并行区域的默认线程数。默认为4MKL_NUM_THREADS:专门控制 Intel MKL(数学核心库)使用的线程数。默认为4MINERU_INTRA_OP_NUM_THREADS:控制单个算子内部的并行线程数(intra-op)。默认为4MINERU_INTER_OP_NUM_THREADS:控制不同算子之间的并行度(inter-op),即同时可以有多少个相互独立的算子并行执行。默认为4- 建议将上述变量设置为 CPU 物理核数(非CPU逻辑核数),提升单任务性能。查看CPU物理和逻辑核数:
lscpu
- 建议将上述变量设置为 CPU 物理核数(非CPU逻辑核数),提升单任务性能。查看CPU物理和逻辑核数:
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.0GPU加速
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-GGUFtorch加速
使用 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 600vLLM加速
使用 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