MinerU Gradio WebUI 实操指南：10 分钟把 PDF 变成大模型可用的 Markdown

MinerU Gradio WebUI 实操指南10 分钟把 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想喂给 RAG 或大模型做检索问答但直接复制出来的文本顺序混乱、公式变成乱码、表格只剩一堆空格——这类文档直接进大模型效果往往很差。MinerU Gradio WebUI 就是为了解决这个问题一条mineru-gradio命令启动浏览器页面上传 PDF 或 Office 文档选择解析后端点击转换就能在网页里直接预览 Markdown 结果并下载完整产物全程不用记任何命令行参数。MinerU 本身是一款开源文档解析工具支持 PDF、图片、DOCX、PPTX、XLSX 输入输出 Markdown 和 JSON。而 Gradio WebUI 是它的可视化入口你不需要理解 OCR 模型和版面检测的分工只需要在页面上做几个开关决策。读完这篇文章你可以独立把 MinerU WebUI 跑起来按文档类型选择合适的解析后端处理扫描版、含公式、Office 这几类真实任务并在结果不理想时知道该调哪个参数。准备一次环境硬条件这一节只列出能不能跑起来的门槛跑通一次之后就不用再管。项目要求说明Python3.10 ~ 3.13项目声明支持3.10,3.14操作系统Linux / Windows / macOS官方三平台均兼容磁盘预留足够空间放模型文件首次运行会自动下载模型视所选后端而定GPU非必须纯 CPU 可以跑Linux 和 macOS 会自动尝试 cuda/mps 加速国内网络环境建议先设置模型源否则模型下载会很慢export MINERU_MODEL_SOURCEmodelscope这里把模型下载源切换为 ModelScope在启动 MinerU 前执行一次即可。第一次跑通从安装到第一次解析这一节走最短路径目标是让浏览器里出现你解析出来的第一个文档。第 1 步安装核心包pip install -U mineru[core]这里安装 MinerU 的core依赖集一次性包含 pipeline、VLM 和 Gradio 三套组件。成功标志是命令正常结束且终端能识别mineru-gradio命令。第 2 步可选拿一份样例 PDF如果手头没有测试文件可以拉取仓库使用内置 demogit clone https://gitcode.com/GitHub_Trending/mi/MinerU这里只是为了取demo/pdfs/下的 demo1.pdf、demo2.pdf 等样例后续也可以用你自己的任意 PDF。第 3 步启动 WebUImineru-gradio这里会同时做两件事启动 Gradio 页面并在后台自动拉起一个可复用的本地mineru-api服务。成功标志是浏览器打开http://localhost:7860能看到MinerU 3文档提取演示标题和左侧上传区。第 4 步转换第一个文件上传一份 PDF保持默认后端和默认开关点击转换。转换过程中状态面板会依次走过 准备 → 检查服务 → 提交 → 排队 → 解析 → 下载结果 → 整理输出 → 完成 这几个步骤首次运行要下载模型耗时会明显更长。成功标志有三点状态面板最后显示完成及耗时转换结果区域出现可下载的 ZIP 文件Markdown 渲染标签页里出现按阅读顺序排好的正文到这里最短链路已经跑通。接下来按你的文档类型做取舍。核心能力它能帮你做什么这一节不按界面区域罗列而是按任务目标讲清楚每个能力什么时候该用。多格式文档转 MarkdownPDF、图片、DOCX、PPTX、XLSX 都支持上传。转换后的文本会去掉页眉、页脚、页码等干扰元素按人类阅读顺序输出保留标题、段落、列表结构。上传 Office 文件时页面会自动隐藏 PDF 专属的解析选项右侧显示 Office 在线预览该预览依赖 Microsoft 在线服务转换本身不依赖它。选择解析后端这是 WebUI 里最重要的一次决策。当前版本提供三类本地后端和两类远程客户端模式后端定位适合什么时候用hybrid-engine默认混合引擎精度最高对结果质量要求高、硬件条件允许时pipeline传统多模型管道低资源、无幻觉多语言文档、资源有限、追求稳定vlm-engine多模态大模型端到端解析中英文文档的高精度解析vlm-http-client/hybrid-http-client连接远程 OpenAI 兼容服务器本机算力不足模型部署在别处切换后端时页面上的公式开关、图片分析开关等会联动显示或隐藏——比如图片分析只在 vlm 和 hybrid 高配强度下出现OCR 语言只在 pipeline 下生效。选择逻辑见 backend_options.py。识别开关微调左侧高级选项气泡里有四个开关各自影响一类内容启用表格识别关闭后表格以图片形式保留不输出 HTML 结构启用公式识别关闭后公式显示为图片行内公式不再解析启用图片分析关闭后图片/图表仍保留版面位置但跳过 VLM 分析强制 OCR OCR 语言仅当自动判断失败、识别效果极差时才开强制 OCR并务必选对语言三种结果形态加一次质检转换完成后右侧有三个标签页Markdown 渲染带 LaTeX 公式渲染、Markdown 文本可复制原始文本、JSON 内容列表按阅读顺序的结构化数据适合程序化处理。ZIP 包里还包含提取出的图片、中间 JSON 和可视化文件。质检是 MinerU 的一个实用习惯结果 ZIP 里会生成{文件名}_layout.pdf用色块标出每页检测到的内容块及阅读顺序号pipeline 后端还会生成{文件名}_span.pdf用不同颜色线框标注文本片段方便你快速定位某段文字为什么丢了。整个链路可以用一张图概括界面交互与状态面板的实现可以看 gradio_app.py输出文件的完整说明在 docs/zh/reference/output_files.md。场景实战三个真实任务这一节挑三类最常见的任务按目标 → 关键配置 → 预期结果给出可以直接照抄的方案。场景一扫描版中文手册要可全文检索的文本目标纸质扫描的 PDF没有文字层需要提取干净正文。关键配置后端选pipeline对扫描件和多语言更稳资源占用低OCR 语言选ch先不勾强制 OCR看第一轮效果预期结果正文按阅读顺序输出为 Markdown页码页眉被剔除。如果第一轮结果很差大量漏字再打开强制启用 OCR并重试——这是界面文案明确提示的用法仅当识别效果极差时启用。场景二含密集公式的学术报告公式必须是 LaTeX目标论文里的行间公式要转成可编辑的 LaTeX而不是截图。关键配置后端选vlm-engine或hybrid-engine保持公式识别开启默认就是开的表格如果复杂保持表格识别开启预期结果Markdown 里公式以 LaTeX 代码形式出现Markdown 渲染标签页里直接渲染成数学符号JSON 内容列表中公式块带有类型标注方便下游程序分流处理。场景三一批 PPTX 汇报材料转成结构化文档目标把演示文稿里的文字、要点整理成 Markdown供知识库录入。关键配置直接上传 PPTX 文件无需任何 PDF 专属选项上传后这些选项会自动隐藏保持默认后端即可预期结果每份 PPTX 输出对应 Markdown 和 JSONZIP 结果里按文件命名组织。若批量数量大、人工逐个上传太慢改用命令行mineru -p 输入目录 -o 输出目录处理整个目录更合适参数体系与 WebUI 一致。 调优与避坑这一节合并了性能调整和故障排查全部按遇到 X 时 → 这样做组织扫一眼就能定位。遇到的问题这样做启动报端口被占用换端口启动mineru-gradio --server-port 7861模型下载慢或失败启动前export MINERU_MODEL_SOURCEmodelscope大文档处理到一半内存吃紧用--max-convert-pages 100限制最大页数默认 1000或调小MINERU_PROCESSING_WINDOW_SIZE默认 64首次 VLM 请求明显卡住加--enable-vlm-preload true让 WebUI 启动阶段就预热本地 VLM 模型Markdown 预览里公式不渲染换 LaTeX 分隔符类型mineru-gradio --latex-delimiters-type a$类型、b()[]类型或all默认多 GPU / 多机部署改用mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto统一入口WebUI 或 CLI 通过--api-url连过去报错信息看不明白export MINERU_LOG_LEVELDEBUG后重启看完整日志两条补充建议远程模式*-http-client后端启动时要加--enable-http-client true并在页面上填写 OpenAI 兼容服务器地址本地不装 torch 也能跑轻量客户端模式输出目录默认在当前工作目录的./output/gradio/下按时间戳组织批量使用时建议定期清理避免旧任务文件堆积⚡ 速查一张表对应你的场景直接照抄即可你的场景推荐配置初次体验任何文档默认后端hybrid-engine全部开关保持默认扫描件 / 多语言 / 低配机器pipeline 对应 OCR 语言识别差再开强制 OCR公式密集的论文vlm-engine或hybrid-engine公式识别保持开启本机无 GPU模型在服务器上hybrid-http-client/vlm-http-client 服务器地址需要程序消费结构化数据看JSON 内容列表标签页或下载 ZIP 里的 middle JSON下一步装好mineru[core]后打开 docs/zh/usage/quick_usage.md 对照命令行参数逐项确认然后用一份你真实的文档把上面三个场景各跑一遍——哪个场景的结果不符合预期就回到调优与避坑那张表里找对应条目。本文基于当前仓库版本MinerU 3hybrid/vlm/pipeline 三后端体系编写启动参数与界面选项可能随版本更新变化后端完整列表、环境变量与输出文件格式请以仓库内docs/zh/文档为准。【免费下载链接】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），仅供参考