MinerU WebUI 3步启动指南：PDF解析到Markdown的可视化教程

MinerU WebUI 3步启动指南：PDF解析到Markdown的可视化教程

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

把 PDF 解析成 Markdown 不再需要背命令行：MinerU（开源文档解析工具）提供 Gradio WebUI 可视化界面，在浏览器里完成上传、配置、转换、下载全流程。安装加启动只需 3 条命令，10 分钟内你可以完成首次 PDF 解析，并独立为学术论文、批量文件、低显存机器各选出一套后端模式与关键参数。

📋 一、能力边界：WebUI 能做什么

CLI 批量自动化、mineru-api服务化部署与mineru-router多 GPU 编排不在本文范围，参见项目内 docs/zh/usage/quick_usage.md。

🚀 二、环境自检、安装与3步启动

启动前先核对 5 项环境（判断句：缺 GPU 也能跑 Pipeline 后端，但选 VLM/Hybrid 时请逐项确认显卡）：

• Python 版本在 3.10–3.13 之间（MinerU 的requires-python范围）
• 内存 ≥16GB（解析长文档时内存占用会显著上升）
• 可用磁盘 ≥50GB（模型下载约占 10GB+）
• NVIDIA GPU 显存 ≥6GB（无 GPU 只能走 CPU 或远程服务）
• 网络能访问模型源，国内网络建议先切到 ModelScope

安装只需 1 条命令。mineru[core]一次性装上解析核心、本地推理与 WebUI 依赖，避免后续缺组件报错：

# 安装 MinerU 核心包（含 gradio WebUI 依赖），pip 用户执行；用 uv 的话在行首把 pip 换成 uv pip install -U "mineru[core]"

启动同理，先给理由再给命令。默认启动会拉起本地解析服务并占用 7860 端口：

# 默认启动 Gradio WebUI mineru-gradio

局域网其他设备要访问时，加上监听地址与端口参数（这也是最常用的变体）：

# 监听 0.0.0.0:7860，允许局域网访问 mineru-gradio --server-name 0.0.0.0 --server-port 7860

看到类似输出即启动成功，浏览器打开http://127.0.0.1:7860：

* Running on local URL: http://127.0.0.1:7860 * To create a public link, set `share=True` in `launch()`.

📄 三、一次完整解析工作流（上传→配置→解析→取结果）

步骤1｜上传待解析文件。左侧上传区支持 PDF、图片（JPG/PNG 等）以及 DOCX/PPTX/XLSX 文件，支持拖拽或点击选择；启动时默认开启示例文件，可直接点示例快速体验，不用先找测试文档。

步骤2｜选择解析配置。上传区下方依次是后端下拉框、识别选项与高级选项。后端有 4 个选项：Hybrid（推荐）、Pipeline、VLM，以及--enable-http-client true启动后出现的远程选项；识别选项含表格识别、公式识别、OCR 语言、强制 OCR 四个开关，另有最大转换页数滑杆。各后端的取舍见第五章，此处只需认识这几个开关。

步骤3｜触发解析。点击 Convert 按钮提交任务，下方状态栏实时显示转换进度；首次使用会自动下载模型，这一步耗时长属正常现象，不必刷新页面。

步骤4｜获取结果。解析完成后右侧依次呈现：文档预览、转换状态、Markdown 渲染视图（公式按 LaTeX 分隔符实时渲染）、Markdown 原始文本，最下方 Result file 区提供结果打包下载（含 Markdown 与结构化 JSON）。

🧭 四、后端模式对比与选择

耗时为 8GB+ 显存 GPU 上的量级参考，请以你机器实测为准。

每个模式一句判定句：

• hybrid-engine：默认首选，显存 8GB+ 直接用它
• pipeline：CPU 或多语种文档时选它
• vlm-engine：精度优先且显存≥8GB 时选它
• vlm-hybrid-http-client：本机无卡但已有远端推理服务时选它

🎛️ 五、按场景配置3类关键参数

1. 精度优先（学术论文/含公式）

# 国内网络切换模型源，并指定推理设备（变量名以项目配置文档为准） export MINERU_MODEL_SOURCE=modelscope export MINERU_DEVICE_MODE=cuda:0

预期效果：公式以 LaTeX 文本输出而非截图，100 页英文论文在 8GB+ 显存上约 8 分钟量级。

2. 速度与批量（大文件/多文件）

# 国内模型源，降低首次启动的下载等待 export MINERU_MODEL_SOURCE=modelscope

预期效果：hybrid 后端单文件 100 页约 10 分钟量级；超过 100 个文件的批量任务建议转 CLI 的mineru -p <输入目录> -o <输出目录>。

3. 低显存与纯 CPU（显存≤6GB）

# pipeline 后端的模型源与设备配置（变量名以项目配置文档为准） export MINERU_MODEL_SOURCE=modelscope export MINERU_DEVICE_MODE=cpu

预期效果：12GB 内存的纯 CPU 机器可完整跑通 pipeline 后端，100 页约 15 分钟量级，无显存压力。

🔧 六、问题速查表

通用日志排查：把启动输出完整落盘，出错后定位最后一行异常：

# 启动 WebUI 并把全部日志写入 mineru_webui.log（MINERU_LOG_LEVEL 等变量以官方文档为准） mineru-gradio --server-port 7860 2>&1 | tee mineru_webui.log

📊 七、性能参考

测试条件：NVIDIA RTX 3060 12GB GPU、100 页英文学术论文 PDF、hybrid 与 vlm 后端各测一轮。耗时与占用为量级参考，请以你硬件实测为准。

✅ 八、收尾

MinerU WebUI 把 PDF 解析压缩成"上传—选后端—下载"三步，精度与速度按场景各取所需。下一步可学习 CLI 批量模式（docs/zh/usage/cli_tools.md）处理数百个文件的自动化任务。

本文基于 MinerU 2.x 版本编写，参数与默认值可能随版本更新，请以项目内官方文档为准。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU