1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@engchina

RTX 4090 + WSL2 で MinerU 3.1.4 を GPU / vLLM 付きで動かしてみた

1
Posted at

image.png

先に結論

WSL2 上の Ubuntu 22.04 環境で、MinerU 3.1.4 を GPU / vLLM 付きでインストールして、PDF 解析まで動かせました。

今回の構成はこうです。

項目 値
OS Ubuntu 22.04.5 LTS on WSL2
GPU NVIDIA GeForce RTX 4090
VRAM 24GB
NVIDIA Driver 591.74
nvidia-smi CUDA 13.1
CUDA Toolkit 12.6.85
Python 3.12.13
MinerU 3.1.4
PyTorch 2.9.0+cu128
vLLM 0.11.2

ポイントは、base 環境をそのまま使わず、Python 3.12 の専用 Conda 環境を作ったことです。

base 側は Python 3.13.5 でした。MinerU 自体は Python 3.13 もサポート範囲に入っていますが、Torch / vLLM / 画像処理系の依存を考えると、Python 3.12 のほうが無難でした。

この記事で分かること

この記事では、次の内容をまとめます。

  • RTX 4090 環境で MinerU を GPU 対応で入れる手順
  • mineru[all] で vLLM まで入れる方法
  • ModelScope からモデルをダウンロードする方法
  • torch.cuda.is_available() で CUDA を確認する方法
  • hybrid-auto-engine で実際に PDF を解析するところ

対象読者

  • ローカル GPU で MinerU を動かしたい人
  • WSL2 + NVIDIA GPU 環境で PDF 解析環境を作りたい人
  • vLLM を使って MinerU の VLM 解析を高速化したい人
  • CPU 版ではなく、ちゃんと GPU に乗っているか確認したい人

今回の環境

まず GPU を確認します。

nvidia-smi

今回の環境では、RTX 4090 が見えていました。

GPU: NVIDIA GeForce RTX 4090
Driver Version: 591.74
CUDA Version: 13.1
VRAM: 24564 MiB

CUDA Toolkit 側は 12.6 でした。

nvcc --version

Cuda compilation tools, release 12.6, V12.6.85

ここで少しややこしいのは、nvidia-smi の CUDA 表示と、PyTorch が使う CUDA runtime は必ずしも同じではないことです。

今回の PyTorch は 2.9.0+cu128 で入りました。つまり PyTorch wheel 側は CUDA 12.8 系です。

実際には問題なく RTX 4090 を認識できました。

1. Conda 環境を作る

既存環境を汚したくなかったので、専用環境を作ります。

cd /u01/workspace/mineru

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

作成後の Python はこうなりました。

python --version

Python 3.12.13

2. pip と uv を入れる

中国大陸ネットワークを想定して、PyPI は Aliyun mirror を使いました。

python -m pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple
python -m pip install uv -i https://mirrors.aliyun.com/pypi/simple

uv は依存解決とインストールが速いので、今回は MinerU のインストールにも使います。

3. MinerU を GPU / vLLM 付きでインストールする

リポジトリ直下で、editable install します。

cd /u01/workspace/mineru
uv pip install -e ".[all]" -i https://mirrors.aliyun.com/pypi/simple

今回入った主要パッケージは次の通りです。

mineru       3.1.4
torch        2.9.0
torchvision  0.24.0
vllm         0.11.2
transformers 4.57.6

.[all] を入れると、Linux では core に加えて vLLM 関連も入ります。

もし vLLM のインストールで詰まる場合は、まずは次のように core だけで入れて、pipeline / transformers 側で動作確認するのが現実的です。

uv pip install -e ".[core]" -i https://mirrors.aliyun.com/pypi/simple

4. コマンドが入ったか確認する

mineru --version

mineru, version 3.1.4

ついでに API と WebUI のコマンドも確認します。

mineru-api --help
mineru-gradio --help

5. CUDA が Python から見えるか確認する

ここは必ず確認したほうがいいです。

nvidia-smi で GPU が見えていても、Python 環境に CPU 版 torch が入っていると、MinerU からは GPU を使えません。

確認コマンドはこちらです。

python -c "import torch, vllm; print('torch', torch.__version__); print('torch cuda', torch.version.cuda); print('cuda available', torch.cuda.is_available()); print('device', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'no cuda'); print('vllm', vllm.__version__)"

今回の結果です。

torch 2.9.0+cu128
torch cuda 12.8
cuda available True
device NVIDIA GeForce RTX 4090
vllm 0.11.2

ここで cuda available True が出れば、かなり安心です。

6. ModelScope からモデルをダウンロードする

MinerU はモデルを Hugging Face または ModelScope から取得できます。

今回は ModelScope を使いました。

まず既存の設定をバックアップします。

cp ~/mineru.json ~/mineru.json.bak.20260427_1009

次に、pipeline と VLM のモデルをまとめてダウンロードします。

export MINERU_MODEL_SOURCE=modelscope
mineru-models-download -s modelscope -m all

ダウンロード後、~/mineru.json は次のように更新されました。

{
  "models-dir": {
    "pipeline": "/root/ModelScopeCache/models/OpenDataLab/PDF-Extract-Kit-1___0",
    "vlm": "/root/ModelScopeCache/models/OpenDataLab/MinerU2___5-Pro-2604-1___2B"
  },
  "config_version": "1.3.1"
}

