AIツール

MinerU 使用ガイド：PDF、Office、画像を RAG 向け Markdown/JSON に解析する

opendatalab/MinerU の機能、インストール方法、CLI の使い方、デプロイ選択肢、適用範囲を整理し、PDF、Office ドキュメント、画像を RAG と Agent ワークフローで使える Markdown/JSON に変換する方法を紹介します。

opendatalab/MinerU は、大規模モデル向けのデータ準備に使うドキュメント解析ツールです。PDF、画像、DOCX、PPTX、XLSX などの入力を Markdown、JSON、中間的な構造化結果に変換し、RAG、情報抽出、ナレッジベース構築、Agent ワークフローへつなげやすくします。

MinerU が扱う問題はかなり具体的です。実際の文書には、複数カラムのレイアウト、表、数式、ヘッダーとフッター、スキャンページ、手書き文字、画像キャプションが混在します。これらをそのまま大規模モデルに渡すと、読み順の崩れ、表構造の欠落、読めない数式、過剰な OCR ノイズが起きやすくなります。MinerU は先にレイアウト、テキスト、表、数式、OCR を解析し、「機械が読みやすい」かつ「人間の読み順に近い」結果を出力します。

どんな問題に向いているか

MinerU は次のような場面に向いています。

  • 論文、レポート、契約書、マニュアルを Markdown に解析する；
  • RAG ナレッジベース向けに、よりきれいな文書分割入力を準備する；
  • スキャン PDF や画像からテキスト、表、数式を抽出する；
  • DOCX、PPTX、XLSX を後続処理で扱いやすい構造化データにそろえる；
  • ローカルまたはプライベート環境で文書をバッチ処理する；
  • LangChain、LlamaIndex、Dify、RAGFlow、FastGPT などのフレームワーク向けにデータを準備する。

単にレイアウトが簡単なテキスト PDF を読むだけなら、通常の PDF 抽出ツールで十分な場合があります。MinerU の価値は、複雑なレイアウト、表と数式、複数フォーマット入力、文書データのバッチ生成が必要になったときに出ます。

主な機能

プロジェクト README によると、MinerU は PDF、画像、DOCX、PPTX、XLSX の入力をサポートし、Markdown、読み順に並べた JSON、解析品質を確認するための可視化結果を出力できます。

重要な機能は次のとおりです。

  • ヘッダー、フッター、脚注、ページ番号などのノイズを自動で除去；
  • 単一カラム、複数カラム、複雑なレイアウトに対して、人間の読み順でテキストを出力；
  • 見出し、段落、リストなどの文書構造を保持；
  • 画像、画像説明、表、表タイトル、脚注を抽出；
  • 数式を認識して LaTeX に変換；
  • 表を認識して HTML に変換；
  • スキャン PDF と文字化け PDF を自動検出し、OCR を有効化；
  • OCR は 109 言語をサポート；
  • CLI、FastAPI、Gradio WebUI、mineru-router を提供。

2026 年 4 月の 3.1.0 では、PPTX と XLSX のネイティブ解析が追加され、メイン VLM モデルが MinerU2.5-Pro-2604-1.2B にアップグレードされました。GitHub release ページによると、2026 年 6 月 4 日に公開された 3.2.3 では、上付き・下付きの検出と出力、さらに私用領域文字を扱うための post-OCR fallback 機構が追加されています。

インストール方法

ローカルで試すだけなら、公式は先に uv をインストールし、その後フル機能パッケージを入れる方法を示しています。

1
2
3

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

ソースコードからもインストールできます。

1
2
3

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[all]

mineru[all] には主要機能が含まれ、Windows、Linux、macOS に対応すると説明されています。ただし、文書解析はハードウェアと依存関係の影響を受けやすく、特に GPU、推論フレームワーク、Python バージョン、OS 環境に注意が必要です。本番デプロイの前に小さなサンプルで動作を確認し、その後バッチ処理に進むのが無難です。

最初の文書解析

基本コマンドでは、入力パスと出力パスを指定します。

