3条命令把扫描版PDF变成Markdown：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
你收到一份200页的扫描版行业白皮书，需要的是能直接进RAG知识库的Markdown，而不是一页页复制出来的乱码。MinerU就是为此而生的文档解析引擎，把PDF、DOCX、PPTX、XLSX和图片转成机器可读的Markdown/JSON：公式变LaTeX，表格变HTML，支持109种语言识别。从安装到出结果，只需要3条命令。
先搞懂：PDF是怎么被"读懂"的
MinerU把解析拆成三层角色：预处理层先判断文档是扫描版还是乱码版；模型层依次跑版面检测、公式检测和文本OCR；管线层做坐标修复、表格合并和阅读顺序排序，最后汇总成统一中间态（middle_json），再输出Markdown和JSON。你可以把它理解为"先定位字在哪、再认字是什么、最后排阅读顺序"。pipeline、vlm、hybrid三种解析后端可随时切换，精度与速度各取所需。
三步跑通本地解析
没有显卡：pipeline后端稳稳起步
机器没有独立显卡时，pipeline后端是首选，纯CPU可跑，显存要求最低4GB。先装核心包：
uv pip install -U "mineru[core]"这条命令只装核心解析组件，不拉vLLM这类重依赖，装得快。装完直接解析文档：
mineru -p demo/pdfs/demo1.pdf -o ./output -b pipeline-p是输入文件（也接受目录，天然支持批量），-o是输出目录。首次运行会自动下载模型并缓存到本地，之后直接复用，不再重复下载。
⚠️ 常见坑：默认模型源是huggingface，网络不通时先执行export MINERU_MODEL_SOURCE=modelscope，否则首次下载模型会一直卡住。
有8GB显存：切hybrid拿95+的精度
显卡显存8GB以上（Volta架构或更新，含Apple Silicon），装全家桶：
uv pip install -U "mineru[all]"mineru[all]等价于core加vllm，包含VLM推理引擎，是解锁高精度hybrid/vlm后端的完整形态。然后用同一条解析命令、不加-b参数，它会自动选更强的后端：
mineru -p ./docs -o ./output在官方OmniDocBench v1.6评测里，pipeline后端得分86.47，hybrid后端95.39，差距在复杂版面和公式密集的文档上最明显。
坑提示：显存吃紧会OOM，用环境变量MINERU_VIRTUAL_VRAM_SIZE按实际显存保守设置（如设16），强制更温和的加载策略。
本地没算力：轻量客户端连远程服务
设备只有CPU，但团队有一台GPU服务器时，装基础包（不要求本地torch）即可远程调用：
uv pip install -U mineru mineru -p input.pdf -o ./output -b vlm-http-client -u http://127.0.0.1:30000-u指向OpenAI兼容推理服务地址，vlm-http-client是零重依赖的轻量客户端。GPU机器上运行mineru-openai-server --port 30000即可拉起服务端，供多台机器共享。
坑提示：想换hybrid-http-client的话，本地仍需mineru[pipeline]及torch等依赖，别和零依赖的vlm-http-client搞混。
调优与扩展：几个开关管速度
| 配置项 | 作用 | 推荐值 |
|---|---|---|
MINERU_MODEL_SOURCE | 切换模型下载源 | 访问不了huggingface时设modelscope |
MINERU_DEVICE_MODE | 强制指定计算设备 | 留空自动探测；自动识别失败再设cuda/mps/cpu |
MINERU_VIRTUAL_VRAM_SIZE | 显式声明可用显存（GB） | 设为略低于实际显存的值 |
MINERU_FORMULA_ENABLE | 公式解析开关 | 文档无公式时设false，省时间 |
MINERU_TABLE_ENABLE | 表格识别开关 | 默认true |
组合建议：纯文本类报表把公式、表格两个开关都关掉，解析耗时更短；学术论文场景保持全默认、走hybrid后端，版面还原度最佳；处理上千页长文档时可调大MINERU_PROCESSING_WINDOW_SIZE（默认64页）减少处理轮次。完整参数清单见docs/zh/usage/cli_tools.md，扩展模块装法见docs/zh/quick_start/extension_modules.md。
跑通之后往哪走
- 打开输出目录里的layout/span可视化图质检结果，对照原文抽查几页，输出文件结构说明在
docs/zh/reference/output_files.md - 接入你的RAG流程：MinerU输出天然适配LangChain、Dify、FastGPT等插件，集成教程见
docs/zh/usage/plugin/ - 想深挖实现，解析管线源码在
mineru/backend/pipeline/，CLI入口在mineru/cli/
遇到问题先翻docs/zh/faq/里的FAQ，没解决就带样例文件提issue。现在打开终端装上mineru，把那份压箱底的PDF变成干净的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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
