MinerU 安装与上手指南：3 步把 PDF 转成结构化 Markdown

MinerU 安装与上手指南3 步把 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/MinerUMinerU 是一款开源文档解析工具把 PDF、扫描件图片以及 DOCX、PPTX、XLSX 解析为带标题层级、表格、公式的结构化 Markdown / JSON供 LLM 检索与 RAG 流程消费。如果你的场景是手头有一份几十页的论文或扫描版报告需要提取成干净的 Markdown 喂给知识库或大模型MinerU 可以直接完成整页布局分析、公式转 LaTeX、表格转 HTML。安装完成后首次解析会自动下载所需模型无需手动配置模型路径。路线选型完整安装、Docker 部署与轻量客户端怎么选MinerU 本地使用有三条路线完整包安装、Docker 部署、以及只装基础包的轻量客户端。选型时主要看两点本机是否有 NVIDIA GPUVolta 架构及以上或 Apple Silicon以及模型服务是否已部署在远端。路线硬件需求解析精度OmniDocBench v1.6适用场景推荐程度完整安装mineru[all]本地 GPU 8GB 显存内存 32GB 推荐hybrid 后端约 95.3 分有 GPU 的桌面 / 服务器追求最高解析精度新手默认首选Docker 部署同完整安装同完整安装Linux / WSL2 服务器依赖冲突多或需要容器化管理生产环境推荐轻量客户端 http-client 后端本地 2GB 显存即可甚至纯 CPU取决于远端服务低配设备或模型已部署在远程 OpenAI 兼容服务上边缘 / 调用方场景提示Docker 部署仅适用于 Linux 和支持 WSL2 的 Windows 环境macOS 用户请使用 pip 或 uv 安装Windows 上 Python 版本需 3.10~3.12详见 快速入门文档。完整安装步骤uv 创建环境、安装包、跑通第一个文档以下按执行顺序给出全部命令适合 Windows / Linux / macOS 通用全程约 3 步。uv venv .venv source .venv/bin/activate创建独立的 Python 虚拟环境并激活避免污染系统解释器。uv pip install -U mineru[all]安装完整功能包mineru[all]已按操作系统自动带上 vllm / lmdeploy / mlx 等推理框架依赖装完即得到mineru、mineru-api、mineru-gradio等命令。mineru -p demo/pdfs/demo1.pdf -o output用仓库自带的示例 PDF 跑一次解析。首次运行会自动从 HuggingFace 下载模型文件国内网络建议先设置MINERU_MODEL_SOURCEmodelscope见下一节完成后在output目录下的auto子目录中找到生成的 Markdown、图片和中间 JSON。如果选择从源码运行例如要改代码可以克隆仓库后执行uv pip install -e .[all]仓库地址为 https://gitcode.com/GitHub_Trending/mi/MinerU 。关键环境变量与配置项说明这些配置通过环境变量生效优先级高于命令行参数且在mineru、mineru-api、mineru-router等所有命令行工具中都有效。完整清单见 命令行工具文档。变量名作用默认或推荐值何时需要改MINERU_MODEL_SOURCE模型下载源huggingface / modelscope / localhuggingface无法访问 HuggingFace 时设为modelscope模型已预先下载时设为localMINERU_HYBRID_BATCH_RATIOhybrid 后端的 batch 倍率控制单客户端显存占用按显存6GB 以下设 84GB 设 42GB 设 1GPU 显存不足报错时下调MINERU_PROCESSING_WINDOW_SIZE单次处理窗口大小影响大文档内存占用64超长文档内存吃紧时调小MINERU_API_MAX_CONCURRENT_REQUESTSmineru-api最大并发请求数3多用户共享服务时上调MINERU_FORMULA_ENABLE公式解析开关true文档无公式、想提速时设为 falseMINERU_PDF_RENDER_TIMEOUTPDF 渲染为图片的超时秒数300遇到异常 PDF 长时间卡住时调整命令行侧还有两个高频选项-b选择解析后端pipeline/hybrid-engine/vlm-engine/ 两种http-client默认hybrid-engine--effort控制 hybrid 的解析强度默认medium。两者配合CUDA_VISIBLE_DEVICES可以精确指定用哪张卡示例见 进阶 CLI 参数文档。验证安装与常见问题排查先做两件事确认装对了执行mineru --version能正常打印版本号说明命令和依赖没问题再执行上一节的示例解析命令输出目录中出现 Markdown 文件和图片目录说明模型下载与解析链路都通了。下面是四个高频问题的现象 → 原因 → 解决现象模型下载失败或下载极慢。原因默认模型源是 HuggingFace国内网络访问不稳定。解决export MINERU_MODEL_SOURCEmodelscope切换到国内镜像源后重跑更完整的模型源策略见 模型源说明。现象Windows 下安装了 CUDA 环境但报错或回退到 CPU。原因PyTorch 的 CUDA 版本与显卡驱动不匹配。解决按 FAQ 中 Windows CUDA 加速一节 核对驱动与 torch 版本或临时改用-b pipeline纯 CPU 后端保证先用起来。现象解析长文档时内存或显存溢出。原因默认处理窗口和 batch 按 32GB 内存、8GB 显存配置。解决调小MINERU_PROCESSING_WINDOW_SIZE与MINERU_HYBRID_BATCH_RATIO或改用pipeline后端4GB 显存即可运行。现象解析找不到输出文件。原因输出按输出目录/后端/文档名/嵌套存放默认后端目录名为auto。解决到对应子目录查找或用--help查看-o参数说明输出文件结构见 输出文件说明。小结与延伸阅读MinerU 的本地使用路径可以概括为按硬件三选一完整安装 / Docker / 轻量客户端mineru[all]一条命令装全用mineru -p 输入 -o 输出跑通第一个文档之后通过环境变量按需调模型源和内存参数。遇到问题先查 FAQ未解决可以到 项目仓库 提交 issue 并附上样例文档。延伸阅读快速入门与部署对比表docs/zh/quick_start/index.mdCLI 参数与环境变量完整清单docs/zh/usage/cli_tools.md扩展模块vllm / lmdeploy / 轻量 client安装指南docs/zh/quick_start/extension_modules.md【免费下载链接】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），仅供参考