MinerU 在 Windows 11 的部署与使用（Python 3.12，RTX 4060）记录我在 Window

MinerU 在 Windows 11 的部署与使用（Python 3.12，RTX 4060）

记录我在 Windows 11 + Python 3.12 + RTX 4060 的本地环境下部署 MinerU 的全过程，并整理三种常见使用方式： 1）Python 依赖直接启动 HTTP 服务；2）CLI 直接解析文件；3）Docker 部署（含 GPU 使用要点）。

操作系统：Windows 11（WSL2 已启用、安装 Docker Desktop 可选）
Python 版本：3.12
显卡：NVIDIA GeForce RTX 4060

显卡环境确认（nvidia-smi）

本机显卡信息如下（确保驱动已安装且可正常使用）：

nvidia-smi 输出（Windows/WSL）

如要在 Docker/WSL 中使用 GPU，需要在对应环境内同样能运行 nvidia-smi。

一、使用 Python 依赖启动 HTTP 服务（推荐上手）

目标：在虚拟环境里安装 MinerU 依赖，然后通过 mineru-api 启动一个本地 HTTP 服务（默认访问文档在 /docs）。

1. 创建并激活虚拟环境

# 进入你的工作目录
# 例如：cd D:\workspace\mineru-demo

# 创建虚拟环境（Python 3.12）
python -m venv .venv

# 激活虚拟环境（PowerShell）
. .venv\Scripts\Activate.ps1
# 或 Cmd：
# .venv\Scripts\activate.bat

2. 安装 uv（如未安装）

uv 是 Astral 出品的极速包管理工具。安装方式任选其一：

PowerShell（官方脚本）：

iwr https://astral.sh/uv/install.ps1 -UseBasicParsing | iex

或使用 pipx或pip（如已安装 pipx）：

pipx install uv
pip install uv

若暂不想安装 uv，也可以直接使用 pip：pip install -U "mineru[core]"

3. 安装 MinerU 依赖

# 使用 uv 安装（推荐）
uv pip install -U "mineru[core]"

#（可选）若使用 pip：
# pip install -U "mineru[core]"

提示：如安装过程中遇到镜像或网络问题，可先配置国内源或使用代理。

4. 启动 HTTP 服务（mineru-api）

mineru-api --host 0.0.0.0 --port 8000

初次启动时，Windows 防火墙可能弹窗，允许即可。
打开浏览器访问：
- http://127.0.0.1:8000
- http://127.0.0.1:8000/docs（Swagger UI，可直接在线试用接口）

5. 在其他项目中通过 HTTP 调用（以 Dify 项目为例）

我本地的 dify-deletion_scheduled-1-mater 项目就是通过 HTTP 直接对接 mineru-api。

推荐做法：先打开 http://127.0.0.1:8000/docs，在 Swagger UI 里查看具体接口路径、请求方式与参数格式，然后在项目里按该接口契约进行调用。
示例思路（伪代码）：

import requests

# 示例：根据 /docs 中的实际接口与字段自行调整
url = "http://127.0.0.1:8000/your_endpoint"
files = {
    "file": ("sample.pdf", open("D:/data/sample.pdf", "rb"), "application/pdf")
}
# 或 data/json = {...} 视接口定义而定
resp = requests.post(url, files=files)
resp.raise_for_status()
print(resp.json())

应用成功使用MinerU服务解析pdf，运行成功示意：

mineru 服务运行成功

小贴士：不同版本/构建的 mineru-api 可能暴露的路由略有差异，强烈建议以 /docs 为准。若在容器/WSL 中启动服务，请注意主机与容器/WSL 的 IP/端口映射与可达性。

二、使用 CLI 直接解析文件

不用启服务，直接在命令行解析本地文件：

# 基本用法（按需替换路径）
mineru -p "D:/input_dir" -o "D:/output_dir"

# 常见注意：
# 1. Windows 路径建议加引号，避免空格/中文路径导致解析失败。
# 2. 权限不足或文件被占用会导致读取失败，必要时以管理员启动终端。

输出目录会生成解析结果（具体结构/格式以 MinerU 版本为准）。

三、使用 Docker 部署（含 GPU 要点）

如果希望通过 Docker 运行 MinerU，并在容器中使用 GPU（Windows 11 + WSL2）：

安装并开启 Docker Desktop（启用 WSL2 后端）。
Windows 主机安装 NVIDIA 显卡驱动（保持最新）。
在 WSL 发行版（如 Ubuntu）内安装 NVIDIA Container Toolkit：
- 参考官方文档安装 nvidia-container-toolkit，并在 WSL 内确认 nvidia-smi 可用。
运行容器时启用 GPU：

# 示例：将 8000 端口映射出来，并启用全部 GPU
# 假设镜像中以 mineru-api 作为入口或手动指定命令

docker run --rm -it --gpus all -p 8000:8000 \
  -v D:\data:/data \
  <mineru_image> mineru-api --host 0.0.0.0 --port 8000

如在 WSL 内运行，请使用 WSL 路径（例如 /mnt/d/data）进行目录挂载。
如果你的镜像没有默认启动 mineru-api，在 docker run 末尾显式追加启动命令即可。

备注：Windows 宿主 + Docker Desktop + WSL2 的 GPU 直通是通过 WSL 层的 NVIDIA Container Toolkit 完成的，务必在容器实际运行的 Linux 发行版里验证 GPU 可用。

常见问题（FAQ）

Q1：mineru-api 启动后访问不了？
- A：检查端口是否被占用；防火墙是否放行；是否访问了正确地址（宿主/WSL/容器 IP 区分）。
Q2：mineru 或 mineru-api 命令找不到？
- A：确认虚拟环境是否已激活；关闭重开终端后再试；where mineru 查看路径；必要时重装依赖。
Q3：uv pip install -U "mineru[core]" 失败？
- A：优先检查网络/镜像源；若是 Python 3.12 兼容性问题，可尝试 Python 3.10/3.11；或改用 pip 安装并查看具体报错信息。
Q4：容器内没有 GPU？
- A：WSL 里确认 nvidia-smi 正常；核对是否已安装 nvidia-container-toolkit；docker run 是否加了 --gpus all；镜像里是否包含所需的 CUDA 运行时。

总结

MinerU 的使用主要分三种： 1）本地依赖 + mineru-api 启服务，通过 HTTP 对接第三方项目（如我本地的 dify 项目）。 2）CLI 直接解析：mineru -p <input_path> -o <output_path>。 3）Docker 部署：在 Windows 11 + WSL2 下可结合 NVIDIA Container Toolkit 使用 GPU。
实操建议：
- 初学者先用“本地依赖 + mineru-api”快速验证功能，再接入项目。
- 需要批量处理/自动化时，CLI 或容器更易集成与迁移。

本文所有截图与环境基于我本机实测；如果你在安装或调用中遇到具体报错，欢迎贴日志我一起排查。