Windows 本地部署 MinerU（Anaconda + NVIDIA 显卡）并提供 HTTP 接口

文章	评论	标签
56	53	11

适用环境：Windows 10/11、NVIDIA 显卡、Anaconda，MinerU 3.x 版本。
目标：在本机部署 MinerU，通过 HTTP 接口给其他服务调用，并支持 PDF、Word、PPT、Excel 等常见文档。

前言

MinerU 是 OpenDataLab 开源的文档解析工具，可以把 PDF、图片、DOCX、PPTX、XLSX 转换成 Markdown / JSON，常用于 RAG 知识库的数据预处理。

很多教程默认使用 Docker 部署，但 Windows 上不方便或者不能用 Docker 的情况下，也完全可以直接用 Python 环境部署。而且 MinerU 自带 HTTP 服务（mineru-api），不需要自己写服务端程序，装好后一条命令就能启动接口，调用方只需要发 HTTP 请求即可。

本文记录完整的安装过程，以及我踩到的一个坑：Can not find $env:CUDA_PATH。

一、先了解 MinerU 的几种解析后端

MinerU 有五种解析后端，通过 -b 参数（命令行）或 backend 参数（HTTP 接口）切换：

后端	原理	适合场景	Windows 是否需要 CUDA Toolkit
`pipeline`	传统小模型组合（版面检测 + OCR + 表格 + 公式识别）	普通电子版 PDF、大批量任务，稳定、速度快	不需要
`hybrid-engine`	pipeline + VLM 大模型结合，默认后端	综合精度最高	需要
`vlm-engine`	纯 VLM 大模型端到端解析	扫描件、复杂版面	需要
`hybrid-http-client`	本地跑小模型，VLM 推理交给远程服务器	本机无显卡，另有 GPU 服务器	不需要
`vlm-http-client`	完全交给远程服务器推理	本机无显卡，另有 GPU 服务器	不需要

注意：不加 -b 参数时默认使用 hybrid-engine。

为什么 hybrid / vlm 需要单独安装 CUDA Toolkit？

用过 PyTorch 的同学可能会疑惑：pip 装 GPU 版 torch 时不是已经自带 CUDA 了吗？

PyTorch：GPU 版安装包里自带了 CUDA 运行库（DLL 在 site-packages\torch\lib 下），只要显卡驱动够新就能用。pipeline 后端只依赖 torch，所以不需要 CUDA Toolkit。
lmdeploy（TurboMind 引擎）：MinerU 的 hybrid / vlm 后端在 Windows 上使用 lmdeploy 的 TurboMind 推理引擎。它是独立编译的 C++/CUDA 引擎，Windows 安装包没有打包 CUDA 运行库，启动时会读取 CUDA_PATH 环境变量去系统里找 CUDA 的 DLL。没有安装 CUDA Toolkit 就会报错：

AssertionError: Can not find $env:CUDA_PATH

所以结论是：只用 pipeline 可以不装 CUDA Toolkit；想用默认的 hybrid 或 vlm 后端，必须装。

显卡架构也有要求：20 系显卡建议直接用 pipeline

装好 CUDA Toolkit 也不代表 hybrid / vlm 一定能跑。我的显卡是 RTX 2080 Ti 22G（Turing 架构，计算能力 7.5），在 torch、CUDA Toolkit 版本完全对齐（都是 12.6）的情况下，hybrid 后端仍然在 TurboMind 引擎初始化时报错（见文末常见问题）。TurboMind 的优化内核主要面向 30 系（Ampere）及以上架构，20 系显卡在 Windows 上建议直接使用 pipeline 后端。

动手之前可以先查一下自己显卡的计算能力：

nvidia-smi --query-gpu=name,memory.total,compute_cap --format=csv

compute_cap 为 7.5 是 20 系，8.6 是 30 系，8.9 是 40 系。7.5 及以下的显卡可以跳过 CUDA Toolkit 的安装，直接用 pipeline。

二、安装步骤

以下命令全部在 Anaconda Prompt 中执行（开始菜单搜索 "Anaconda Prompt"）。

