一个命令跑通 MinerU：PDF 转换实战笔记
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
手里有份 200 页的扫描 PDF，要转成能编辑的 Markdown，手动复制行不通。MinerU 把 PDF、图片和 Office 文档解析成 LLM 能直接用的 Markdown 与 JSON。按你的硬件和场景选一条路，装完就能转。
装 core 就能跑：MinerU 第一份 PDF 怎么转
装完你手里多了一个mineru命令行工具：输入 PDF、图片或 docx/pptx/xlsx，输出 Markdown 和 JSON。core 模块把解析所需的全部依赖一次装齐，模型首次运行时自动下载，需要联网。
uv pip install mineru[core] mineru -p input.pdf -o output/第二行跑通后，output/下按页生成 Markdown。默认走 hybrid-engine 后端，换 pipeline、vlm-engine 或调解析参数，见 CLI 参数文档。
有显卡才走这条路：MinerU vllm 加速与显存配置
门槛先说清：Turing 架构及以上、显存 ≥8G，不满足直接跳过本节。
uv pip install mineru[all]在 Linux 上，mineru[all]等价于 core + vllm + s3 合并安装，一条命令到位。装完设两个环境变量：
export MINERU_DEVICE_MODE=cuda export MINERU_VIRTUAL_VRAM_SIZE=16 # 按实际显存改加速原理只记结论：vllm 用 PagedAttention 管理 KV 缓存，减少显存浪费，批量推理比默认引擎快 3~5 倍。服务端实现在mineru/model/vlm/，想抠细节再看。
🖥 本机算力不够：轻量客户端连远程推理服务
三种情况适用：本机没显卡、不想装重依赖、只想连远程 vllm-server。服务端跑mineru-vllm-server，客户端只装基础包，体积 <50MB：
uv pip install mineru mineru -p input.pdf -o output/ --backend vlm-http-client --url http://127.0.0.1:30000客户端把页面通过 HTTP 发给远端做推理，本地只处理返回结果，跑 200 页扫描件也不吃本机显存。整体架构与数据流见下图。
这几个环境变量开关最常用
默认配置能覆盖大多数文档，想换模型下载源、限定显存上限、关掉公式或表格识别来省时间时，才需要动下面这些开关。
| 变量名 | 干什么的 | 常见取值 |
|---|---|---|
| MINERU_MODEL_SOURCE | 模型下载源 | modelscope / local |
| MINERU_DEVICE_MODE | 设备模式 | cuda / cpu |
| MINERU_VIRTUAL_VRAM_SIZE | 推理显存上限 | 8 / 16 |
| MINERU_FORMULA_ENABLE | 公式解析开关 | true / false |
| MINERU_TABLE_ENABLE | 表格识别开关 | true / false |
完整列表在 CLI 参数文档 里。
装不上、跑不对时先查这几种症状
vllm 安装反复失败：大概率是本地依赖版本冲突。别跟依赖死磕，换预构建镜像，看 Docker 部署指南。
中文输出乱码：文档语言没判对。跑转换时加-l ch指定语言，OCR 准确率会直接上来。
大文档显存溢出：推理批量开大了。先把MINERU_VIRTUAL_VRAM_SIZE调小，再用-s/-e分段转页面。
都解决不了，先翻 FAQ，再不到去仓库 issue 区提单。
个人日常转换，core 加远程客户端就够；批量任务或精度要求高，走 vllm 那条路。想读源码：git clone https://gitcode.com/GitHub_Trending/mi/MinerU
【免费下载链接】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），仅供参考