1

mineru -p <input_path> -o <output_path>

GPU アクセラレーションの条件を満たさない場合は、pipeline バックエンドを指定して CPU のみで実行できます。

1

mineru -p <input_path> -o <output_path> -b pipeline

<input_path> は単一ファイルでもディレクトリでも構いません。実際には、まず代表的な文書だけを入れた小さなディレクトリから始めるとよいでしょう。

1

mineru -p ./samples -o ./output -b pipeline

これにより、出力品質、処理時間、メモリ使用量、ファイル構造を確認してから、文書ライブラリ全体に広げるか判断できます。

出力結果の使い方

MinerU の出力は、いくつかの下流ワークフローに接続できます。

1 つ目は RAG です。Markdown をチャンク分割とベクトル化の入力として使い、見出し、段落、リスト、表、数式をできるだけ元の意味構造のまま保てます。すべてを OCR で大きなテキスト塊にするより、構造化 Markdown のほうが分割、引用、結果の追跡を行いやすくなります。

2 つ目は情報抽出です。JSON と中間結果は、表、数式、画像説明、特定セクションを抽出する後続スクリプトに向いています。レポート、論文、契約書のフィールドを自動整理する場面では、純テキストだけを扱うより安定します。

3 つ目は人間によるレビューです。MinerU はレイアウトや span などの可視化結果を提供し、内容の欠落、読み順の妥当性、表の崩れを確認できます。バッチ処理の前には、まずサンプルを抽出してこれらの可視化結果を見るのがおすすめです。

バックエンドの選び方

MinerU のドキュメントでは、主に次のバックエンドが説明されています。

  • pipeline：互換性が高く、CPU または GPU で動作し、試用や通常のバッチ処理に向く；
  • vlm-engine：精度は高いがハードウェア要件も高く、複雑な文書や高品質な解析に向く；
  • hybrid-engine：ネイティブテキスト抽出と高精度解析を組み合わせ、幻覚を減らしつつ複雑レイアウトの品質を上げたい場合に向く；
  • *-http-client：OpenAI API 互換サービスに接続し、ローカルまたはリモート推論サービスと連携できる。

結果を検証したいだけなら、まず pipeline が安定です。文書タイプ、品質要件、処理量が見えてから、VLM や hybrid ルートを検討するとよいでしょう。企業内部文書では、データがローカル環境を離れてよいかもバックエンド選択に関わります。

デプロイ方法

MinerU は CLI、ローカル API、Gradio WebUI、Docker、mineru-router をサポートしています。入口ごとに向いているチームが異なります。

  • 個人で試す：CLI が最も直接的；
  • 非エンジニアが試す：Gradio WebUI が使いやすい；
  • 既存システムに接続する：FastAPI または REST API が適している；
  • 複数サービス、複数 GPU、高並行処理：mineru-router を検討；
  • 環境構築コストを下げる：Linux または WSL2 環境では Docker デプロイを検討。

Docker デプロイは現在、Linux と WSL2 付き Windows により適しています。macOS ユーザーは通常、pip / uv によるインストールから始めます。

通常の OCR ツールとの違い

一般的な OCR ツールは、主に「画像内の文字を認識する」ことに注力します。これは重要ですが、RAG にはそれだけでは足りません。RAG では段落順、見出し階層、表構造、数式表現、画像の文脈、追跡可能性も重要です。

MinerU は、文書理解の前処理ツールに近い位置づけです。OCR だけでなく、レイアウト解析、読み順、表の HTML、数式の LaTeX、複数フォーマット入力、構造化出力も扱います。複雑な文書を、下流モデルが安定して消費できるデータに整える用途に向いています。

つまり、重ければよいわけではありません。簡単な請求書、単一ページ画像、純テキスト PDF なら、軽量 OCR や PDF テキスト抽出ツールのほうが速い場合があります。MinerU は、文書の複雑さが後続結果に明らかに影響している場面に向いています。

PaddleOCR、Marker、Unstructured との使い分け

