企业官网建设流程全解析

5步上手MinerU：把PDF和Office文档转成LLM可用的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

你在为 RAG 知识库、Agent 工作流准备语料时，手里的资料往往不是干净文本，而是带多栏版式、公式、表格的 PDF、DOCX、PPTX。MinerU 就是干这件事的文档解析工具：输入这些文件，输出按阅读顺序排好、公式转成 LaTeX、表格转成 HTML 的 Markdown 和 JSON，直接喂给大模型。这篇指南带你从安装到第一次跑通，再拆解最常用的三个能力和关键配置。

跑通第一次

最短路径是 5 步，按顺序执行即可：

1. 安装 Python 3.10–3.13 环境，安装核心依赖：

uv pip install "mineru[core]"

core 模块包含解析所需的全部核心依赖，体积适中；想一次装齐所有加速模块可以改用mineru[all]。

2. 国内网络建议先切模型源，避免模型下载卡住：

export MINERU_MODEL_SOURCE=modelscope

模型默认托管在 Hugging Face，这一行让首次自动下载改走 ModelScope 镜像。

3. 用仓库自带的示例 PDF 跑一次解析：

mineru -p demo/pdfs/demo1.pdf -o ./output

执行后 CLI 会自动拉起一个本地临时的 mineru-api 服务来完成解析，首次运行会自动下载模型，耐心等待即可。

4. 打开./output目录，你会得到demo1.md主文件，以及_middle.json、_content_list.json和可视化质检文件等辅助产物。

5. 重点看demo1.md是否通顺、demo1_layout.pdf里的阅读顺序编号是否合理，这就是第一份正反馈。

MinerU 从 PDF 到 Markdown 的整体链路如下，预处理、模型层、管线层最终都落到统一中间态再输出：

上图展示了 MinerU 的分层设计：预处理做乱码检测和扫描版识别，管线层做表格合并、公式替换，最后统一输出 Markdown 和 content list。

核心能力拆解

1. 多格式输入与版面还原

它能解决的核心问题是"顺序错乱"：多栏、跨页、页眉页脚混在一起的文档，解析出来还是一段乱码顺序的文本。MinerU 会自动剥离页眉、页脚、页码，输出符合人类阅读顺序的内容，且 PDF、图片、DOCX、PPTX、XLSX 都是原生支持。

开启方式就是上面那条mineru -p <输入> -o <输出>，输入可以是单个文件或整个目录。最小示例：

mineru -p ./my_docs -o ./output

一个注意点：解析结果好不好，最快的验证方式是打开输出目录里的{文件名}_layout.pdf，每页会显示每个内容块的阅读顺序编号和类型色块：

上图展示的是 layout 质检效果：数字标记阅读顺序，不同底色区分标题、正文、公式块，顺序不对一眼就能看出来。

2. 公式转LaTeX与表格转HTML

学术论文和研报里最让传统解析工具头疼的就是公式和表格。MinerU 的公式解析和表格解析默认都是开启的，公式会输出 LaTeX、表格会输出 HTML，不需要额外配置。

想临时关掉某个能力，用 CLI 参数或环境变量都行：

mineru -p demo/pdfs/demo2.pdf -o ./output -f false -t false

-f false关闭公式解析、-t false关闭表格解析，对应的环境变量是MINERU_FORMULA_ENABLE和MINERU_TABLE_ENABLE，环境变量优先级高于命令行参数，在所有子命令里都生效。一个注意点：pipeline 后端有一个实验性的中文公式优化开关MINERU_FORMULA_CH_SUPPORT，中文论文场景可以打开试试，完整说明见 环境变量说明。

3. 三种解析后端怎么选

这是上手后第一个要做的重要决策。MinerU 提供三种后端，用-b参数切换：

最小示例（纯 CPU 环境强制走 pipeline）：

mineru -p input.pdf -o ./output -b pipeline

hybrid 后端支持--effort medium|high两档解析强度，默认 medium 在精度基本不变的前提下速度更快，但 medium 档不支持图片/图表分析，需要时切 high。注意 vllm 和 lmdeploy 两个加速模块不要同时安装，会引入依赖冲突，装哪个都可以，效果接近。

配置与进阶

下面是日常最可能用到的几项配置，完整清单在 命令行工具文档：

怎么选：有 NVIDIA 显卡就用默认 hybrid-engine，不用改任何配置；机器只有 CPU 就加-b pipeline；算力和客户端分离的部署，就在服务器上用mineru-api起服务、客户端走vlm-http-client远程调用，多 GPU 场景再叠加mineru-router做统一入口和负载均衡。想深入调参时，vllm/lmdeploy 的官方参数也可以直接透传给 mineru 各子命令。

避坑清单

1. 现象：首次运行长时间无输出。原因：正在自动下载模型，大模型文件走网络比较慢。解决：先export MINERU_MODEL_SOURCE=modelscope切镜像源，或用mineru-models-download命令提前下载模型，第二次运行直接命中本地缓存。
2. 现象：vllm 模块安装失败或报 CUDA 相关错误。原因：vllm 新版本默认要求兼容 CUDA 13.0 的显卡驱动。解决：确认驱动版本支持所装 vllm 对应的 CUDA 运行时，或按 Docker 部署文档 用预构建镜像规避环境问题。
3. 现象：Windows 安装后解析速度慢得像纯 CPU。原因：装到的是不带 CUDA 的 torch。解决：去 PyTorch 官网选择与你 CUDA 版本匹配的安装命令重装 torch 和 torchvision；RTX 50 系显卡则按 FAQ 安装对应 cu128 的 lmdeploy wheel。
4. 现象：Linux 上解析结果缺一部分文字。原因：部分发行版缺 CJK 字体，PDF 渲染成图片时把中文字渲染丢了。解决：sudo apt install fonts-noto-core fonts-noto-cjk后刷新字体缓存，或直接用自带字体的 Docker 镜像。
5. 现象：macOS 上想走 Docker 部署报错。原因：Docker 方案只支持 Linux 和 WSL2。解决：macOS 用户直接 pip/uv 安装即可，MPS 加速开箱可用，不需要 Docker。

解析结果不满意时，先别急着提 issue：输出目录里的layout.pdf和span.pdf是官方给的质检入口，能帮你定位是版面切错还是 OCR 漏字。完整输出文件说明见 output_files，常见问题见 FAQ。

下一步建议：拿一份你自己的真实文档跑一遍，打开 layout 文件确认阅读顺序，再根据文档类型（论文偏公式、报表偏表格）决定后端和开关组合；跑顺之后，可以把content_list.json接进你的 RAG 管线，开始真正的批量处理。

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