MinerU 本地部署教程（Windows）

mineru在线体验demo：https://mineru.net/OpenSourceTools/Extractor

MinerU 与 vllm-mineru 的完整介绍，涵盖定义、核心区别及服务器配置要求：

一、MinerU（标准版 / Pipeline 模式）

是什么

MinerU 是一款文档解析工具 ，主打 PDF 结构化提取。它通过内置的 OCR + 布局分析流水线，自动识别文档中的标题、段落、表格、图片、公式等元素，最终输出结构化的 Markdown，并附带文本的坐标位置信息（页码、偏移量）。

核心能力

支持普通可复制 PDF、扫描件 PDF
表格提取、公式识别、图片说明提取
保留原始排版结构，输出 Markdown
附带坐标信息，可满足"高亮跳转原文"的需求

适用场景

标书解析、图文混排文档
常规扫描件、标准表格文档
主力解析方案，适合大部分日常文档

短板

复杂手写、模糊扫描件识别较弱
扭曲图纸、密集框图容易出错

二、vllm-mineru（VLM 多模态增强版）

是什么

vllm-mineru 是 MinerU 的多模态视觉大模型增强版本 。它不再使用传统的"切图块 + 分别识别"流水线，而是将整页文档图片直接输入给 VLM（视觉语言模型），让模型全局理解页面布局、线条、表格、框图及图文位置关系。

注：名字中的 "vllm" 指的是使用 vLLM 推理框架来加速 VLM 多模态模型，vllm 本身不是多模态模型。

核心能力

复杂表格：跨行跨列、线条残缺、虚线表格识别明显增强
图纸 / 流程图：既能看懂线条框图，又能读出图内小字
疑难扫描件：倾斜、模糊、底纹干扰的文档识别更准
图文混排：自动区分图片、标题、注释，Markdown 结构更合理

适用场景

暗标、复杂排版、手绘表格
模糊扫描件、扭曲图纸、密集框图
兜底解析方案，仅用于原版 MinerU 识别失败的疑难文档

三、两者核心区别

维度	MinerU（标准版）	vllm-mineru（增强版）
技术路线	传统 CV 流水线：布局检测 → OCR → 表格识别 → 公式识别，分块孤立处理	VLM 端到端多模态：整页图片 + 文本提示词同时输入，全局视觉理解
识别方式	先切图块，再分别 OCR 识别	把整页喂给多模态大模型，边看边理解
识别精度	常规文档足够，复杂场景易出错	复杂表格、图纸、模糊件识别精度更高
输出格式	Markdown + bbox 坐标	Markdown
资源消耗	较低	较高（需 GPU/NPU）
定位	主力解析，对标基础文档转换服务	兜底增强，处理疑难文档

一句话总结区别：

MinerU：先切图块，再分别 OCR（传统流水线）

vllm-mineru：整页看图理解文字和排版（VLM 端到端）

四、服务器配置要求

1. MinerU（Pipeline 流水线模式）------ 主力方案

硬件类型	要求	说明
CPU	✅ 支持纯 CPU 运行	速度慢，测试可用，小并发可生产使用
NVIDIA GPU	✅ 首选，显存 ≥ 4GB	T4 / A10 / A100 / L4 等
Apple Silicon	✅ 支持 MPS	Mac M 系列芯片
国产 NPU	✅ 支持（v2.7+）	昇腾、寒武纪、燧原、昆仑芯、海光 DCU、壁仞、沐曦等 11 家国产卡

特点：兼容性最强，CPU / GPU / NPU 全部通吃，资源占用适中，工程稳定。

2. vllm-mineru（VLM-Engine 模式）------ 兜底方案

硬件类型	要求	说明
CPU	❌ 不支持纯 CPU 运行	必须 AI 加速硬件
NVIDIA GPU	✅ 显存 ≥ 8GB	最低门槛
国产 NPU	✅ 推荐昇腾 910B / A2	有成熟 vllm-ascend 镜像及官方部署样例

特点：

必须 8GB 以上显存的 GPU 或 NPU
不要全部文档都走它，避免 GPU 资源耗尽、解析变慢
仅对识别质量差、图纸多的疑难标书做二次解析

五、实际使用建议

复制代码

┌─────────────────────────────────────────┐
│           文档进入解析队列               │
└─────────────────┬───────────────────────┘
                  ▼
