MinerU — PDF → Markdown

Opendatalab 出品，magic-pdf 的后继者。v3.4.0 起是 namespace package，安装 mineru[core]。 约 2GB 依赖（torch + transformers + onnxruntime），无需 GPU 可用 pipeline 后端。

快速安装 (Windows, no GPU)

# 标准安装
uv pip install "mineru[core]" --python "D:/Hermes/hermes-agent/.venv/Scripts/python.exe"

# 国内网络用腾讯云镜像（2026-06 实测最稳）
uv pip install "mineru[core]" --python "D:/Hermes/hermes-agent/.venv/Scripts/python.exe" \
  -i https://mirrors.cloud.tencent.com/pypi/simple/

安装后验证：

uv pip list --python "<venv-python>" | grep mineru
# mineru 3.4.0, mineru-vl-utils 1.0.5

python -c "from mineru import version; print(version.__version__)"
# 3.4.0

CLI 核心用法

# 基础转换（pipeline 后端，中文 OCR）
python -m mineru.cli.client -p input.pdf -o ./output -b pipeline -l ch

# 高精度（hybrid engine，含图表分析）
python -m mineru.cli.client -p input.pdf -o ./output -b hybrid-engine --effort high -l ch

# 纯文本提取（跳过 OCR，最快）
python -m mineru.cli.client -p input.pdf -o ./output -m txt -b pipeline -l ch

# 指定页码范围（0-indexed）
python -m mineru.cli.client -p input.pdf -o ./output -s 0 -e 5 -b pipeline -l ch

# 远程 API（无需本地 GPU）
python -m mineru.cli.client -p input.pdf -o ./output -b vlm-http-client -u http://server:30000 -l ch

CLI 参数速查

后端选型（无 GPU Windows）

无 GPU 推荐：先用 pipeline（稳定），需要更高精度时切 vlm-http-client 指向远程 GPU 服务。

包结构（非显而易见）

• mineru 是 namespace package：__init__.py 仅 50 字节，dir(mineru) 为空
• 实际代码在子目录：mineru.cli.client（CLI 入口）、mineru.backend、mineru.model、mineru.utils
• 没有 magic_pdf 包——v3.x 已将旧 magic-pdf 合并进 mineru
• 正确的 import：from mineru.cli.client import ...（或直接用 CLI）

常见坑

uv 锁冲突

同时跑多个 uv pip install 会抢 D:\sofeware\cache\uv\ 的锁。错误信息：

Timeout (300s) when waiting for lock on `D:\sofeware\cache\uv\wheels-v6\pypi\...`

修法：kill 掉多余的进程，留一个就行。或设 UV_LOCK_TIMEOUT=600。

pip 不在 venv 里

Hermes 的 venv 精简过，没有 pip。用 uv pip install，不要用 python -m pip。

python -m mineru.cli.client --help 卡住

首次运行可能在做模型预热，用 --version 快速验证安装即可。

中文镜像不稳定

清华镜像 (tuna) 和阿里云镜像在 2026-06 实测超时。 腾讯云镜像 mirrors.cloud.tencent.com 可用。 PyPI 直连 files.pythonhosted.org 也可用（慢但不断）。

与其他工具对比

MinerU 是 marker-pdf 的强力替代品——更多后端选择，原生支持远程推理。