MinerU 本地部署保姆级“喂饭”教程

type

status

date

slug

summary

⭐ MinerU 运行环境

● 支持纯 CPU 环境运行

● 支持 GPU 加速，提升处理效率

🔧本地部署系统要求

在开始安装前，请确保您的系统满足以下要求：

基础环境

● Python 3.10～3.13

● Conda（包管理器）

GPU加速要求（可选）

● NVIDIA显卡（显存≥6GB）

基础环境配置推荐：

接下来是具体的安装步骤：

⚙️ 1.环境配置

1.1 创建Conda环境

需指定Python版本>=3.10

1.2 下载模型文件

首次使用需下载模型文件，提供两种下载方式：

📥 方法一：从Hugging Face下载模型（国际用户推荐）

📥 方法二：从ModelScope下载模型（国内用户推荐）

📁 模型默认存储路径示例：

💡提示：

下载完成后，系统会自动在用户目录下生成 magic-pdf.json 配置文件，你可以在这个配置文件中修改部分配置，实现不同功能的开关，如表格识别、公式识别关闭或开启（默认二者都是开启的，关闭只需将对应的值改 'true' 为 'false' ）。

用户目录位置：

● Windows：C:\Users\用户名

● Linux：/home/用户名

● macOS：/Users/用户名

🧠 补充说明：

● 之前用 'pip install -U "magic-pdf[full]"' 安装的依赖已经保存在mineru环境里。

● 只要没有删除这个环境或修改环境目录，这些内容都会保留。

● 每次关掉终端后再次使用，只需运行 'conda activate mineru' 即可。

🚀 2. GPU加速配置

2.1 CUDA加速设置

这里以 Windows（NVIDIA 显卡）为例。如果您的 NVIDIA 显卡显存 ≥ 6GB，可配置 CUDA 加速。这里我们以 CUDA 12.8 安装为例：

（还需提前安装 NVIDIA 显卡所匹配的 pytorch 版本，但安装步骤此处不做展开，可根据下方“提示”及第二篇文章自行配置）

修改用户目录中配置文件 magic-pdf.json ：

💡提示：

● Pytorch 是 MinerU 运行所必须的深度学习模型的依赖库，执行第1节步骤会自动安装适配 CPU 场景的 Pytoch ，如果使用 GPU，还需重新调整 Pytorch 版本以适配对应的 GPU ；Windows 和 Linux 系统对于 Pytorch 的安装也存在差异，具体安装细节与说明，请参考本期第二篇文章《零基础入门：MinerU 和 PyTorch、CUDA的关系》。

🧩 3. 功能测试

3.1 单文件测试

执行以下命令自动测试功能：

💡 提示: ./ 是指是一个相对路径，它表示当前工作目录（也就是你在终端中运行命令时所在的目录）；执行完上述命令后，检查 output 文件夹，有输出文件说明部署成功。

3.2 批量PDF转换

📋 操作步骤：

✅ 步骤 1：获取批量转换脚本

下载名为 batch_demo.py 的 Python 文件。你可以将此文件保存在你希望执行转换的任何目录下。

✅ 步骤 2：准备 PDF 文件

在 batch_demo.py 文件的目录下新建如下文件夹：

✅ 步骤 3：执行批量转换：

打开你的终端或命令提示符，导航到你保存 batch_demo.py 文件的目录。例如，如果你的 batch_demo.py 文件保存在 demo 文件夹中，你可以执行以下命令：

✅ 步骤 4：查看转换结果：

转换后的结果将默认输出到与 batch_demo.py 文件同级目录下的一个名为 output 的文件夹中。

按照上述步骤，你已经成功本地部署 MinerU 并可以进行 PDF 文档解析了。不过很多小伙伴还有 MinerU

本地

API 服务的需求，比如我们上一篇文章提到的 MinerU Dify插件教程里的场景二

，那接下来就来看看怎么配置 MinerU 本地 API。

🔌 4. 搭建本地 API 服务

4.1 Conda 方式安装

✅ 步骤 1：创建Conda环境

需指定 Python 版本为3.10

✅ 步骤 2：安装依赖

✅ 步骤 3：启动服务

4.2 Docker安装方式

✅ 步骤 1：构建方式

✅ 步骤 2：启动命令

💡 提示 上述任意一种方式安装完成后，可以通过如下地址访问（测试）

📝 5. 如何彻底卸载通过 Conda 安装的 MinerU（含 magic-pdf\[full]）？

✅ 步骤 1：退出当前环境（如果你还在`mineru` 环境中）

✅ 步骤 2：删除整个 Mineru 虚拟环境

确保输出中没有 mineru 环境，说明已经卸载彻底。

💡提示: 如果你是在 Conda 的 base 默认环境中安装并运行了 MinerU API（通过 `pip install -r requirements.txt` 安装依赖），这意味着：

● 所有的依赖都混在 base 环境里；

● 没有单独的虚拟环境，卸载时需要精准清理特定依赖。

🗑️ 6. 如何卸载 MinerU API？

6.1 卸载你通过 Conda 和 pip 安装的 MinerU API 环境，可以按照以下步骤进行清理：

✅ 步骤 1：删除 Conda 环境

你创建的 Conda 环境名为 mineru_api，可使用以下命令删除它：

这将删除整个 mineru_api 环境及其所有依赖。

✅ 步骤 2：可选：删除项目目录（如果你克隆了 GitHub 项目）

如果你通过 git clone 下载了 MinerU 项目文件，可以直接删除目录，例如：

例如你是在 ~/projects/MinerU 目录下：

✅ 步骤 3：可选：清理 pip 缓存

如果你想进一步清理 pip 下载的缓存文件：

6.2 卸载你通过Docker 构建和运行 MinerU 的 PDF 解析 API 镜像，主要包括以下两步：

✅ 步骤 1：停止并移除容器（如果有残留）

你用了 --rm 参数（docker run --rm），这意味着容器在停止后会自动删除，所以无需手动删除容器，这一步可以跳过。

但你可以用以下命令确认没有运行中的 MinerU 容器：

如果看到 mineru-api 仍在运行，可以手动停止：

✅ 步骤 2：删除镜像

删除名为 mineru-api 的镜像：

如遇“镜像正在使用”的提示，可加 -f 强制删除：

✅ 步骤 3：可选：清理构建缓存

Docker 会留下很多中间层镜像和缓存文件，如果你想释放空间：

⚠️ 警告：该命令会删除所有未使用的容器、网络、镜像、构建缓存。慎用！

至此，相信你已经掌握了 MinerU 本地部署、API构建、卸载等操作，快去试试吧

如果上述操作对你来说仍显得复杂，或者始终缺少相应的硬件条件，那强烈推荐!!!你使用官方提供的 MinerU 客户端，无需编写代码、零学习成本，即可快速完成文档免费转换：

https://mineru.net