MinerU插件3步装好：PDF转Markdown 10分钟
【免费下载链接】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、Word、PPT、Excel 解析成大模型可用 Markdown 和 JSON 的开源文档解析工具，解决"PDF 内容喂不进 LLM"的麻烦。读完本文你能做到：
- 按你的硬件（纯 CPU / N 卡 / 只需远程调用）选对插件安装路径
- 跑通第一次 PDF 转换，并验证结果
- 用几个环境变量切换模型源、指定设备、开关公式和表格解析
- 自查安装失败、乱码、显存不足等高频问题
30 秒搞懂核心概念
插件就是按需安装的功能包
MinerU 的功能按"扩展包"拆分：core是基础解析能力，vllm是推理加速模块，s3、mlx等是可选增强。按需安装，不装用不到的依赖。
vllm 是什么
vllm 是一种高性能推理引擎（开源推理框架），用 PagedAttention（分页管理 KV 缓存）技术加速 VLM（视觉大模型）推理。要求 Volta 及以后架构的 N 卡，显存 8G 以上。
三种解析后端怎么分
pipeline：传统版面检测 + OCR，CPU 可跑；vlm-engine：本地跑 VLM 模型，精度高；vlm-http-client：本机只做轻量客户端，模型跑在远程服务器上。
按场景选你的路径：MinerU插件安装方案
1. 纯 CPU，或只想先试试
下面的命令安装 core 包，包含 pipeline/VLM 基础模型和 Gradio 可视化，不含 vllm：
uv pip install "mineru[core]"适合没有显卡、或先评估 MinerU 解析质量的用户。
2. 有 Volta 及以后架构的 N 卡（8G 显存+）
执行uv pip install "mineru[core,vllm]"，一次性装好 core 和 vllm，VLM 后端会走 vllm 做 GPU 推理加速。
适合有 N 卡、要更高精度和批量吞吐的用户。注意：vllm 与 lmdeploy 加速效果相近，二选一安装，别同时装。
3. 只需远程调用（边缘设备 / 纯 CPU 服务器）
执行uv pip install mineru装轻量客户端，运行时用-b vlm-http-client -u <服务端地址>指向远程的 OpenAI 兼容服务。
适合只有 CPU 和网络、算力放在远端 GPU 服务器上的用户。
装完就跑：最小可用配置
下面的命令解析项目自带的示例 PDF，把结果写到output目录（首次运行会自动下载模型）：
mineru -p demo/pdfs/demo1.pdf -o output验证方式：跑完执行mineru --version能输出版本号，且output目录下生成了.md文件。两者都满足，说明环境 OK。
性能旋钮与环境变量：GPU推理加速配置
| 变量名 | 作用 | 推荐值 | 什么时候需要改 |
|---|---|---|---|
| MINERU_MODEL_SOURCE | 切换模型下载源 | 不设置（自动探测） | 网络访问不了 HuggingFace 时，设为modelscope |
| MINERU_DEVICE_MODE | 指定计算设备 | 不设置（自动探测） | 多卡或想强制指定设备时，设为cuda、cpu等 |
| MINERU_VIRTUAL_VRAM_SIZE | 限制模型加载的显存上限（GB） | 不设置（自动探测） | 显存紧张或 OOM 时，调成较小的整数 |
| MINERU_FORMULA_ENABLE | 公式解析开关 | true | 文档基本没公式时设为false，加快解析 |
| MINERU_TABLE_ENABLE | 表格识别开关 | true | 文档没有表格时设为false |
不配置也能跑，以上只是进阶调优。完整参数清单见 命令行工具文档。
踩坑速查：高频问题 Q/A
Q：vllm 安装失败或 CUDA 版本不兼容？
A：默认 vllm 需要兼容 CUDA 13.0 的驱动；驱动是 CUDA 12.9 的话，请按 vllm 官方文档选对应 CUDA 的安装方式，或直接用 Docker 部署指南 里的预构建镜像。
Q：模型下载慢或反复失败？
A：多半是网络访问不了 HuggingFace。执行export MINERU_MODEL_SOURCE=modelscope切到 ModelScope 源再重试。
Q：中英混排文档 OCR 效果不理想？
A：OCR 语言默认ch（中文，兼容混排）。纯英文文档在命令里加-l en即可。
Q：解析时显存溢出（OOM）？
A：调小MINERU_VIRTUAL_VRAM_SIZE，或换更轻量的后端：-b pipeline。
下一步
跑通第一次转换后，建议翻一翻 扩展模块安装指南，了解 s3、lmdeploy 等可选模块，把 MinerU 接到你的 Agentic 工作流里。
【免费下载链接】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），仅供参考
