MinerU PDF 转换指南：如何按需组合模块并完成 GPU 加速配置
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
把上百页的扫描件变成结构化的 Markdown，是搭建 RAG 知识库和 Agent 工作流绕不开的一步。MinerU 负责把 PDF、Office 文档解析成 LLM 可直接消费的 Markdown 与 JSON，它的扩展模块按需安装，不必全都要。这篇教程带你完成三件事：选对安装包、跑通第一次 PDF 转换、配好 GPU 加速。
第一步选安装包：先按机器配置做决策
MinerU 的可选安装组把功能拆成了几档，装多装少取决于你手头的硬件。先看结论：
| 安装组合 | 适用人群 | 特点 |
|---|---|---|
mineru（基础包） | 只做转换调用的轻量机器 | 体积最小，把解析任务交给远端服务 |
mineru[core] | 需要在本地完成全部转换的用户 | 除 vllm 外的核心组件，装完即可用mineru命令 |
mineru[all] | 有 GPU 且追求吞吐的用户 | 等价于mineru[core,vllm]，包含全部扩展 |
💡 选型口诀：没有 GPU 或机器配置低，选基础包走远程；要本地完整转换，选 core；GPU 够强想加速，直接 all。
三行命令跑通首次转换：安装到出结果的最短路径
选定 core 后，下面三条命令就是从空环境到拿到输出物的完整链路。
安装 core 组件：
uv pip install mineru[core]对一份 PDF 发起转换，-p指输入文件，-o指输出目录：
mineru -p demo.pdf -o output运行结束后，output目录下会生成解析出的 Markdown、图片与中间 JSON 结果，可以直接喂给下游的 LLM 流程。完整的参数清单（分页解析、公式/表格开关等）可查阅 CLI 工具文档。
给 GPU 换上加速引擎：vllm 模块的安装与门槛
vllm 模块面向 GPU 用户，前提条件是 Turing 架构及以上显卡，且显存 8G 起步。满足后，一条命令即可装齐全部扩展：
uv pip install mineru[all]然后配置两个环境变量，设备模式指定为 cuda，虚拟显存大小按实际卡调整：
export MINERU_DEVICE_MODE=cuda export MINERU_VIRTUAL_VRAM_SIZE=16原理一句话带过：vllm 借助 PagedAttention（一种把 KV 缓存分页管理的技术）避免显存碎片化，让批量推理更快更省，整体推理速度有显著提升。相关模型代码位于 mineru/model/vlm 目录。
连上远程推理服务：轻量客户端用法
本地没有 GPU 但有一台服务器时，基础包就是最合适的选择：它体积最小，把重活交给远端。客户端通过 HTTP 连接 vllm-server，一条命令即可发起转换：
mineru --backend vlm-http-client -u http://server-ip:8000 -p input.pdf -o output.md其中-u指向远端的 OpenAI 兼容服务地址，适合边缘设备与多机分摊解析压力的部署形态。
环境变量速查表：不碰代码调节行为
不想每次都在命令行里堆参数时，环境变量更省事，且通常优先于命令行参数生效。
| 变量名 | 作用 | 示例值 |
|---|---|---|
MINERU_MODEL_SOURCE | 切换模型下载来源 | modelscope |
MINERU_FORMULA_ENABLE | 公式解析开关 | false |
MINERU_TABLE_ENABLE | 表格识别开关 | true |
例如国内网络下载模型不便时，把来源切成 modelscope 即可；纯文字文档可以关掉公式与表格解析来省时间。全部变量的说明见 环境变量说明。
高频问题自查：现象、原因与一行修复
现象：vllm 安装失败或环境不兼容。原因：vllm 对显卡驱动与 CUDA 版本有硬性要求，手搓依赖容易踩坑。修复：直接使用官方 Docker 预构建镜像，参考 Docker 部署指南。
现象：转换结果中文显示为乱码。原因：解析时语言识别不准，OCR 按错误字符集还原了文字。修复：在运行转换时通过-l ch显式指定文档语言（该参数仅 pipeline 后端生效）。
现象：推理时报显存不足。原因：批量处理占用的显存超出了卡的实际容量。修复：调小MINERU_VIRTUAL_VRAM_SIZE的取值，为系统留出余量。
小结与延伸阅读
MinerU 把 PDF 转换拆成了基础包、core、all 三档安装组，分别对应远程调用、本地转换与 GPU 加速三种形态，配合环境变量即可覆盖多数场景。完整代码与更多示例可在 MinerU 仓库 找到。
延伸阅读：常见问题 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），仅供参考