これらのツールには重なる部分がありますが、入口が異なります。

PaddleOCR は OCR の基礎能力と文字認識コンポーネント寄りで、細かい OCR パイプラインを自分で組みたい場合に向いています。Marker は PDF から Markdown への変換寄りで、文書を素早く読みやすい Markdown にしたい場合に便利です。Unstructured は文書データ抽出と企業データパイプライン寄りで、多様な文書を検索や ETL に流す用途に向いています。

MinerU の特徴は、LLM、RAG、Agent 向けのデータ準備を意識していることです。複雑なレイアウト、表、数式、複数フォーマット入力、VLM + OCR の二重エンジン、プライベートデプロイを重視します。文書が主に論文、レポート、教材、PPT、表計算ファイルで、後続が大規模モデルアプリケーションなら、単独で試す価値があります。

バッチ処理の進め方

本格的なバッチ処理の前に、次の順序で小規模検証を行うとよいでしょう。

  1. スキャン、複雑な表、複数カラム論文、PPT、Excel を含む代表的な文書を 10 から 20 件選ぶ。
  2. まず pipeline バックエンドで解析し、処理時間、メモリ、出力サイズ、失敗サンプルを記録する。
  3. Markdown、JSON、可視化結果をサンプル確認し、読み順、表、数式、画像説明を重点的に見る。
  4. 品質が足りないサンプルには、VLM または hybrid バックエンドを試す。
  5. 出力構造を確認したら、RAG のチャンク分割、ベクトル化、引用追跡に接続する。

最初から文書ライブラリ全体を投入しないほうがよいです。文書解析の失敗は、特定のスキャン、特定の表、フォント、言語方向、跨ページ内容など、かなり具体的に現れます。先に境界を見つけてから規模を広げるほうが時間を節約できます。

プライバシーとコンプライアンス

企業内部文書、顧客資料、契約書、財務レポート、未公開研究資料を扱う場合は、まずデプロイ方式とデータの流れを確認してください。

重点的に確認すべき点は次のとおりです。

  • ファイル内容が外部モデルサービスに送信されるか；
  • ローカル推論、リモート推論、OpenAI API 互換サービスのどれを使うか；
  • 中間ファイルに全文、画像、表、機密性の高い業務情報が含まれるか；
  • 出力 Markdown / JSON がログ、オブジェクトストレージ、共有ディレクトリに入るか；
  • バッチ処理で失敗したサンプルが issue、コミュニティ、第三者のデバッグ基盤にアップロードされるか。

MinerU はプライベートおよびオフラインデプロイをサポートしますが、すべての設定が自動的にオフラインになるわけではありません。本番デプロイ前に、入力ファイル、一時ディレクトリ、モデル推論、出力ディレクトリ、ログシステムまでのデータ経路を明確にしておくべきです。

使わなくてもよい場合

次のような場合は、MinerU をすぐ導入しなくても構いません。

  • 文書が単純で、通常の PDF テキスト抽出で十分；
  • 数ページを一度読むだけで、構造化出力が不要；
  • 現在のマシンリソースが足りず、解析コストが効果を上回る；
  • 文書品質が悪く、OCR 結果に大量の手動修正が必要；
  • プライベート文書を現在の推論チェーンに入れられない；
  • チームに RAG、抽出、ナレッジベースの明確な下流需要がまだない。

文書解析ツールは、後続ワークフローのために使うものです。「解析するための解析」にならないようにしましょう。明確な利用先がない場合は、まず出力サンプルと下流要件をそろえてから、バッチ投入するか判断するのがよいです。

参考

MinerU が GPU を使わない場合の CUDA トラブルシューティング

MinerU 環境で PyTorch を確認したときに、次のような結果が出る場合があります。

1
2
3
4
5

PyTorch: 2.8.0+cpu
PyTorch CUDA: None
CUDA available: False
GPU count: 0
GPU: 未检测到