第 1 步：确认显卡驱动

nvidia-smi

查看输出右上角的 CUDA Version（例如 12.8），这是当前驱动支持的最高 CUDA 版本，后面安装 torch 和 CUDA Toolkit 时版本不能超过它。如果版本太低，先去 NVIDIA 官网更新显卡驱动。

第 2 步：创建 conda 环境

MinerU 在 Windows 上只支持 Python 3.10 ~ 3.12（依赖的 ray 不支持 Windows 下的 Python 3.13），这里使用 3.12：

conda create -n mineru python=3.12 -y
conda activate mineru

第 3 步：安装 MinerU

python -m pip install --upgrade pip
pip install uv
uv pip install -U "mineru[all]"

如果 uv 安装出错，可以直接用 pip，国内网络可以加清华镜像：

pip install -U "mineru[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

第 4 步：安装 GPU 版 PyTorch

上一步默认装的通常是 CPU 版 torch，需要卸载后重装 GPU 版：

pip uninstall -y torch torchvision

根据第 1 步看到的 CUDA Version 选择一条执行（其他版本请到 https://pytorch.org/get-started/locally/ 查询）：

:: 驱动显示 CUDA 12.8 或更高
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

:: 驱动显示 CUDA 12.6 ~ 12.7
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

验证 GPU 是否可用：

python -c "import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.get_device_name(0))"

输出中出现 True 和显卡名称即为成功。

第 5 步：安装 CUDA Toolkit（使用 hybrid / vlm 后端时必须）

只打算用 pipeline 后端的可以跳过这一步。

到 NVIDIA 官网下载 CUDA Toolkit：https://developer.nvidia.com/cuda-toolkit-archive
版本与第 4 步安装的 torch 保持一致：装的是 cu128 就下载 CUDA 12.8，cu126 就下载 12.6。
选择 Windows → x86_64 → 系统版本 → exe (local)。
安装时选择 "自定义"，只勾选 CUDA 下面的组件，取消勾选 Display Driver，避免覆盖已有的新版驱动。
安装程序会自动设置 CUDA_PATH 环境变量。

安装完成后，关闭所有 Anaconda Prompt 窗口，重新打开，验证：

conda activate mineru
echo %CUDA_PATH%
nvcc --version

能输出类似 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8 的路径和 nvcc 版本号即为成功。

第 6 步：配置模型源并下载模型

MinerU 默认从 HuggingFace 下载模型，国内网络建议切换为 ModelScope。下面的命令会把环境变量绑定到 mineru 这个 conda 环境，以后每次激活自动生效：

conda env config vars set MINERU_MODEL_SOURCE=modelscope
conda deactivate
conda activate mineru

下载模型（按提示选择，建议全部下载）：

mineru-models-download

三、命令行测试

准备一个测试文件，先用 pipeline 后端测试基础环境：

mineru -p D:\test\test.pdf -o D:\test\output -b pipeline

再测试默认的 hybrid 后端：

mineru -p D:\test\test.pdf -o D:\test\output

解析过程中另开一个窗口执行 nvidia-smi，能看到 python 进程占用显存，说明 GPU 加速已生效。

四、启动 HTTP 服务

conda activate mineru
mineru-api --host 0.0.0.0 --port 8000

启动后在浏览器打开 http://127.0.0.1:8000/docs，可以看到 Swagger 接口文档，所有参数名以这个页面为准。

主要接口：

接口	说明
`GET /health`	健康检查
`POST /file_parse`	同步解析，等待解析完成后直接返回结果
`POST /tasks`	异步提交任务，立即返回 `task_id`
`GET /tasks/{task_id}`	查询任务状态
`GET /tasks/{task_id}/result`	获取任务结果

几点说明：