┌─────────────────────────────────────────┐
│  第一步：MinerU（Pipeline 标准版）        │
│  • 资源占用低，速度快                    │
│  • 输出 Markdown + 坐标，支持溯源跳转     │
└─────────────────┬───────────────────────┘
                  ▼
        ┌─────────────────┐
        │  识别质量是否合格？ │
        └────────┬────────┘
           是 /        \ 否
            ▼            ▼
    ┌──────────┐   ┌─────────────────────┐
    │ 直接输出  │   │ vllm-mineru 兜底解析 │
    │ Markdown │   │ • 多模态 VLM 增强    │
    └──────────┘   │ • 显存 ≥ 8GB        │
                   │ • 仅疑难文档使用      │
                   └─────────────────────┘

推荐部署策略：

主力：mineru pipeline 模式（NVIDIA GPU / 国产昇腾 NPU / 甚至 CPU 小并发）
兜底：vllm-mineru（vlm-engine）仅处理疑难文档，硬件选昇腾 910B/A2 或 NVIDIA 8GB+ 显卡

MinerU 2.6.4 本地部署教程（Windows）

一、环境准备

powershell 复制代码

# 1. 创建项目目录
mkdir D:\Ai_project\mineru
cd D:\Ai_project\mineru

# 2. 使用 conda 创建 Python 3.10 环境（要求 >=3.10,<3.14）
conda create -n mineru python=3.10 -y
conda activate mineru

# 3. 克隆项目
git clone https://github.com/opendatalab/MinerU.git
cd MinerU
# 或直接解压你已有的 MinerU-mineru-2.6.4-released 源码包

下载地址 ：https://github.com/opendatalab/MinerU

可以选高版本的。

二、安装依赖（按需选择）

powershell 复制代码

# ------ 核心依赖（必装）------ 该一开
pip install -e .

# ------ 按后端选择安装扩展依赖 ------
# A. pipeline 后端（CPU 可跑，含 OCR/版面/公式/表格），装 Python 代码（不含模型权重）
pip install -e ".[pipeline]"

# B. vlm-transformers 后端（通用，慢，需 PyTorch）
pip install -e ".[vlm]"

# C. vlm-vllm-engine 后端（GPU 加速，需 CUDA）
pip install -e ".[vllm]"

# D. API / Gradio Web UI（推荐装）
pip install -e ".[api,gradio]"

# 一键全装（pipeline + vlm + vllm + api + gradio）
pip install -e ".[all]"

三、三种解析后端说明