この結果なら、現在の環境には CPU 版 PyTorch が入っていると判断できます。そのため MinerU は NVIDIA GPU を使いません。PC に RTX 4060 が入っていても、その Python 環境の torch が CPU 版である限り、MinerU は CPU 実行になります。

解決方法はシンプルです。同じ .venv の中で、torch と torchvision を CUDA 版に入れ替えます。PyTorch 2.8.0 では CUDA 12.8 対応版が公式に提供されているため、cu128 wheel を直接インストールできます。

まず NVIDIA ドライバを確認する

PowerShell で次を実行します。

1

nvidia-smi

正常なら、次のような情報が表示されます。

1
2
3

NVIDIA GeForce RTX 4060
Driver Version: ...
CUDA Version: 12.x

ここに表示される CUDA Version は、現在のドライバが対応する最大 CUDA バージョンです。nvidia-smi が GPU を正しく認識しているなら、通常は完全な CUDA Toolkit を別途インストールする必要はありません。

もし nvidia-smi でも GPU を認識できない場合は、PyTorch を触る前に NVIDIA ドライバを更新または再インストールしてください。

MinerU が使う仮想環境に入る

まず MinerU のあるディレクトリへ移動します。ここでは C:\Work\test を例にします。

1

cd C:\Work\test

プロジェクトが .venv を使っている場合は有効化します。

1

.\.venv\Scripts\Activate.ps1

現在の Python パスを確認します。

1

python -c "import sys; print(sys.executable)"

次のようなパスを指しているはずです。

1

C:\Work\test\.venv\Scripts\python.exe

この確認は重要です。置き換えるべきなのは MinerU が実際に使っている Python 環境の PyTorch です。システム Python、別の Conda 環境、VS Code が選んだ別インタプリタではありません。

CPU 版 PyTorch をアンインストールする

.venv が有効になっていることを確認したら、現在の CPU 版を削除します。

1

uv pip uninstall torch torchvision

uv を使っていない環境なら通常の pip でも可能ですが、同じ環境内でツールを混在させないほうが安全です。ここでは uv pip を使います。

CUDA 12.8 版 PyTorch をインストールする

PyTorch 2.8.0 に対応する CUDA 12.8 版をインストールします。

1

uv pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

公式の対応関係は次の通りです。

1
2
3

torch 2.8.0
torchvision 0.23.0
CUDA 12.8

CUDA 版 PyTorch はダウンロードサイズが大きく、数 GB になることがあります。ネットワークが遅い場合は少し待つ必要があります。

uv がすでにインストール済みと表示するのに、確認結果がまだ CPU 版のままなら、強制的に再インストールします。

1

uv pip install --reinstall torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

インストール後に CUDA を確認する

次を実行します。

1

python -c "import torch; print('PyTorch:', torch.__version__); print('CUDA build:', torch.version.cuda); print('CUDA available:', torch.cuda.is_available()); print('GPU count:', torch.cuda.device_count()); print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else '未检测到')"

正しい結果は次のようになります。

1
2
3
4
5

PyTorch: 2.8.0+cu128
CUDA build: 12.8
CUDA available: True
GPU count: 1
GPU: NVIDIA GeForce RTX 4060

最も重要なのはこの行です。

1

CUDA available: True

ここがまだ False の場合、PyTorch はまだ CUDA を使えていません。よくある原因は、インストール先の環境が違う、まだ CPU 版 torch が残っている、NVIDIA ドライバに問題がある、または Python インタプリタが MinerU の .venv ではない、というものです。

実際に GPU 計算を走らせる

CUDA available: True を見るだけでなく、実際の CUDA テンソル計算も確認できます。

1

python -c "import torch; x=torch.randn(4096,4096,device='cuda'); y=x@x; torch.cuda.synchronize(); print('设备:', y.device); print('显存:', round(torch.cuda.memory_allocated()/1024**2,1), 'MB')"

正常なら次のような結果になります。

1
2

设备: cuda:0
显存: 128.0 MB

これは PyTorch が GPU を認識しているだけでなく、RTX 4060 上で CUDA 計算を実行できていることを示します。