后端在每次请求时通过 backend 参数指定，启动服务时不需要指定。注意 HTTP 接口里的取值是 pipeline、hybrid-engine、vlm-engine、hybrid-http-client、vlm-http-client，不传则默认 hybrid-engine。如果你的显卡跑不了 hybrid（例如 20 系），每次请求都必须显式传 backend=pipeline。
hybrid 后端有一个 effort 参数，默认 medium，medium 会关闭图片/图表分析，需要识别图表内容时要传 effort=high。
return_content_list、return_images 默认是 false，需要结构化内容和图片时要手动开启。
任务状态保存在服务进程内存中，服务重启后历史任务无法查询。
默认任务完成 24 小时后自动清理结果，调用方拿到结果后应自行保存。
如果调用方在另一台机器上，需要在 Windows 防火墙中放行 8000 端口。

curl 测试

curl -X POST http://127.0.0.1:8000/file_parse -F "files=@test.pdf" -F "backend=pipeline" -F "return_md=true"

Python 调用示例（同步）

import requests

BASE = "http://127.0.0.1:8000"

with open("test.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE}/file_parse",
        files={"files": f},
        data={
            "backend": "hybrid-engine",  # 或 pipeline / vlm-engine
            "return_md": "true",
        },
        timeout=1800,  # 大文件解析时间较长，超时时间设长一些
    )

resp.raise_for_status()
print(resp.json())

Python 调用示例（异步 + 轮询）

大文件建议使用异步接口，避免 HTTP 请求超时：

import time
import requests

BASE = "http://127.0.0.1:8000"

# 1. 提交任务
with open("test.pdf", "rb") as f:
    resp = requests.post(
        f"{BASE}/tasks",
        files={"files": f},
        data={"backend": "hybrid-engine", "return_md": "true"},
    )
task_id = resp.json()["task_id"]
print("任务已提交:", task_id)

# 2. 轮询任务状态（状态字段的具体取值请以 /docs 中的实际返回为准）
while True:
    status = requests.get(f"{BASE}/tasks/{task_id}").json()
    print("当前状态:", status.get("status"))
    if status.get("status") in ("completed", "failed"):
        break
    time.sleep(3)

# 3. 获取结果
result = requests.get(f"{BASE}/tasks/{task_id}/result").json()
print(result)

五、Word、PPT、Excel 文档怎么处理

新版格式：直接解析

MinerU 3.x 已经原生支持 DOCX、PPTX、XLSX，不需要转换，直接传给命令行或 HTTP 接口即可：

mineru -p D:\test\test.docx -o D:\test\output

老版格式：用 LibreOffice 转换

老版的 .doc、.ppt、.xls 需要先转换。这一步不需要大模型，推荐使用免费的 LibreOffice，它支持无头模式命令行转换。

为什么不用 Python 库？Python 生态里没有纯 Python 实现的高质量 Office 格式转换库。常见的 docx2pdf、pywin32 本质上是调用本机安装的微软 Office，要求安装 Office，而且不适合服务端并发调用。

下载地址：https://www.libreoffice.org/download/download/

安装后命令行测试：

"C:\Program Files\LibreOffice\program\soffice.exe" --headless --convert-to docx --outdir D:\test\output D:\test\old.doc

Python 预处理代码

import subprocess
import tempfile
from pathlib import Path

SOFFICE = r"C:\Program Files\LibreOffice\program\soffice.exe"

# 老格式 -> 新格式
LEGACY_MAP = {".doc": "docx", ".ppt": "pptx", ".xls": "xlsx"}
# MinerU 可直接解析的格式
NATIVE_EXTS = {".pdf", ".docx", ".pptx", ".xlsx", ".png", ".jpg", ".jpeg"}


def prepare_file(src: str, work_dir: str) -> Path:
    """返回一个 MinerU 可以直接解析的文件路径"""
    src = Path(src)
    ext = src.suffix.lower()

    if ext in NATIVE_EXTS:
        return src

    if ext in LEGACY_MAP:
        target = LEGACY_MAP[ext]
        # 每次使用独立的 LibreOffice 配置目录，避免并发调用时互相冲突
        profile = Path(tempfile.mkdtemp()).as_uri()
        subprocess.run(
            [
                SOFFICE,
                f"-env:UserInstallation={profile}",
                "--headless",
                "--convert-to", target,
                "--outdir", work_dir,
                str(src),
            ],
            check=True,
            timeout=300,
        )
        out = Path(work_dir) / f"{src.stem}.{target}"
        if not out.exists():
            raise RuntimeError(f"转换失败: {src}")
        return out

    raise ValueError(f"不支持的格式: {ext}")