后端定义在 $mineru/cli/client.py:16-18$ (file:///d:\Ai_project\查重系统服务\mineru\MinerU-mineru-2.6.4-released\mineru\cli\client.py#L16-18)：

后端	命令参数	模型仓库	硬件需求	适用场景
`pipeline`	`-b pipeline`	`OpenDataLab/PDF-Extract-Kit-1.0`（10 个小模型）	CPU 可用	通用，结构化文档
`vlm-transformers`	`-b vlm-transformers`	`opendatalab/MinerU2.5-2509-1.2B`（1.2B VLM）	需 PyTorch，GPU 推荐	SOTA 精度，速度慢
`vlm-vllm-engine`	`-b vlm-vllm-engine`	同上	必须 NVIDIA GPU	生产环境，高吞吐
`vlm-http-client`	`-b vlm-http-client -u http://ip:port`	远程服务	无	连接外部 vLLM 服务

四、下载模型

A. pipeline 后端的 10 个模型

powershell 复制代码

# 执行pip install -e .后，
# 说明：以下命令执行，皆在执行完pip install -e .命令后，pip install 只装了 Python 代码和依赖库，不会下载模型权重。模型权重需要单独执行以下命令下载。

# 交互式下载（会提示选 huggingface/modelscope 和模型类型），一个是用github的模型，一个是用本地的
mineru-models-download

# 推荐：指定 modelscope（国内快），下载 pipeline 全部 10 个模型
mineru-models-download -s modelscope -m pipeline

包含的 10 个模型文件：

复制代码

models/Layout/YOLO/doclayout_yolo_docstructbench_imgsz1280_2501.pt   # 版面分析
models/MFD/YOLO/yolo_v8_ft.pt                                          # 公式检测
models/MFR/unimernet_hf_small_2503/                                   # 公式识别
models/MFR/pp_formulanet_plus_m/                                      # 公式识别(备选)
models/OCR/paddleocr_torch/                                           # OCR 文字识别
models/ReadingOrder/layout_reader/                                    # 阅读顺序
models/TabRec/SlanetPlus/slanet-plus.onnx                            # 表格识别
models/TabRec/UnetStructure/unet.onnx                                # 表格结构
models/TabCls/paddle_table_cls/PP-LCNet_x1_0_table_cls.onnx          # 表格分类
models/OriCls/paddle_orientation_classification/PP-LCNet_x1_0_doc_ori.onnx  # 方向分类

B. vlm 后端的 MinerU2.5 模型（可选）

powershell 复制代码

mineru-models-download -s modelscope -m vlm

C. 全部下载

powershell 复制代码

mineru-models-download -s modelscope -m all

五、配置文件

配置文件位置：C:\Users\<你>\mineru.json（首次下载模型时自动生成）

模板见 $mineru.template.json$ (file:///......\mineru\MinerU-mineru-2.6.4-released\mineru.template.json)，关键字段：

json 复制代码

{
    "models-dir": {
        "pipeline": "C:\\Users\\PC\\.cache\\modelscope\\models\\OpenDataLab--PDF-Extract-Kit-1.0\\snapshots\\master",
        "vlm": ""
    },
    "llm-aided-config": {
        "title_aided": {
            "enable": false,
            "api_key": "your_api_key",
            "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "model": "qwen3-next-80b-a3b-instruct",
            "enable_thinking": false
        }
    },
    "config_version": "1.3.1"
}

models-dir.pipeline：手动指向本地模型绝对路径（必填）
models-dir.vlm：用 vlm 后端时填 MinerU2.5 模型路径
llm-aided-config：可选的标题辅助 LLM，enable: false 即不联网

六、huggingface / modelscope 切换配置

由环境变量 MINERU_MODEL_SOURCE 控制，代码在 $models_download_utils.py:17$ (file:///......\mineru\MinerU-mineru-2.6.4-released\mineru\utils\models_download_utils.py#L17)：

值	行为
`huggingface`（默认）	调 `huggingface_hub.snapshot_download()`，国内会超时
`modelscope`	调 modelscope 下载，国内快
`local`	跳过联网，直接读 `mineru.json` 里配置的本地路径

推荐：使用本地已下载模型

powershell 复制代码

# 临时（当前终端会话）
$env:MINERU_MODEL_SOURCE = "local"

# 永久（用户级环境变量，需重启终端生效）
[Environment]::SetEnvironmentVariable("MINERU_MODEL_SOURCE", "local", "User")

设置 local 后，代码会直接读 mineru.json 的 models-dir 路径，不再触发任何网络请求。

其他可选环境变量

powershell 复制代码

$env:MINERU_DEVICE_MODE = "cpu"                 # 设备：cpu / cuda / cuda:0 / mps
$env:MINERU_VIRTUAL_VRAM_SIZE = "1"             # 虚拟显存上限(GB)，pipeline 用
$env:MINERU_INTRA_OP_NUM_THREADS = "4"          # ONNX CPU 线程数
$env:MINERU_PDF_RENDER_TIMEOUT = "300"          # PDF 渲染超时(秒)
$env:MINERU_TABLE_MERGE_ENABLE = "1"            # 跨页表格合并开关
$env:MINERU_FORMULA_CH_SUPPORT = "0"             # 中文公式支持(实验性)

七、启动项目

A. Gradio Web UI（推荐入门）

powershell 复制代码

$env:MINERU_MODEL_SOURCE = "local"
mineru-gradio

访问 http://127.0.0.1:7860

可选参数（ $gradio_app.py:287-339$ (file:///......\mineru\MinerU-mineru-2.6.4-released\mineru\cli\gradio_app.py#L287-339)）：

powershell 复制代码

mineru-gradio --server-port 8080 --max-convert-pages 100

B. FastAPI 服务

powershell 复制代码

$env:MINERU_MODEL_SOURCE = "local"
mineru-api

访问 http://127.0.0.1:8000/docs 看 Swagger 文档

C. CLI 命令行

powershell 复制代码

$env:MINERU_MODEL_SOURCE = "local"

# pipeline 后端（默认）
mineru -p "D:\xxx\your.pdf" -o "./output" -b pipeline -l ch

# vlm-transformers 后端
mineru -p "D:\xxx\your.pdf" -o "./output" -b vlm-transformers

# vlm-vllm-engine 后端（需 GPU）
mineru -p "D:\xxx\your.pdf" -o "./output" -b vlm-vllm-engine

# vlm-http-client 后端（连接外部 vLLM 服务）
mineru -p "D:\xxx\your.pdf" -o "./output" -b vlm-http-client -u http://127.0.0.1:30000

# 常用可选参数
# -m auto|txt|ocr     解析方法（仅 pipeline）
# -s 0 -e 10         起止页（从 0 开始）
# -f True/False       公式识别开关（仅 pipeline）
# -t True/False       表格识别开关（仅 pipeline）
# -d cuda / cpu       设备（仅 pipeline / vlm-transformers）

D. vLLM 推理服务（仅 vlm-http-client 后端需要）

powershell 复制代码

mineru-vllm-server

启动后监听 30000 端口，供 vlm-http-client 调用。

八、验证安装

powershell 复制代码

# 查看版本
mineru -v

# 查看 CLI 帮助
mineru --help

# 测试一个 PDF
$env:MINERU_MODEL_SOURCE = "local"
mineru -p ".\demo\pdfs\demo1.pdf" -o ".\test_output" -b pipeline

看到进度条 Layout Predict: xx% 即正常工作。

九、常见问题

问题	解决
`LocalEntryNotFoundError` / huggingface 超时	设 `MINERU_MODEL_SOURCE=local` 或 `modelscope`
Gradio 上传报错 `cannot unpack NoneType`	同上，后端崩了导致返回 None
表格识别慢	加 `-t False` 关闭表格识别
GPU 未利用	设 `-d cuda`，确认装了 `pip install -e ".[pipeline]"` 且 torch 是 CUDA 版
内存占用高	设 `$env:MINERU_INTRA_OP_NUM_THREADS = "4"` 限制 CPU 线程

十、一键部署脚本（pipeline 后端，纯 CPU）

powershell 复制代码

# deploy_mineru.ps1
conda create -n mineru python=3.10 -y
conda activate mineru

cd D:\Ai_project\mineru\MinerU-mineru-2.6.4-released
pip install -e ".[pipeline,api,gradio]"

mineru-models-download -s modelscope -m pipeline

# 配置环境变量
[Environment]::SetEnvironmentVariable("MINERU_MODEL_SOURCE", "local", "User")

# 启动
mineru-gradio

部署安装完成后，

页面：

MinerU WebUI页面完整讲解

一、顶部蓝色横幅

MinerU 2.5: PDF Extraction Demo PDF提取演示

简介：开源文档提取工具，PDF/图片转Markdown、JSON

按钮：Code(github源码)、Model(模型下载)、Paper论文、Homepage主页、Download下载

二、左侧：操作配置区

1. Please upload a PDF or image

文件上传框，上传 PDF文件或者图片（扫描件照片也可以）

截图里已经上传：安全预警预测管理制度.pdf

2. Max convert pages（最大转换页数）

滑块，控制最多解析多少页

比如滑块拉到1，只解析第1页；上限1000页。

✅小技巧：你的电脑只有8G内存，不要一次性解析几百页，先设置少量页数测试，防止内存爆满卡死。

3. Backend 后端（下拉选择解析引擎，就是咱们前面聊的3种）

pipeline：多小模型流水线，你当前选中的，本机唯一可用选项
vlm‑transformers：多模态大模型，你的电脑硬件不支持
vlm http‑client：远程调用外部VLM服务

不要改动，保持pipeline

4. Recognition Options：识别选项

✅Enable formula recognition：开启公式识别。文档有数学公式时勾选；纯文字文档取消可以省内存。
✅Enable table recognition：开启表格识别。投标文件/制度文档里有表格一定要勾选，能还原成markdown表格。
Language语言：ch=中文，不用修改。
☐Force enable OCR（强制开启OCR）

重点：

不勾选：如果是可复制文字的电子版PDF，直接提取文字，速度快；
勾选强制OCR：把PDF当成图片扫描件逐页识别文字。适合图片型扫描PDF；纯电子版文档不要勾，会变慢。

5. Convert转换 / Clear清除按钮

Convert转换：全部参数调好之后点它，开始解析PDF
Clear清除：清空上传文件和结果

6. PDF preview

PDF预览区域，解析前可以预览上传的文档

三、右侧：结果展示区

解析完成后会生成结果，两个标签页

Markdown rendering Markdown渲染：可视化预览排版效果（表格、标题正常展示）
Markdown text Markdown文本：原始纯markdown源码，可以直接复制出来

截图现在显示【错误】：还没有执行Convert，没有生成解析结果，不是程序故障

👉点Convert运行之后，这里才会出现内容。

✅完整使用步骤（照着操作）

上传PDF文件
设置Max convert pages，建议先设5页以内测试
Backend保持 pipeline
有表格勾选Enable table recognition；有公式勾选公式识别
如果这份PDF是扫描图片版 ，勾选Force enable OCR；可复制文字的电子版不要勾选
点击【Convert转换】，等待处理
处理完成，右侧查看渲染效果，或者复制原始Markdown文本

纯文本pdf文件提取效果：