MinerU 実行中にGPUを監視する

2つ目の PowerShell ウィンドウを開き、GPU を監視します。

1

nvidia-smi -l 1

1つ目のウィンドウで MinerU を実行します。

1

mineru -p "C:\Work\test\input.pdf" -o "C:\Work\test\output"

仮想環境を有効化していない場合は、.venv 内の実行ファイルを直接呼び出します。

1

.\.venv\Scripts\mineru.exe -p "C:\Work\test\input.pdf" -o "C:\Work\test\output"

nvidia-smi を見て、次の状態が確認できれば、MinerU が RTX 4060 を使っている可能性が高いです。

  1. python.exe が表示される。
  2. VRAM 使用量が増える。
  3. 推論中に GPU-Util が上がる。
  4. MinerU 終了後に VRAM が解放される。

RTX 4060 と MinerU のモード

RTX 4060 は NVIDIA 40 シリーズ、つまり Ada Lovelace アーキテクチャの GPU であり、MinerU が GPU 加速をサポートするハードウェア範囲に入ります。正しい CUDA 版 PyTorch を入れれば、通常の mineru コマンドで GPU を使えます。

明示的に次を指定する場合：

1

mineru -p "input.pdf" -o "output" -b pipeline

これは安定性と互換性を重視するモードで、CPU フォールバックや低VRAM環境にも向きます。hybrid-engine や vlm-engine のような VLM 依存度の高いモードを使う場合は、CUDA 版 PyTorch が正しく入っていることの確認がさらに重要です。

よくある落とし穴

第一に、環境を間違えることです。CUDA 版 PyTorch をある Python 環境に入れたのに、MinerU は別の .venv で動いている、というケースが最も多いです。必ず先に確認します。

1

python -c "import sys; print(sys.executable)"

第二に、ドライバだけを見て PyTorch を確認しないことです。nvidia-smi が正常でも、それはドライバが GPU を認識しているという意味にすぎません。Python の PyTorch が CUDA 対応かどうかは、次で確認します。

1

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

第三に、CUDA Toolkit と PyTorch CUDA を混同することです。多くの通常用途では、完全な CUDA Toolkit を別途入れる必要はありません。NVIDIA ドライバが正常なら、公式の PyTorch CUDA wheel をインストールすれば十分です。

第四に、他のプログラムが VRAM を使っていることです。RTX 4060 8GB は動かせますが、余裕が大きいわけではありません。MinerU 実行前に、ゲーム、ブラウザのハードウェアアクセラレーション、他の AI 推論プログラム、VRAM を使うソフトを閉じておくのがおすすめです。

一言でまとめると

次のように表示される場合：

1
2

PyTorch: 2.8.0+cpu
CUDA available: False

MinerU は現在 RTX 4060 を使えません。正しい手順は、同じ .venv の中で CPU 版 torch / torchvision をアンインストールし、次を入れることです。

1

uv pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

確認結果が次のようになれば、

1
2
3

PyTorch: 2.8.0+cu128
CUDA available: True
GPU: NVIDIA GeForce RTX 4060

MinerU を実行し、nvidia-smi -l 1 で python.exe、VRAM、GPU 使用率を観察します。それで GPU 加速が本当に有効か確認できます。

まとめ

MinerU は、複雑な文書を大規模モデルアプリケーションで使いやすい Markdown と JSON に変換するのに適しています。PDF、画像、Office ドキュメント、表、数式、OCR、多言語認識、ローカルデプロイをカバーし、特に RAG、ナレッジベース、Agent ワークフローのデータ準備に向いています。

堅実な導入ルートは、オンライン体験版または小さなローカルサンプルで品質を評価し、pipeline バックエンドで流れを通し、その後、精度とスループット要件に応じて VLM、hybrid、API、複数サービス構成へ切り替えることです。複雑な文書では前処理コストを大きく減らせますが、単純な文書ではワークフローを重くしすぎないよう注意が必要です。