モデルサイズはこのくらいでした。

pipeline model: 3.5G
VLM model:      2.2G

次回以降は、ローカルモデルを使うようにします。

export MINERU_MODEL_SOURCE=local

7. PDF 解析を実行する

リポジトリに含まれているサンプル PDF で確認します。

cd /u01/workspace/mineru
conda activate mineru-3-gpu
export MINERU_MODEL_SOURCE=local
export CUDA_VISIBLE_DEVICES=0

mineru -p demo/pdfs/demo1.pdf -o output/gpu_smoke -b hybrid-auto-engine

今回のログでは、次のように vllm-async-engine が選ばれていました。

Using vllm-async-engine as the inference engine for VLM.

つまり、単に MinerU が動いただけではなく、VLM 側が vLLM 経由で GPU に乗っています。

8. 出力結果

解析後、次のようなファイルが生成されました。

output/gpu_smoke/demo1/hybrid_auto/demo1.md
output/gpu_smoke/demo1/hybrid_auto/demo1_middle.json
output/gpu_smoke/demo1/hybrid_auto/demo1_content_list.json
output/gpu_smoke/demo1/hybrid_auto/demo1_content_list_v2.json
output/gpu_smoke/demo1/hybrid_auto/demo1_model.json
output/gpu_smoke/demo1/hybrid_auto/demo1_layout.pdf
output/gpu_smoke/demo1/hybrid_auto/images/

13 ページの PDF が正常に処理されました。

初回はモデルロードと vLLM の CUDA graph capture が走るため、少し時間がかかります。

ただし、ログを見る限り、モデルロード後の実処理はかなり速いです。

9. API サーバーとして使う

CLI だけでなく、API サーバーとしても起動できます。

cd /u01/workspace/mineru
conda activate mineru-3-gpu
export MINERU_MODEL_SOURCE=local
export CUDA_VISIBLE_DEVICES=0

mineru-api --host 0.0.0.0 --port 8000 --enable-vlm-preload true

起動後は、次の URL で API ドキュメントを見られます。

http://127.0.0.1:8000/docs

WSL2 の場合でも、多くの環境では Windows 側のブラウザからそのまま 127.0.0.1:8000 にアクセスできます。

疎通確認はこれです。

curl http://127.0.0.1:8000/health

10. Gradio WebUI として使う

ブラウザで手軽に試したい場合は、Gradio WebUI が便利です。

cd /u01/workspace/mineru
conda activate mineru-3-gpu
export MINERU_MODEL_SOURCE=local
export CUDA_VISIBLE_DEVICES=0

mineru-gradio --server-name 0.0.0.0 --server-port 7860 --enable-vlm-preload true

アクセス先はこちらです。

http://127.0.0.1:7860

11. やってみて分かったこと

今回いちばん大事だったのは、インストール手順そのものよりも、環境を分けることでした。

既存の Conda 環境には、すでに別バージョンの MinerU や Torch が入っていました。

そのまま上書きすると、動いたとしても後から原因不明の依存衝突が起きやすくなります。

今回のように、次のような方針にしたほうが安定します。

  • MinerU 3.x 用に専用 Conda 環境を作る
  • Python は 3.12 を使う
  • mineru[all] で vLLM までまとめて入れる
  • モデルは MINERU_MODEL_SOURCE=local で固定する
  • 最後に torch.cuda.is_available() と実 PDF 解析で確認する

12. よくある詰まりどころ

nvidia-smi は見えるのに torch.cuda.is_available() が False

CPU 版 torch が入っているか、別の Python 環境を見ている可能性があります。

まずは今いる環境を確認します。

which python
python --version
python -m pip show torch

vLLM のインストールが失敗する

まず Python 3.12 の専用環境になっているか確認します。

それでも難しい場合は、mineru[core] で先に動作確認するか、Docker 版に逃がすのが現実的です。

WSL2 で pin_memory=False の warning が出る

今回も出ました。

Using 'pin_memory=False' as WSL is detected.

これは WSL2 検出時の warning で、今回の実行では失敗原因ではありませんでした。

初回だけ遅い

初回はモデルロード、torch compile、CUDA graph capture が走ります。

今回も cold start では 1 分以上かかりました。

ただし、一度ロードされると実際の解析処理は速くなります。

まとめ

RTX 4090 + WSL2 でも、MinerU 3.1.4 は GPU / vLLM 付きで問題なく動きました。

今回の最終確認は次の状態です。

MinerU: 3.1.4
Python: 3.12.13
Torch: 2.9.0+cu128
vLLM: 0.11.2
CUDA available: True
Device: NVIDIA GeForce RTX 4090
Backend: hybrid-auto-engine -> vllm-async-engine

PDF 解析結果も demo1.md、middle.json、content_list.json、画像、layout PDF まで生成されました。

個人的には、MinerU の GPU インストールで重要なのは「CUDA を入れること」より、Python / Torch / vLLM / モデルパスをきれいに揃えることだと感じました。

そこさえ揃えば、hybrid-auto-engine はかなり素直に動きます。

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?