MinerU WebUI 实用教程：从 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
MinerU 把杂乱的 PDF、扫描件和 Office 文档转成干净的 Markdown 与 JSON，它的 Gradio WebUI 版本不用敲任何命令行，拖进文件、选个后端就能拿到能直接读的结果。
这篇文章读完你会拿到：
- 一条命令装好、一条命令起界面
- 页面上每个选项是什么、什么时候用
- 三个不配也能跑、配了更顺手的选项
- 第一次运行最容易踩的坑
🚀 安装并启动：两条命令跑出第一个 PDF 解析结果
先对一下环境，差距不大就能直接开始：
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| Python | 3.10 | 3.10–3.13 |
| 内存 | 16 GB | 32 GB 以上 |
| 显卡 | 集显 | NVIDIA 8 GB 以上 |
| 磁盘 | 20 GB | 50 GB |
下面这条命令安装[core]扩展包，里面已包含 vlm、pipeline 两种解析后端和 Gradio 前端，一条装全：
pip install -U "mineru[core]"执行完终端会打出Successfully installed ...，看到这一行就说明依赖齐了。
接着启动 WebUI，首次运行会自动下载模型，耐心等它跑完：
mineru-gradio --server-name 0.0.0.0 --server-port <your_port>终端最后打印出 Gradio 服务地址时就算启动成功。浏览器打开后，你会看到左侧上传区、右侧结果区的双栏界面；想先试试效果，可以直接点界面上的内置示例文件，无需自己准备文档。
🔍 看懂 WebUI 上的四件事
整个界面就一条任务线：上传文件 → 选解析后端 → 设识别选项 → 拿 Markdown。
1. 上传与预览
拖入 PDF、图片，或者 DOCX / PPTX / XLSX。PDF 走版面检测路线，Office 文件走专用的办公文档解析链路。
上面这张图就是解析的第一步：模型先在页面上圈出段落、公式、表格各自的位置，再逐块转换，所以结果能保持原文的版式结构。
2. 选解析后端
- Hybrid（推荐）：默认项，混合引擎，精度上限最高
- Pipeline（稳定多语言）：传统多模型管线，资源占用低、无幻觉问题，适合多语种文档
- VLM（高精度中英文）：多模态大模型端到端解析，中英文场景效果最好
- Remote VLM / Remote Hybrid：连接已部署的 OpenAI 兼容服务，本机几乎不耗资源
选中 Hybrid 后会多出一个"解析强度"：medium 更快，high 更准但更慢。
3. 设识别选项
表格识别、公式识别、图片分析、OCR 语言、强制 OCR，共五个开关。多数人保持默认即可；强制 OCR 是最后手段，只在识别结果差到没法看时打开，且要先选对语言。
4. 拿结果
结果区有三个页签：Markdown 渲染（公式直接画出来，适合人眼检查）、Markdown 文本（复制源码用）、JSON 内容列表（结构化内容，给程序调用）。
⚙️ 三个可选配置：不配能跑，配了更顺手
场景：模型下载慢或卡死推荐值：启动前执行export MINERU_MODEL_SOURCE=modelscope为什么：默认模型源是 HuggingFace，国内网络经常连不上；这个环境变量对所有 MinerU 命令生效，一次设置后启动、解析都走 ModelScope。
场景：大文档想控制资源消耗推荐值：mineru-gradio --max-convert-pages <your_max_pages>为什么：默认最多解析 1000 页。给个上限，可以避免误传超大文档时把内存和显存吃满，解析中途报错。
场景：机器上已有解析服务推荐值：mineru-gradio --api-url http://127.0.0.1:<api_port>为什么：WebUI 本身不做解析，它是把任务转给一个 mineru-api 服务。如果服务已经常驻，直接传地址复用它，免得每次启动界面都临时拉起一个。
📁 按场景选配置：三个真实任务
扫描件合同归档推荐组合：Pipeline 后端 + 正确的 OCR 语言 + 打开强制 OCR。 一句话理由：扫描件自带文本层残缺，让 OCR 从头认字比让大模型猜更稳。
把 PPT、Excel 变成知识库素材推荐组合：Hybrid 后端 + 表格识别开启 + 图片分析开启。 一句话理由：Office 文档的价值主要在图表里，表格识别直接产出结构化内容，省去二次整理。
给大模型喂文档上下文推荐组合：VLM 后端（中英文文档）+ 拿 JSON 内容列表。 一句话理由：程序按结构化 JSON 切块投喂，比直接塞 Markdown 原文可控得多。
🛡️ 避坑：五个高频现象一句话解法
| 现象 | 原因 | 一句话解法 |
|---|---|---|
| 界面起不来 | 7860 端口被占用 | --server-port <your_port>换个端口 |
| 模型下载卡住 | HuggingFace 连不上 | export MINERU_MODEL_SOURCE=modelscope后重启 |
| 大文档解析爆显存 | 页数过多 | 调低--max-convert-pages或改用 Pipeline |
| 扫描件出来是乱码 | OCR 语言没选对 | 在 OCR Language 选对应语言再转一次 |
| Markdown 里公式不显示 | 渲染器不认当前分隔符 | 用--latex-delimiters-type all启动 |
🎯 收个尾
- 第一次使用就用默认 Hybrid 后端加默认选项，先把完整流程跑通，再回头调参。
- 国内网络先把模型源切到 modelscope，能解决大半"模型下不下来"的问题。
- 资源紧张时用 Pipeline 后端加页数上限，精度损失可控，体验不会断。
- 成批的文档改用命令行
mineru -p <input> -o <output>跑自动化，WebUI 更适合单份文档和人工核对。
以上内容基于 MinerU 3.4.x 编写，参数细节和界面文案可能随版本更新，遇到出入以官方文档的 usage 与 FAQ 章节为准。
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
