夜雨聆风项目卡片
项目：MinerU[1] 状态：v3.4.0 / 70k+ Star / 活跃更新中 一句话判断：文档解析领域的"瑞士军刀"，精度高、格式全、集成广，适合需要把文档喂给大模型的场景
把 PDF 直接丢给大模型，效果通常很差。表格乱了，公式丢了，多栏排版变成一团乱码。问题不在模型，而在格式。
你需要先把文档"翻译"成模型能理解的东西——Markdown 或 JSON。MinerU 就是干这个的。
MinerU 支持的输入格式很全：PDF、DOCX、PPTX、XLSX、图片。输出是结构化的 Markdown 或 JSON。
几个关键能力：
公式识别：自动把 LaTeX 公式转成标准格式 表格提取：表格转 HTML，保留结构 多栏排版：不管文档是几栏，输出都按人类阅读顺序 扫描件 OCR：支持 109 种语言，扫描件也能处理 跨页表格：表格跨页了？它能自动合并
我一开始以为它只是个普通 PDF 解析器，看了文档才发现，它连 PPT 和 Excel 都能处理，这在同类工具里不多见。
MinerU 提供三种解析引擎，适用场景不同：
pipeline：最稳，CPU 也能跑，没有幻觉问题。适合对精度要求不极端、但需要稳定输出的场景。OmniDocBench 评分 86.47。
vlm-engine：用视觉语言模型，精度最高（95.30），但需要 GPU，最少 8GB 显存。适合精度优先的场景。
hybrid-engine：结合两者优点，精度 95.39，原生文本提取，低幻觉。默认用 medium 强度，速度快；需要最高精度或图片分析时切 high。
我一般建议先跑 pipeline 试试水。它对硬件要求最低，纯 CPU 就能用，结果也够用。等确认场景合适了，再考虑切到 hybrid 或 vlm。
安装很简单：
pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"
跑起来更简单：
mineru -p <你的文档.pdf> -o <输出目录>
没 GPU？指定 pipeline 后端：
mineru -p <你的文档.pdf> -o <输出目录> -b pipeline
输出目录里会有 Markdown 文件和提取的图片。就是这么直接。
如果你网络不好，下不了 HuggingFace 的模型，加个环境变量：
export MINERU_MODEL_SOURCE=modelscope
国内用户用这个，模型从 ModelScope 下载，不用挂代理。
命令行够用，但如果你要集成到自己的系统里，MinerU 提供了完整的 API：
# 启动 FastAPI 服务
mineru-api --host 0.0.0.0 --port 8000
然后用 curl 测试：
curl -X POST http://127.0.0.1:8000/tasks \
-F "files=@你的文档.pdf" \
-F "return_md=true"
API 支持异步任务，提交后会返回 task_id，你可以轮询状态：
curl http://127.0.0.1:8000/tasks/<task_id>
想要可视化界面？Gradio WebUI 一行命令：
mineru-gradio --server-name 0.0.0.0 --server-port 7860
浏览器打开 http://127.0.0.1:7860，上传文档就能看效果。
这是 MinerU 最有意思的功能之一。
它提供了 MCP Server，可以集成到 Cursor、Claude Desktop、Windsurf 这些 AI 编程工具里。集成之后，你可以直接在对话里让 AI 帮你解析文档。
配置方式（以 Cherry Studio 为例）：
{
"name": "MinerU-MCP",
"type": "stdio",
"command": "uvx",
"args": ["mineru-mcp"],
"env": {
"MINERU_API_BASE": "https://mineru.net",
"MINERU_API_KEY": "你的API密钥",
"OUTPUT_DIR": "./downloads",
"USE_LOCAL_API": "false"
}
}
配置好后，你可以说："帮我把这个 PDF 转成 Markdown"，AI 会自动调用 MinerU 处理。
这对需要频繁处理文档的开发者来说，省了不少事。
如果你在做 RAG（检索增强生成）应用，MinerU 的集成生态很完善：
LangChain：直接调用 Dify：插件支持 FastGPT：原生集成 RAGFlow：深度集成
这意味着你可以把 MinerU 作为文档预处理环节，清洗后的 Markdown 直接喂给向量数据库。
这点在国内很重要。
MinerU 支持的国产算力平台很全：昇腾、寒武纪、燧原、沐曦、摩尔线程、昆仑芯、天数智芯、瀚博、太初元碁、海光、平头哥。
如果你的公司用的是国产 GPU，MinerU 大概率能跑起来。文档里每个平台都有详细的适配说明。
我踩过的几个坑，分享一下：
1. 模型下载问题
首次运行会下载模型，默认从 HuggingFace。国内网络经常连不上。解决方案：export MINERU_MODEL_SOURCE=modelscope。
2. Windows CUDA 加速
Windows 上装完 MinerU，如果推理速度很慢，大概率是 CUDA 没配好。去 PyTorch 官网选适合你 CUDA 版本的 torch 和 torchvision 重新装。
3. Linux 缺字体
Linux 上解析 PDF 如果丢字，大概率是缺 CJK 字体：
sudo apt install fonts-noto-core fonts-noto-cjk
fc-cache -fv
4. 大文档内存问题
处理几万页的 PDF，内存会爆。MinerU 3.0 之后加了滑动窗口机制，长文档不用手动拆分了，但内存还是建议 32GB 以上。
5. 超时问题
用 MCP Server 处理大文档容易超时。建议分批处理，或者用本地 API 模式。
MinerU 用的是自定义许可证，基于 Apache 2.0。
商业使用门槛很高：月活超过 1 亿或月收入超过 2000 万美元才需要单独谈商业许可。对绝大多数公司来说，直接用就行。
如果你基于 MinerU 提供在线服务，需要在界面上注明用了 MinerU。这个要求不算过分。
MinerU 不是万能的。复杂排版、手写体、扫描件的解析结果可能还是不够完美。但在开源文档解析工具里，它的精度、格式支持和集成生态确实是最全的。
如果你正在做 RAG 应用、文档处理流水线，或者只是想把 PDF 喂给大模型，值得花 5 分钟跑一下命令行试试。
这里会继续拆真实可用的开发者工具：少讲概念，多看入口、成本和坑点。你只需要判断一件事——它值不值得放进自己的工作流。
引用链接
[1]MinerU: https://github.com/opendatalab/MinerU