如果想统一转成 PDF，把 target 改为 "pdf" 即可。

原生解析还是转 PDF？

DOCX/PPTX 原生解析：直接读取文档中的文字和结构，速度快，文字不会识别错误。
转 PDF 后解析：走版面分析流程，适合排版复杂、大量文本框、图文混排的文档。

建议先用原生解析测试自己的实际文档，效果不理想的类型再改为转 PDF。

六、常见问题

1. `AssertionError: Can not find $env:CUDA_PATH`

使用了 hybrid 或 vlm 后端，但没有安装 CUDA Toolkit。解决方法：按第二章第 5 步安装 CUDA Toolkit，安装后重新打开 Anaconda Prompt；或者改用 -b pipeline。

2. `[TM][FATAL] kernels\gemm\tuner\measurer.cu(83): Check failed: status == cudaSuccess invalid argument`

CUDA Toolkit 已经找到（日志中有 Add dll path ...CUDA\v12.6\bin），但 TurboMind 引擎在启动时对显卡做矩阵运算性能测试失败。排查顺序：

查看显卡计算能力：nvidia-smi --query-gpu=name,compute_cap --format=csv
如果是 7.5（20 系显卡，包括魔改 2080 Ti 22G）：这是显卡架构支持问题，不是配置问题，建议改用 -b pipeline。我的环境（2080 Ti 22G，torch 2.14.0+cu126，CUDA Toolkit 12.6，lmdeploy 0.11.1）就属于这种情况。
如果是 8.x 及以上（30/40 系）：检查 torch 的 CUDA 版本（python -c "import torch; print(torch.version.cuda)"）和 CUDA Toolkit 版本是否一致，不一致则重装对齐。

3. `lmdeploy check_env` 报错 `Microsoft Visual C++ 14.0 or greater is required`

这是环境信息收集工具在检测 C++ 编译器时报的错，不影响 MinerU 和 lmdeploy 的正常运行，可以忽略。

4. `torch.cuda.is_available()` 返回 False

装的是 CPU 版 torch：按第 4 步卸载后重装 GPU 版。
显卡驱动太旧：更新驱动，确保 nvidia-smi 显示的 CUDA Version 不低于 torch 的 CUDA 版本。

5. 和 Ollama 等其他模型程序共用显卡

MinerU 解析时和 Ollama 同时加载大模型可能导致显存不足。批量解析前可以先释放 Ollama 占用的显存：

ollama ps
ollama stop 模型名

如果机器上有多张显卡，也可以让 MinerU 只使用其中一张，另一张留给 Ollama：

set CUDA_VISIBLE_DEVICES=0
mineru-api --host 0.0.0.0 --port 8000

6. 模型下载慢或失败

确认已设置 MINERU_MODEL_SOURCE=modelscope，可以用 echo %MINERU_MODEL_SOURCE% 检查。

七、日常启动

conda activate mineru
mineru-api --host 0.0.0.0 --port 8000

如果需要开机自启，可以使用 NSSM 将 mineru-api 注册为 Windows 服务。先查询可执行文件的完整路径：

where mineru-api

然后在 NSSM 中配置该路径和启动参数 --host 0.0.0.0 --port 8000，并在环境变量中加入 MINERU_MODEL_SOURCE=modelscope。

参考

MinerU GitHub：https://github.com/opendatalab/MinerU
MinerU 官方文档：https://opendatalab.github.io/MinerU/zh/
PyTorch 安装：https://pytorch.org/get-started/locally/
CUDA Toolkit 历史版本：https://developer.nvidia.com/cuda-toolkit-archive
LibreOffice 下载：https://www.libreoffice.org/download/download/