MinerU 实用指南10分钟把PDF转成LLM就绪的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把PDF里的公式、表格搬进知识库常常一地鸡毛直接喂给大模型更难。MinerU 是一款开源文档解析工具能把 PDF、DOCX 等文档直接转成 LLM 就绪的 Markdown 与 JSON。本文按任务顺序带你过一遍安装命令、按硬件选解析后端的方案、常用参数和几个高频坑帮你第一次就转出可用结果。快速上手两条命令转出第一个PDF最简路径只有两条命令前提是已装好 Python 3.10~3.13 和 uv 包管理器uv pip install -U mineru[all] # 一次装齐全部解析能力含本地GPU加速组件 mineru -p demo/pdfs/demo1.pdf -o ./output # 解析示例PDF结果写入output目录第二条命令运行时会自动拉起本地解析服务首次运行需要联网下载模型约几GB下载一次后走本地缓存。-p后面可以是单个 PDF、图片、DOCX、PPTX、XLSX 文件也可以直接给一个目录做批量转换。如果模型下载卡住先设置export MINERU_MODEL_SOURCEmodelscope再重试这条在 Linux/macOS 上会自动尝试 cuda/mps 加速。按场景选方案先看硬件再定后端MinerU 的解析后端写在命令的-b参数里选哪个取决于你的机器而不是你的喜好。没有显卡pipeline后端跑纯CPU适合笔记本、云CPU实例这类无GPU环境速度比GPU慢但零硬件门槛。mineru -p input.pdf -o output -b pipeline # 指定pipeline后端纯CPU运行文档标注该后端兼容性最好端到端精度约86分OmniDocBench指标日常转换够用。本地有N卡或Mac默认混合引擎自动加速显存8GB以上、Volta架构及以后的N卡以及 Apple Silicon满足条件时直接跑默认后端hybrid-engine不用额外加参数多卡机器可用CUDA_VISIBLE_DEVICES1 mineru -p ... -o ...指定用哪张卡。文档给出该路线端到端精度约95分比纯CPU的 pipeline 高一个量级适合对解析质量有要求的正式文档。团队协作一台GPU机当服务器其他人连HTTP适合显卡只有一台、使用者有若干人的情况服务端推理、客户端只负责收发文件。mineru-api --host 0.0.0.0 --port 8000 # 服务端暴露API浏览器开 /docs 看接口文档 mineru -p input.pdf -o output -b vlm-http-client -u http://127.0.0.1:8000 # 客户端本地无需torch和显卡vlm-http-client是轻量远程客户端官方说明它不要求本地安装 torch。想要网页界面就改用mineru-gradio --server-name 0.0.0.0 --server-port 7860启动 WebUI多卡多服务场景还有mineru-router做统一入口编排。参数调优速查常用环境变量变量作用建议值适用场景MINERU_MODEL_SOURCE模型下载源huggingface / modelscope / local国内网络填modelscope模型下载慢、失败MINERU_DEVICE_MODE指定解析运行的设备CPU/GPU默认自动检测出问题再显式指定设备选择不符合预期MINERU_VIRTUAL_VRAM_SIZE给VLM推理划定的显存预算GB默认自动检测显存紧张时显式调小本地GPU加速MINERU_FORMULA_ENABLE公式解析开关默认true纯文本文档可设false提速公式密集或想省资源MINERU_TABLE_ENABLE表格识别开关默认true表格密集或想省资源MINERU_API_OUTPUT_ROOTAPI 服务输出根目录默认./output服务化部署时建议指到固定磁盘部署 mineru-apiMINERU_PROCESSING_WINDOW_SIZE单次处理窗口大小影响大文档内存与吞吐默认64内存吃紧时调小解析超长PDFMINERU_HYBRID_BATCH_RATIOhttp-client 端小模型 batch 倍率控制客户端显存显存≤4GB 建议 4 以下远程客户端显存有限CUDA_VISIBLE_DEVICES限定可见GPU编号如0,1多卡机器分卡使用环境变量的优先级高于命令行同名参数且对所有 MinerU 命令行工具生效配置一次全局受益。常见坑现象、原因与解法现象常见原因解决办法首次运行卡在模型下载网络访问不了 HuggingFaceexport MINERU_MODEL_SOURCEmodelscope后重跑Linux 解析结果缺部分中文文字发行版缺 CJK 字体PDF渲染丢字安装fonts-noto-cjk字体包后执行fc-cache -fvWindows 装完跑得很慢像没用GPU没装支持CUDA的torch按显卡架构从 PyTorch 官网装对应 CUDA 版本的 torch 与 torchvisionWSL2 启动报ImportError: libGL.so.1系统缺图形库sudo apt-get install libgl1-mesa-glx显存不够、推理报OOM混合引擎要求8GB显存改走vlm-http-client连远程服务或本机退回 pipeline 后端Windows 和 WSL2 的这两类报错在官方 FAQ 里有独立条目若上述命令不生效直接翻仓库内的 FAQ 文档对照处理。收尾检查清单已安装mineru[all]Python 版本在 3.10~3.13 之间首次解析跑通模型已缓存到本地后端与硬件匹配无卡用 pipeline有卡走默认混合引擎多人共用走 http-client国内网络已把模型源切到 modelscope服务化部署时固定了输出目录并按并发量调整了 API 参数按清单核完一遍第一次解析就能稳定复现。遇到清单外的报错带上命令和日志去 MinerU 仓库提交 issue社区会跟进处理。【免费下载链接】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），仅供参考 MinerU 实用指南：10分钟把PDF转成LLM就绪的Markdown
MinerU 实用指南10分钟把PDF转成LLM就绪的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把PDF里的公式、表格搬进知识库常常一地鸡毛直接喂给大模型更难。MinerU 是一款开源文档解析工具能把 PDF、DOCX 等文档直接转成 LLM 就绪的 Markdown 与 JSON。本文按任务顺序带你过一遍安装命令、按硬件选解析后端的方案、常用参数和几个高频坑帮你第一次就转出可用结果。快速上手两条命令转出第一个PDF最简路径只有两条命令前提是已装好 Python 3.10~3.13 和 uv 包管理器uv pip install -U mineru[all] # 一次装齐全部解析能力含本地GPU加速组件 mineru -p demo/pdfs/demo1.pdf -o ./output # 解析示例PDF结果写入output目录第二条命令运行时会自动拉起本地解析服务首次运行需要联网下载模型约几GB下载一次后走本地缓存。-p后面可以是单个 PDF、图片、DOCX、PPTX、XLSX 文件也可以直接给一个目录做批量转换。如果模型下载卡住先设置export MINERU_MODEL_SOURCEmodelscope再重试这条在 Linux/macOS 上会自动尝试 cuda/mps 加速。按场景选方案先看硬件再定后端MinerU 的解析后端写在命令的-b参数里选哪个取决于你的机器而不是你的喜好。没有显卡pipeline后端跑纯CPU适合笔记本、云CPU实例这类无GPU环境速度比GPU慢但零硬件门槛。mineru -p input.pdf -o output -b pipeline # 指定pipeline后端纯CPU运行文档标注该后端兼容性最好端到端精度约86分OmniDocBench指标日常转换够用。本地有N卡或Mac默认混合引擎自动加速显存8GB以上、Volta架构及以后的N卡以及 Apple Silicon满足条件时直接跑默认后端hybrid-engine不用额外加参数多卡机器可用CUDA_VISIBLE_DEVICES1 mineru -p ... -o ...指定用哪张卡。文档给出该路线端到端精度约95分比纯CPU的 pipeline 高一个量级适合对解析质量有要求的正式文档。团队协作一台GPU机当服务器其他人连HTTP适合显卡只有一台、使用者有若干人的情况服务端推理、客户端只负责收发文件。mineru-api --host 0.0.0.0 --port 8000 # 服务端暴露API浏览器开 /docs 看接口文档 mineru -p input.pdf -o output -b vlm-http-client -u http://127.0.0.1:8000 # 客户端本地无需torch和显卡vlm-http-client是轻量远程客户端官方说明它不要求本地安装 torch。想要网页界面就改用mineru-gradio --server-name 0.0.0.0 --server-port 7860启动 WebUI多卡多服务场景还有mineru-router做统一入口编排。参数调优速查常用环境变量变量作用建议值适用场景MINERU_MODEL_SOURCE模型下载源huggingface / modelscope / local国内网络填modelscope模型下载慢、失败MINERU_DEVICE_MODE指定解析运行的设备CPU/GPU默认自动检测出问题再显式指定设备选择不符合预期MINERU_VIRTUAL_VRAM_SIZE给VLM推理划定的显存预算GB默认自动检测显存紧张时显式调小本地GPU加速MINERU_FORMULA_ENABLE公式解析开关默认true纯文本文档可设false提速公式密集或想省资源MINERU_TABLE_ENABLE表格识别开关默认true表格密集或想省资源MINERU_API_OUTPUT_ROOTAPI 服务输出根目录默认./output服务化部署时建议指到固定磁盘部署 mineru-apiMINERU_PROCESSING_WINDOW_SIZE单次处理窗口大小影响大文档内存与吞吐默认64内存吃紧时调小解析超长PDFMINERU_HYBRID_BATCH_RATIOhttp-client 端小模型 batch 倍率控制客户端显存显存≤4GB 建议 4 以下远程客户端显存有限CUDA_VISIBLE_DEVICES限定可见GPU编号如0,1多卡机器分卡使用环境变量的优先级高于命令行同名参数且对所有 MinerU 命令行工具生效配置一次全局受益。常见坑现象、原因与解法现象常见原因解决办法首次运行卡在模型下载网络访问不了 HuggingFaceexport MINERU_MODEL_SOURCEmodelscope后重跑Linux 解析结果缺部分中文文字发行版缺 CJK 字体PDF渲染丢字安装fonts-noto-cjk字体包后执行fc-cache -fvWindows 装完跑得很慢像没用GPU没装支持CUDA的torch按显卡架构从 PyTorch 官网装对应 CUDA 版本的 torch 与 torchvisionWSL2 启动报ImportError: libGL.so.1系统缺图形库sudo apt-get install libgl1-mesa-glx显存不够、推理报OOM混合引擎要求8GB显存改走vlm-http-client连远程服务或本机退回 pipeline 后端Windows 和 WSL2 的这两类报错在官方 FAQ 里有独立条目若上述命令不生效直接翻仓库内的 FAQ 文档对照处理。收尾检查清单已安装mineru[all]Python 版本在 3.10~3.13 之间首次解析跑通模型已缓存到本地后端与硬件匹配无卡用 pipeline有卡走默认混合引擎多人共用走 http-client国内网络已把模型源切到 modelscope服务化部署时固定了输出目录并按并发量调整了 API 参数按清单核完一遍第一次解析就能稳定复现。遇到清单外的报错带上命令和日志去 MinerU 仓库提交 issue社区会跟进处理。【免费下载链接】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），仅供参考 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
