企业官网建设流程全解析

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/MinerU

MinerU 是一款开源文档解析工具，把 PDF、扫描件图片以及 DOCX、PPTX、XLSX 解析为带标题层级、表格、公式的结构化 Markdown / JSON，供 LLM 检索与 RAG 流程消费。如果你的场景是：手头有一份几十页的论文或扫描版报告，需要提取成干净的 Markdown 喂给知识库或大模型，MinerU 可以直接完成整页布局分析、公式转 LaTeX、表格转 HTML。安装完成后首次解析会自动下载所需模型，无需手动配置模型路径。

路线选型：完整安装、Docker 部署与轻量客户端怎么选

MinerU 本地使用有三条路线：完整包安装、Docker 部署、以及只装基础包的轻量客户端。选型时主要看两点：本机是否有 NVIDIA GPU（Volta 架构及以上）或 Apple Silicon，以及模型服务是否已部署在远端。

提示：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_SOURCE=modelscope，见下一节），完成后在output目录下的auto子目录中找到生成的 Markdown、图片和中间 JSON。

如果选择从源码运行（例如要改代码），可以克隆仓库后执行uv pip install -e .[all]，仓库地址为 https://gitcode.com/GitHub_Trending/mi/MinerU 。

关键环境变量与配置项说明

这些配置通过环境变量生效，优先级高于命令行参数，且在mineru、mineru-api、mineru-router等所有命令行工具中都有效。完整清单见 命令行工具文档。

命令行侧还有两个高频选项：-b选择解析后端（pipeline/hybrid-engine/vlm-engine/ 两种http-client，默认hybrid-engine），--effort控制 hybrid 的解析强度（默认medium）。两者配合CUDA_VISIBLE_DEVICES可以精确指定用哪张卡，示例见 进阶 CLI 参数文档。

验证安装与常见问题排查

先做两件事确认装对了：执行mineru --version能正常打印版本号，说明命令和依赖没问题；再执行上一节的示例解析命令，输出目录中出现 Markdown 文件和图片目录，说明模型下载与解析链路都通了。

下面是四个高频问题的"现象 → 原因 → 解决"：

现象：模型下载失败或下载极慢。原因：默认模型源是 HuggingFace，国内网络访问不稳定。解决：export MINERU_MODEL_SOURCE=modelscope切换到国内镜像源后重跑；更完整的模型源策略见 模型源说明。

现象：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.md
• CLI 参数与环境变量完整清单：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