MinerU 3.4 の公式 CLI は、現在次の5つのバックエンド名に対応しています。
|
|
デフォルトのバックエンドは hybrid-engine で、Hybrid は標準で --effort medium を使います。この5つで混乱しやすいのはコマンドの書き方ではなく、モデルがローカルで動くのかリモートサーバーで動くのか、ローカル GPU が必須なのか、どの種類の PDF に向いているのかです。
先に結論を書くと、通常の電子 PDF や一括処理は pipeline、ローカルで総合的な品質を重視するなら hybrid-engine --effort medium、難しいスキャン文書は vlm-engine を個別に試す、モデルを別の GPU サーバーに置く場合だけ2つの HTTP Client を検討する、という選び方になります。
5つのモードの早見表
| バックエンド | 計算場所 | 主な方式 | ローカル GPU | 特徴 |
|---|---|---|---|---|
pipeline |
ローカル | OCR、レイアウト解析、数式認識など複数の専用モデルを組み合わせる | 任意 | 互換性が高く、安定し、ほぼ幻覚がない |
hybrid-engine |
ローカル | ネイティブテキスト抽出 + VLM + Pipeline | 必須、最低約 8GB | 総合精度が高く、多くの高品質解析に向く |
vlm-engine |
ローカル | 主に視覚言語モデルがページ全体を理解する | 必須、最低約 8GB | 複雑なスキャン、表、数式、特殊レイアウトに強い |
hybrid-http-client |
ローカル小モデル + リモート VLM | Hybrid だが大きなモデルはサーバーで実行 | ローカル GPU なしでも可 | 既存のリモート GPU サーバーがある場合に向く |
vlm-http-client |
リモートサーバー | VLM を完全にサーバーで実行 | ローカル GPU 不要 | ローカルはファイルをアップロードし、結果を受け取るだけ |
HTTP Client は「VRAM を節約できるローカルモード」ではなく、リモートデプロイ用のモードです。ローカルマシンは大きなモデルを動かさなくてもよい一方で、リモートサーバー側では VLM 推論が必要です。
pipeline：安定、省VRAM、一括処理向き
実行コマンド：
|
|
pipeline はページ全体を1つの大きなモデルに理解させるのではなく、複数の専用モジュールを組み合わせて処理します。
- PDF のネイティブテキスト抽出。
- OCR。
- レイアウト検出。
- 表認識。
- 数式認識。
- 読み順の整理。
利点は安定性と低いリソース要求です。CPU のみでも実行でき、NVIDIA GPU による高速化も可能です。公式では「高速、安定、幻覚なし」と説明されており、表の総合精度は約 86.47、GPU モードでは最低約 4GB の VRAM が必要とされています。
pipeline が向いているのは次のような場面です。
- 通常の電子 PDF。
- 大量の一括処理。
- テキスト中心の文書。
- モデルに内容を推測してほしくない場面。
- 8GB GPU で安定性を優先したい場合。
RTX 4060 8GB を使っているなら、これは最も無難なローカル GPU モードです。CUDA 環境が正常に動くか確認する最初のステップとしても使いやすいです。
vlm-engine：ページ全体を視覚言語モデルに任せる
実行コマンド：
|
|
vlm-engine は主に MinerU の視覚言語モデルを使い、ページを画像として理解します。タイトル、本文、表構造、数式、読み順、複雑なレイアウト間の関係を判断します。
表の精度は約 95.30 で、pipeline よりかなり高くなります。ただしローカル実行には最低約 8GB の VRAM が必要で、CPU のみのモードには対応していません。
vlm-engine が向いているのは次のような文書です。
- スキャンされた論文。
- 複雑な複数カラムレイアウト。
- 枠線が不規則な表。
- 数式が多いページ。
- 手書きや特殊なレイアウト。
pipelineの解析結果がよくないファイル。
欠点は VRAM 負荷が高いことです。また hybrid-engine と比べると、「PDF のネイティブテキストを優先して抽出し、難しい部分だけ VLM を使う」という総合的な利点は弱いため、日常のデフォルトにする必要はない場合があります。
hybrid-engine：Pipeline と VLM の組み合わせ
実行コマンド：
|
|
hybrid-engine は2つの方法を組み合わせます。
- 電子 PDF では、できるだけネイティブテキストを直接抽出する。
- スキャン部分、複雑な表、数式、特殊レイアウトでは VLM を呼び出す。
- Pipeline の一部モジュールで補助処理を行う。
そのため、VLM の高い精度、ネイティブテキスト抽出の信頼性、低い幻覚リスク、多言語電子 PDF への対応をバランスよく得られます。公式では「高精度、ネイティブテキスト抽出、低幻覚」と位置づけられており、現在推奨されるローカル既定モードです。
Hybrid にはよく使う強度が2つあります。
Medium：
|
|
表の精度は約 95.26 です。速度が速く、ほとんどの文書に向いています。現在のデフォルトは medium ですが、Medium では画像とグラフの解析が自動的に無効になります。
High：
|
|
表の精度は約 95.39 です。画像とグラフの解析に対応しますが、処理速度は遅くなります。公式データでは Medium は High より約 0.13 ポイント低いだけですが、Windows の一部環境ではかなり速くなることがあります。
RTX 4060 8GB を使っている場合、hybrid-engine --effort medium がローカル高品質解析の第一候補です。8GB は必要条件の下限に近いため、実行前にゲーム、ブラウザのハードウェアアクセラレーション、その他 VRAM を使うアプリを閉じておくのがおすすめです。
vlm-http-client：ローカルではモデルを実行しない
実行例：
|
|
このモードでは、あなたの PC はクライアントとして動きます。
|
|
実際の VLM モデルは、別の GPU PC、Linux GPU サーバー、LAN 内サーバー、または OpenAI API 互換の推論サービス上で動きます。そのためローカル側に NVIDIA GPU は不要で、軽量版 MinerU だけでも利用できます。公式ドキュメントでも、vlm-http-client は CPU とネットワーク接続だけを持つエッジデバイスに向くと説明されています。
注意点は、「ローカル GPU が不要」という意味であって、システム全体で GPU が不要という意味ではありません。リモートサーバー側では VLM 推論を行います。
hybrid-http-client：ローカルとサーバーで役割分担
実行コマンド：
|
|
hybrid-http-client は vlm-http-client と同じではありません。通常は次のように動きます。
- ローカルが PDF テキスト抽出と一部の小モデル処理を担当する。
- リモートサーバーが VLM 推論を担当する。
- 最後に結果を組み合わせる。
そのためローカルは CPU のみでも使えます。GPU がある場合は、ローカル補助処理が速くなります。公式ではクライアントに mineru[pipeline] をインストールすることが推奨されています。表にある最低約 2GB の VRAM は、主に Hybrid クライアント側の小モデルをローカル GPU で高速化する場合の目安であり、リモート VLM サーバーが 2GB だけでよいという意味ではありません。
HTTP Client と Engine の精度が同じ理由
公式表では、次のような結果が示されています。
|
|
理由は、両者が基本的に同じ解析ロジックとモデルを使っているためです。違いは主にモデルの実行場所です。
hybrid-engine：モデルはローカル GPU で動く。hybrid-http-client：モデルはリモートサーバーで動く。
つまり HTTP Client は低精度版ではなく、リモートデプロイ版です。すでに GPU サーバーを持っているチーム向けであり、単体 PC のユーザーが気軽に VRAM 節約のために切り替えるモードではありません。
RTX 4060 8GB ならどう選ぶか
RTX 4060 8GB を使っているなら、次の順番で選ぶと分かりやすいです。
日常的に安定して使う：
|
|
VRAM 負荷が小さく、CUDA 環境の確認にも、通常 PDF の一括処理にも向いています。
ローカルで総合品質を重視する：
|
|
8GB GPU での高精度モードの第一候補です。実行時はできるだけ VRAM を空けておきます。
画像解析や最高精度が必要：
|
|
遅くなりますが、画像とグラフの解析が有効になります。
複雑なスキャン文書で結果がよくない：
|
|
Hybrid の結果と比較できますが、通常は常用デフォルトにする必要はありません。
リモートサーバーがない場合は、次の2つは考えなくてよいです。
|
|
これらは別途 OpenAI 互換の推論サーバー、または利用可能なリモート GPU マシンを必要とします。
一言で選ぶなら
通常 PDF、一括処理、安定優先：
|
|
ローカルでの総合品質優先：
|
|
画像解析または最高精度：
|
|
非常に複雑なスキャンレイアウトを VLM 単体で試したい：
|
|
モデルを別の GPU サーバーに置く：
|
|
最後に PyTorch 環境も確認してください。現在がまだ torch 2.8.0+cpu の場合、CUDA 版 PyTorch に入れ替えるまでは pipeline は CPU 実行のみになり、hybrid-engine と vlm-engine も RTX 4060 を実際には使えません。