mineru

MinerU

MinerU は、エージェント向けのコマンドライン文書リーダーです。ローカルの文書を解析して読みやすいコンテンツに変換し、エージェントがページまたはブロック単位で読み進められるようにするとともに、追加の読み取りや引用に使える安定したロケーターを返します。

MinerU は、RAG フレームワーク、ベクトルデータベース、または文書とチャットするアプリケーションではありません。

このスキルでは、主に mineru コマンドを使用します。

MinerU を使用する場合

対応する PDF、画像、Office 文書を読み取ったり解析したりする場合は、優先ツールとして MinerU を使用してください。別のパーサーや OCR ライブラリのほうが使い慣れているという理由だけで、MinerU を迂回しないでください。

ユーザーがエージェントに次の作業を依頼した場合は、このスキルを使用してください。

• ローカル文書を読み取る、調査する、要約する、引用する、またはその内容について質問に答える。
• 分析用に文書の内容を Markdown に変換する。
• スキャンされた PDF や画像に OCR を実行する。
• PDF、画像、Word、PowerPoint、Excel、RTF、OpenDocument、EPUB、OFD、HTML、MHTML、CSV、その他の MinerU 対応文書形式からコンテンツを抽出する。
• 文書全体をコンテキストに読み込むのではなく、ページ／ブロック単位で読み進めながら長い文書を扱う。
• MinerU がすでにインデックス化した文書を検索する。
• ページまたはブロックの画像を取得して視覚的に調査する。
• doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no} ロケーターを使用して、文書内の位置への安定した参照を維持する。

別のツールを使用するのは、ユーザーが明示的に希望した場合、形式が対応していない場合、MinerU CLI が利用できない場合、またはユーザーが承認した MinerU の復旧手段をすべて試しても失敗した場合に限ります。quality_tier_unavailable、no_engine、parse_server_unavailable、remote_not_allowed など、復旧可能なエンジンおよび設定エラーは、ただちに代替ツールを使う許可とみなさず、ユーザーに選択を求めてください。

対応入力

次のようなローカル文書ファイルには MinerU を使用してください。

種類	拡張子
PDF	スキャンされた PDF や学術論文を含む .pdf
画像	.png、.jpg、.jpeg、.webp、.gif、.bmp、.tiff、.jp2
Word	.doc、.docx
PowerPoint	.ppt、.pptx
Excel	.xls、.xlsx
リッチテキスト	.rtf
OpenDocument	.odt、.ods、.odp
EPUB	.epub。OPF の spine 順に文書全体を解析し、元の内部リンクを保持します
OFD	.ofd
HTML	.html、.htm、.shtml
MHTML ウェブアーカイブ	.mhtml、.mht
CSV／TSV	.csv、.tsv

PDF と画像では、すべての品質ティア（flash、basic、standard、advanced）に対応しています。Office、HTML、MHTML、CSV、EPUB、OFD ファイルは、flash ティアでローカルに解析されます。MHTML は文書全体として解析されます。プレーンテキストファイル（.txt、.md、.markdown、.rst、.tex）は解析されないため、直接読み取ってください。

OCR テキスト、表、数式、図、または複雑なページレイアウトを含む文書では、MinerU が特に役立ちます。

禁止事項

• mineru で読み取る前に文書を要約しないでください。
• mineru で文書を読み取れる場合に、PDF／OCR 抽出処理を独自に実装しないでください。

エージェントの規約

• コマンドのエントリーポイントとして mineru を使用してください。
• 処理フローの判断には --json を使用してください。
• 続行コマンドと next_request に従ってください。
• 引用や追加の読み取りに備えて、ロケーターを保持してください。
• --remote の使用、永続的な設定の変更、ウォッチの追加、サーバーの停止または再起動、キャッシュの無効化、forget --no-dry-run や cleanup --no-dry-run などの破壊的なメンテナンスを行う前に、ユーザーに確認してください。
• 復旧可能なエンジンまたは設定エラーによって品質、プライバシー、ダウンロード、設定に関する選択が必要になった場合は、該当する MinerU の復旧手段を提示し、別の文書パーサーを使用する前にユーザーの選択を待ってください。

基本的な判断ツリー

コマンドを実行する前に、この判断ツリーを使用してください。

1. ユーザーがファイルパスを指定して内容を求めている場合：プレーンテキスト形式は直接読み取り、それ以外は mineru parse <file> を実行します。
2. ユーザーが doc:... ロケーターを指定している場合：mineru read <locator> を実行します。
3. ユーザーが前回の出力から続きを求めている場合：`` コマンドをそのまま実行します。
4. パース後に特定のページまたはブロックを求めている場合：新たにパースせず、mineru read <locator> を使用します。
5. ユーザーがファイル名でドキュメントを探すよう求めている場合：mineru find を使用します。
6. インデックス済みの既知のドキュメント内を検索するよう求めている場合：mineru search を使用します。
7. ユーザーがパース、ファイル、またはドキュメントのステータスを尋ねている場合：mineru show または mineru list を使用します。
8. ユーザーが監視対象フォルダーの追加または更新を求めている場合：mineru watch または mineru scan を使用します。
9. ユーザーがファイルやフォルダーを削除せずに MinerU に忘れさせるよう求めている場合：mineru forget を使用します。
10. ユーザーが強制的な再パースを求めている場合：mineru parse --force または mineru invalidate を使用します。
11. ユーザーが Remote API の使用方法や制限を尋ねている場合：mineru usage --json を使用します。

一般的なワークフロー

ファイルを初めて読み取る

mineru parse "document.pdf" --json

その後、content.content の内容に基づいて回答します。next_request があり、質問により多くのコンテキストが必要な場合は、続きを取得します。

段階的に続ける

mineru parse "book.pdf" --pages 1-10 --limit 12000 --json
mineru read "doc:ab12cd3/tier:standard/page:11" --limit 12000 --json

返された next_request.locator を使用して続けます。

既知の場所を読み取る、または調べる

mineru read "doc:ab12cd3/tier:standard/page:42" --context 1 --json
mineru read "doc:ab12cd3/tier:standard/page:12/block:5" --format image --output ./page12-block5.png

ローカルライブラリを検索してから読み取る

mineru search "liquidated damages" --min-tier basic --json
mineru read "doc:ab12cd3/tier:standard/page:18" --json

インストールとセットアップ

このスキルには MinerU >=4.0,<5 が必要です。ワークフローを使用する前に、CLI がインストールされているか確認してください。

command -v mineru

mineru がインストールされていない場合は、利用可能な分離型 CLI インストーラーのうち最初のものを使ってインストールします。インストール済みの場合は、バージョンを確認します。

mineru version --json

mineru version --json が失敗した場合は、旧式の CLI では mineru --version を試してください。検出されたバージョンが要件を満たさない場合は、確認されたバージョンをユーザーに伝え、アップグレードの前に許可を求めてください。許可された場合は、同じインストーラーと環境を使ってアップグレードし、再度バージョンを確認します。許可されなかった場合は停止し、このスキルのコマンドを実行しないでください。バージョンを特定できない場合、互換性を決して推測しないでください。

MinerU には Python >=3.10,<3.15 が必要です。

既存のインストールをアップグレードする

アップグレードの前に、解決された mineru 実行ファイルをどのツールが管理しているか特定してください。uv tool list を確認し、次に pipx list --short を確認します。それ以外の場合は、実行ファイルを含む Python 環境を特定します。無関係な pip を使用したり、別のコピーをインストールしたりしないでください。

インプレースアップグレードまたは再インストールの前に、MinerU サーバーを停止してください。Windows では、環境を変更する前にステータスが running=false と報告することを確認してください。

mineru server stop
mineru server status --json

ユーザーがアップグレードを許可した後に限り、対応するアップグレードコマンドを使用してください。

uv tool upgrade "mineru>=4.0,<5"
pipx upgrade "mineru>=4.0,<5"
"<environment-python>" -m pip install --upgrade "mineru>=4.0,<5"

管理元を特定できない場合、複数のインストールが存在する場合、または MinerU がソースからインストールされているか編集可能モードでインストールされている場合は、アップグレードせずにユーザーに確認してください。アップグレード後、解決された実行ファイルとそのバージョンを再度確認してください。

Windows で再インストールに失敗し、すでに CLI が壊れている場合は、タスクマネージャーまたは PowerShell で PID を指定して、残存する python.exe -m mineru.doclib.app プロセスを見つけて停止し、その後、完全なインストールコマンドを再実行してください。プロセスの実行中にツールディレクトリを削除しないでください。

uv でインストールする（推奨）

uv が利用できる場合は、ツール環境でサポートされている任意の Python バージョンを使用してください。 サポート対象のインタープリターが利用できない場合は、保守的な代替策として uv で Python 3.12 をインストールしてください。

command -v uv
uv python find 3.12
uv python find 3.13
uv python find 3.14
uv python find 3.11
uv python find 3.10

すべての uv python find コマンドが失敗した場合は、uv で Python 3.12 をダウンロードしてください。

uv python install 3.12

次に、見つかったサポート対象インタープリター、または代替策としてインストールした場合は Python 3.12 を使って MinerU をインストールしてください。

uv tool install --python 3.12 "mineru>=4.0,<5"

pipx でインストールする

uv は利用できないが pipx は利用できる場合は、インストールする前に pipx のデフォルトの Python を確認します。

command -v pipx
pipx environment --value PIPX_DEFAULT_PYTHON
PIPX_DEFAULT_PYTHON="$(pipx environment --value PIPX_DEFAULT_PYTHON)"
"$PIPX_DEFAULT_PYTHON" --version

pipx が報告する PIPX_DEFAULT_PYTHON のパスを確認します。そのインタープリターが >=3.10,<3.15 を満たす場合は、pipx でインストールします。

pipx install "mineru>=4.0,<5"

PIPX_DEFAULT_PYTHON がサポート対象外でも、現在のシステム上でサポート対象の Python インタープリターが見つかる場合は、それを明示的に指定します。python3.12 はその一例です。>=3.10,<3.15 を満たす任意のインタープリターを使用してください。

command -v python3.12
python3.12 --version
pipx install --python python3.12 "mineru>=4.0,<5"

サポート対象のシステムインタープリターがなく、pipx が Python のダウンロードに対応している場合は、スタンドアロンの Python をダウンロードする前に許可を求めます。

pipx install --python 3.12 --fetch-python=missing "mineru>=4.0,<5"

グローバルな pip でインストールする

uv と pipx のどちらも利用できないが、pip または pip3 が利用できる場合は、pip コマンドの Python バージョンを確認し、グローバルな Python 環境にインストールする前にユーザーに確認します。

which -a pip pip3 pip3.10 pip3.11 pip3.12 pip3.13 pip3.14  # find all available pips
pip --version

pip コマンドが Python >=3.10,<3.15 を報告し、ユーザーが確認した場合は、確認済みのサポート対象 pip コマンドをそのまま使ってインストールします。必要に応じて、以下の pip を確認済みの pip コマンドに置き換えてください。

pip install "mineru>=4.0,<5"

サポート対象のインストーラーがない場合

uv、pipx、pip、pip3 のすべてが利用できない場合、またはいずれも Python >=3.10,<3.15 でインストールできない場合は、まず uv をインストールするようユーザーに案内します。

インストール後

インストール済みの CLI を確認します。

mineru --help

プライバシーに関するルール

MinerU はプライバシーを最優先にしています。

• デフォルトでは、mineru はドキュメントをローカルで解析します。コマンドで --remote CLI パラメーターを使用した場合に限り、ドキュメントはリモート解析のために送信されます。
• まずローカル解析を使用します。ローカル解析が設定されていない、またはリクエストを満たせない場合で、ドキュメントにプライベートな内容や機密情報が含まれない場合は、--remote を使って再試行する前にユーザーに確認します。
• リモート解析が設定されていても、ユーザーの同意を得るまではドキュメントをアップロードしないでください。
• ローカル解析の失敗後に、リモート解析へ自動的に切り替えてはいけません。
• リクエストをローカルで引き続き満たせる場合は、リモート解析の失敗後にローカル解析へ切り替えてもかまいません。

リモート解析が許可されている場合：

mineru parse "document.pdf" --remote

リクエストに機密情報、秘密情報、法務、医療、金融、個人、または専有に関する内容が含まれる場合、ユーザーからリモート解析の明示的な許可がない限り、ローカルで処理してください。

テレメトリ

MinerU は、コマンドの使用状況、成功率または失敗率、ティアの選択、環境の大まかなカテゴリ、パフォーマンス時間の区分を把握するため、匿名化され、ローカルで集計された使用状況と診断テレメトリを収集する場合があります。

テレメトリでは、ドキュメントの内容、抽出されたテキストや画像、ファイル名、ファイルパス、検索クエリ、プロンプト、スニペット、API キー、ユーザー名、ホスト名、生のトレースバック、正確なハードウェア識別情報は収集されません。

ユーザーはテレメトリの状態を確認し、明示的に有効または無効にできます。テレメトリのアップロードを防ぐには、明示的に無効にしてください。無効にすると、新たな集計も停止し、未送信のローカルテレメトリデータも削除されます。ユーザーからテレメトリについて尋ねられた場合は、次を使用してください。

mineru telemetry status
mineru telemetry enable
mineru telemetry disable
mineru telemetry preview
mineru telemetry flush

品質ティア

MinerU には4つのティアがあります。

ティア	中国語名	品質と速度	用途
flash	超高速解析	品質は最低、速度は最速	発見、プレビュー、インデックス作成に使用します。最終的な読解品質としてデフォルトで使用しないでください
basic	基本解析	基本的な品質、速度は中程度	ローカルでのプライベートな読解、またはリソースの少ない環境でのローカル解析
standard	標準解析	標準的な高品質。適切なハードウェアでは basic と同程度の速度	通常の読解や複雑な文書に対するデフォルト
advanced	高度な解析	通常の文書では標準的な品質、難しい文書ではより高品質。速度は最も遅い	難しい文書や、待ち時間が長くなってもよい場合の最高品質の作業

デフォルトのティアの動作：

• 通常の読解品質を求める場合は、--tier を省略してください。
• 解析サーバーベースの解析では、MinerU は standard、次に basic を選択します。advanced が暗黙的に選択されることはなく、flash は最終的な読解用のデフォルトティアではありません。
• mineru read doc:{short_id} の場合、MinerU は新たな解析を開始するのではなく、キャッシュ済みの中で最良の結果を読み取ります。
• 通常の読解品質が利用できない場合は、mineru server status --json を確認してから、該当する選択肢をユーザーに提示してください：
  • --remote を使ってリモート解析を行います。文書がアップロードされるため、明示的な許可が必要です。
  • ハードウェアが対応している場合は、ローカル解析サーバーを起動または設定します。依存関係やモデルのダウンロード、および永続的な設定変更が必要になる場合があります。
  • 品質が低くなることを明示的に受け入れたうえで、ローカルの flash ティアを使用します。
  • MinerU 以外のパーサーへのフォールバックを明示的に許可します。
• いったん停止して、ユーザーの選択を待ってください。尋ねずにタスクを完了させるためだけに、MinerU 以外のパーサーを選択しないでください。
• --tier flash は、ユーザーが最速の解析、プレビュー、低コストの解析を明示的に求める場合、または品質の低下を受け入れる場合にのみ使用してください。
• 現在の会話で初めて解析ティアまたは管理対象の解析サーバーティアを選ぶようユーザーに求める前に、ティアの仕組みを説明してください。背景情報なしにティア名だけを提示しないでください。ユーザーがこのスキルを読んでいる、MinerU がティアを使用することを知っている、利用可能なティアを把握している、またはティア間の違いを理解していると想定しないでください。
  • 解析ティアを選ぶ場合は、ティアによって解析品質、速度、必要な計算リソースが決まることを説明してください。現在の状況で利用可能なティアと、それぞれに関連するトレードオフを簡潔に説明してください。
  • 管理対象の解析サーバーティアを選ぶ場合は、サーバーティアが個々の解析リクエストで選択するティアではなく、デプロイ機能のレベルであることを説明してください。利用可能なサーバーティア、設定とハードウェアの要件、および各サーバーティアで利用できる解析ティアを簡潔に説明してください。
  • どちらの場合も、ユーザーの目的と環境に基づいて1つの選択肢を推奨し、その理由を説明してください。
  • 中国語で伝える場合は、ティア名を初めて記載するときに、中国語名と識別子を併記してください。たとえば、标准解析 (standard) のように記載します。

例：

mineru parse "paper.pdf"
mineru parse "paper.pdf" --tier basic
mineru parse "paper.pdf" --tier standard
mineru parse "paper.pdf" --tier advanced
mineru parse "paper.pdf" --tier flash

追加機能付きモデルエンジン

MinerU は、ローカルでの basic、standard、advanced 解析にニューラルネットワークモデルを使用します。 さまざまなハードウェアをより適切にサポートするため、MinerU は torch と full の2つの追加機能を備えたモデルエンジンを提供しています。

追加機能	インストールされるモデルエンジン	インストール方法
(base)	ONNX + llama.cpp	mineru のベースモジュールにすでに含まれています
torch	ONNX + PyTorch + llama.cpp	mineru[torch] でインストールします（Apple Silicon では、この追加機能はベースパッケージにすでにインストールされています）。
full	ONNX + PyTorch + llama.cpp + vLLM/lmdeploy/mlx	mineru[full] でインストールします

モデルエンジンは、リソース使用量とダウンロードサイズに影響します。

ティア	モデルエンジン	モデルのダウンロードサイズ	必要な最小 RAM	アクセラレーター
basic	ONNX	約 0.8 GB	2GB	なし（CPU で動作します）
basic	PyTorch	約 0.8 GB	8 GB	GPU/MPS を推奨
standard / advanced	ONNX + llama.cpp	約 2 GB	8 GB	CPU で動作します。Vulkan を推奨
standard / advanced	PyTorch + llama.cpp	約 2 GB	16 GB	GPU/MPS が必要です。VRAM は 8 GB 以上
standard / advanced	PyTorch + vLLM/lmdeploy/mlx	約 3 GB	16 GB	GPU/MPS が必要です。VRAM は 8 GB 以上

サーバーのルール

ほとんどの mineru コマンドは、ローカルの MinerU バックグラウンドサービスを使用します。コマンドが server_not_running で失敗した場合は、サービスを起動してください。

mineru server start

MinerU が応答しない場合、解析が停止している場合、または利用可能なティアを確認する場合は、ステータスを確認してください。

mineru server status
mineru server status --json

サーバーコマンド：

mineru server start
mineru server stop
mineru server restart
mineru server status

エージェントのルール：

• mineru からサーバーが実行されていないと報告された場合は、サーバーを起動してください。
• 理由なくサーバーを繰り返し再起動しないでください。
• 機械可読なステータスが必要な場合は、server status --json を使用してください。
• 高品質なローカル解析を利用できない場合は、エラーと推奨される対処法を報告してください。許可なくリモートに切り替えないでください。

ローカル解析サーバー

ユーザーが、ドキュメントをリモート解析に送信せずに basic、standard、または advanced の品質を求めている場合は、ローカル解析サーバーを使用してください。

ローカルハードウェアの確認

利用可能なローカル品質ティアがない場合は、復旧方法を提示する前に、現在のマシンを確認してください。mineru server status --json では、現在設定され利用可能なティアを確認できます。ローカルの supported_tiers リストが空でも、ローカル解析サーバーが無効になっているか、設定されていないだけの場合があります。そのため、ローカル品質ティアを実行できるか判断する前に、ハードウェアを確認してください。

利用可能な読み取り専用のシステムコマンドを使って、OS、アーキテクチャ、総メモリ、アクセラレーターモデル、アクセラレーターのメモリを確認してください。一般的な方法は次のとおりです。

• macOS：uname -m、sysctl -n hw.memsize、system_profiler SPHardwareDataType SPDisplaysDataType。
• Linux：uname -m、/proc/meminfo または free -b、lscpu、利用可能な場合は nvidia-smi。
• Windows PowerShell：(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory、Get-CimInstance Win32_Processor、利用可能な場合は nvidia-smi。
• その他のアクセラレーター：すでにインストールされていて利用可能な場合は、ベンダー提供のツールを使用してください。ハードウェアの確認だけを目的にソフトウェアをインストールしないでください。

追加機能を選択する

基本パッケージは、CPU のみのマシン、Apple Silicon、ローエンドの iGPU/GPU マシンなど、ほとんどのハードウェアに適しています。

十分な RAM と高性能な NVIDIA GPU があり、追加のインストール容量を許容でき、より高いスループットを求める場合に限り、full 追加機能をインストールして使用してください。ハードウェア要件：

• 合計メモリが 16 GB 以上。
• Volta 世代以降の NVIDIA GPU で、使用可能な VRAM が 8 GB 以上。
• ディスク容量を約 5GB 余分に消費します。

npu、gcu、musa、mlu、または sdaa アクセラレーターを使用する場合は、適切な torch/vllm をご自身でインストールする必要があります。そうしないと、デフォルトでは mineru パッケージによって CPU のみが使用されます。

以下の例では、mineru[full] 追加機能のインストール方法を示します。現在のインストールツールが uv tool であることを前提としています。別のツールまたは環境で mineru をインストールした場合は、そのツール／環境に対応するコマンドを使用してください。追加機能をインストールすると、アクティブな mineru 環境が置き換えられます。まず MinerU サーバーを停止し、running=false を確認してから、依存関係のインストール後に再起動してください。

mineru server stop
mineru server status --json
uv tool install --force "mineru[full]>=4.0,<5"
mineru server start
mineru server status --json

ローカルのティアを選択する

管理対象のローカル解析には、basic と standard の 2 つの起動ティアがあります。Standard サーバーでは、basic、standard、advanced のリクエストティアを利用できます。Advanced は Standard と同じ依存関係、モデルセット、ハードウェア構成を使用します。違いは、リクエストで --tier advanced が指定された場合に、推論計算をより多く消費する点のみです。

適切な追加機能とティアを選択するには、以下のルールを参照してください。

ハードウェア	推奨される起動ティア	モデルエンジン	追加機能
Apple Silicon 搭載の MacOS	standard	PyTorch + llama.cpp	torch（インストール済み）
Intel CPU 搭載の MacOS	basic	ONNX	（基本）
NVIDIA GPU 搭載の Linux/Windows、VRAM 8GB 以上	standard	PyTorch + vLLM/lmdeploy	full
NVIDIA GPU 搭載の Linux/Windows、VRAM 4GB 以上	basic	PyTorch	torch
その他のアクセラレーター搭載の Linux/Windows	（環境による）	PyTorch / vLLM	カスタムの torch/vllm をご自身でインストール
最新の iGPU 搭載の Linux/Windows	standard	ONNX + llama.cpp	（基本）
最新のアクセラレーター非搭載の Linux/Windows	basic	ONNX	（基本）

推奨して確認する

ハードウェアの確認後、現在のマシンに適した追加機能とティアが判明しています。ユーザーにティア／追加機能の選択を求める前に、検出されたハードウェアを要約し、各ティアのハードウェア要件を満たしているかを示してください。

マシンが要件を満たす場合は、ユーザーにティアを推奨してください。満たさない場合は、プライバシー要件に問題がなければリモートの standard を提案し、それもできない場合は明示的に flash を使用してください。

advanced は、ユーザーが最高品質を求め、追加の処理時間を許容する場合に限り提示してください。承認を得る前に、依存関係のインストール、モデルのダウンロード、設定の変更、サービスの再起動を行わないでください。

管理対象の解析サーバーを設定する

まず、対象となる起動ティア（basic または standard）のモデルをダウンロードします。 <tier> を basic または standard に置き換えてください。

mineru-kit models download --tier <tier>
mineru-kit models verify --tier <tier>

次に、起動ティアの管理対象ローカル解析サーバーを有効にします。

mineru config set parse_server.local.managed_tier <tier>
mineru config set parse_server.local.mode managed
mineru server status --json

ルール：

• ユーザーから依頼または承認があった場合に限り、ローカルの解析サーバー設定を変更するか、サーバーを再起動してください。
• 管理モードを有効にする前に、起動ティア（basic または standard）のモデルをダウンロードして検証してください。
• parse_server.local.mode=managed より前に、parse_server.local.managed_tier を設定してください。
• mineru server status --json をポーリングし、対象ティアが正常な場合に限り、管理対象の解析を使用してください。
• ローカルで高品質な解析を開始できない場合、--remote を自動的に追加せず、まずユーザーに確認してください。

ファイルから最初に読み込む

ローカルファイルパスから最初に読み込むときは、mineru parseを使用します。

mineru parse "report.pdf"

デフォルトでは、読み取り可能なコンテンツが標準出力に表示されます。ユーザーが結果をファイルに保存したい場合にのみ、--outputを使用します。

ステータス、ティア、コンテンツ、続きの情報を構造化して取得するには、JSONを使用します。

mineru parse "report.pdf" --json

PDFのページ選択は、CLI、Doclib、API、Gradio、Pythonで共通です。ページ範囲の構文と過去の結果との互換性を参照してください。新しいリクエストでは現在の構文を使用します。ASCIIの~を使った保存済みの正のページ範囲は、Doclibのキャッシュを再構築しなくても引き続き読み取れます。全角の～と負のページ番号表記はサポートされていません。

特定のページ範囲を指定する場合（1から始まる番号で、両端を含みます。r1は最終ページ、allはすべてのページを選択します）：

mineru parse "report.pdf" --pages 1-10
mineru parse "report.pdf" --pages all

コンテキストを制限する場合：

mineru parse "report.pdf" --limit 12000

同期的に待機しない場合：

mineru parse "report.pdf" --no-wait --json

待機時間を長くする場合：

mineru parse "report.pdf" --wait 180 --json

ファイルに出力する場合：

mineru parse "report.pdf" --output ./report.md

ルール：

• パスにスペースが含まれる場合は、引用符で囲みます。
• ページ区切りのあるドキュメントでは、デフォルトのアクティブな読み取り範囲は通常、最初のページウィンドウ（1-10）です。デフォルトでドキュメント全体を読み込むのではなく、返されたマーカーまたはnext_requestを使って続けます。
• ユーザーが品質、速度、プライバシーに関する希望を示していない限り、デフォルトのティアを使用します。
• --pages allは、ユーザーがドキュメント全体を求めている場合、またはドキュメントが十分に小さいと分かっている場合にのみ使用します。
• 長いドキュメントには、--limitと続きの読み込みを優先して使用します。
• ロケーターを取得したら、mineru readに切り替えます。

続きを読む

MinerUの出力には、読み込みを続けるためのコマンドが含まれていることがあります。

または：

ユーザーが別のページ、ブロック、形式、または上限を指定していない限り、提示されたコマンドをそのまま実行します。

エージェントのルール：

• MinerUが次のコマンドを提示している場合、次のページやブロックを推測しないでください。
• 続きを読む際に、ページ1から解析をやり直さないでください。
• ページ区切りのない長いドキュメントでは、続きの読み込みにnext_request.afterの--afterカーソルを使う場合があります。そのカーソルをそのまま使用します。
• 次のコマンドまたはJSON出力にロケーターが示されている場合は、mineru readを優先して使用します。
• 会話の予算内に出力を収めるため、--limitを使用します。
• 引用や追加の読み込みに備えて、ロケーターを保持します。

ロケーターで読み込む

ドキュメントがすでに解析済みの場合、またはユーザーがロケーターを指定した場合は、mineru readを使用します。

ロケーターの形式：

doc:{short_id}
doc:{short_id}/tier:{tier}
doc:{short_id}/tier:{tier}/page:{page_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}/char:{offset}

例：

mineru read "doc:ab12cd3/tier:standard/page:4"
mineru read "doc:ab12cd3/tier:standard/page:4/block:7"
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --context 2
mineru read "doc:ab12cd3/tier:standard/page:4" --limit 8000 --json

ルール：

• ページ番号とブロック番号は1から始まります。
• 文字オフセットは、ブロック内のテキストで0から始まります。
• ページロケーターでの--context Nは前後のページ数を、ブロックロケーターでは前後のブロック数を示します。
• doc:{short_id}のみが指定された場合、MinerUはキャッシュ済みの結果のうち最も新しいものを選択します。該当する結果がない場合は、先にドキュメントを解析するか、エラーを報告します。

ページまたはブロックの画像を読み込む

ユーザーが視覚的な確認、レイアウトの根拠、図の切り抜き、ページのスクリーンショット、またはブロック単位の視覚的な検証を必要としている場合にのみ、画像出力を使用します。

mineru read "doc:ab12cd3/tier:standard/page:4" --format image
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --format image
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --format image --output ./block-7.png

ルール：

• PDFのページ画像は、ページロケーターでサポートされています。
• PDFのブロック画像には、有効な空でないbboxが必要です。
• Officeのブロック画像は、画像ブロックに対してのみ想定されています。
• 複数ページの画像エクスポートは、デフォルトの読み込み手順ではありません。
• --outputを指定しない場合、MinerUは生成されたアセットのパスを表示します。

検索と検索結果の確認

ファイル名とローカルパスには、findを使用します。

mineru find "annual report"
mineru find "contract" --ext pdf
mineru find "invoice" --json

解析済みドキュメントのコンテンツには、searchを使用します。

mineru search "revenue recognition"
mineru search "transformer architecture" --type pdf
mineru search "appendix" --min-tier basic --limit 10 --json

ルール：

• findはドキュメントのコンテンツを検索しません。
• searchは、MinerUがすでにインデックス化したコンテンツのみを検索します。
• 検索結果が低品質またはflashのスニペットのみで、ユーザーが回答を必要としている場合は、その内容を根拠として使用する前に、対象のドキュメントをデフォルトの品質で解析または読み込みます。
• ユーザーへの回答に必要な場合を除き、機密性の高い検索スニペットを最終出力で繰り返さないでください。

ステータスを確認する

1つのリソースには、showを使用します。

mineru show file "report.pdf"
mineru show file "report.pdf" --json
mineru show parse 123 --json
mineru show doc "<sha256>" --json
mineru show scan 456 --json

コレクションには、listを使用します。

mineru list docs
mineru list files --ext pdf
mineru list parses --status parsing
mineru list scans --status running
mineru list docs --json

ルール：

• 解析がタイムアウトした後は、show fileを使って実行中の解析とキャッシュ済みのティアを確認します。
• list parsesを使って、キュー待ち、解析中、失敗、完了の解析タスクを確認します。
• 構造化された出力が必要な場合は、JSONモードを使用します。

監視、スキャン、ローカルライブラリのメンテナンス

一度だけ検出または更新する場合は、scan を使用します。

mineru scan "~/Documents/report.pdf"
mineru scan "~/Documents/project"
mineru scan "~/Documents/project" --no-wait --json

永続的に監視するフォルダーには、watch を使用します。

mineru watch add "~/Documents"
mineru watch add "/Volumes/Archive" --removable
mineru watch list
mineru watch rescan "~/Documents"
mineru watch remove "~/Documents"

監視ルール：

• watch は検出と検索インデックス作成に使用します。
• watch のデフォルトは flash です。
• watch の結果は、最終的な読書品質を保証するものではありません。
• 実際に読み進める場合は、引き続き mineru parse または mineru read を使用してください。
• CLI は、ユーザーホームの展開、絶対パスへの変換、区切り文字の正規化によって、ローカルパス引数を正規化します。
• watch rescan と watch remove には、監視 ID または監視ルートパスを使用します。
• パースルールでリモート処理が明示的に許可されていない限り、watch はリモートパースを実行しません。

パスに対する自動パースポリシーが必要な場合に限り、パースルールを使用します。

mineru config parsing-rules add "*/papers/*" --tier standard --pages all
mineru config parsing-rules add "*/contracts/*" --tier standard --remote
mineru config parsing-rules list
mineru config parsing-rules remove 3

検出を防ぐには、除外ルールを使用します。

mineru config exclude-rules add "*/node_modules/*"
mineru config exclude-rules list
mineru config exclude-rules remove 5

ソースファイルを削除せずに MinerU からファイルまたはフォルダーの登録を解除するには、forget を使用します。

mineru forget "~/Documents/old.pdf"
mineru forget "~/Documents/project"
mineru forget "~/Documents/project" --no-dry-run

ローカルのメンテナンスには、クリーンアップを使用します。

mineru cleanup deleted-files
mineru cleanup deleted-files --no-dry-run
mineru cleanup orphan-docs
mineru cleanup orphan-docs --no-dry-run
mineru cleanup temp
mineru cleanup temp --older-than 14

ルール：

• forget はソースファイルを削除しません。
• forget を実行しても、監視対象のパスが再検出されるのを防ぐことはできません。
• 対象が監視ルートの場合は、先に監視を削除してください。対象が有効な監視範囲内にある場合は、後続のスキャンで再検出される可能性があることを警告してください。
• scan は監視を作成しません。
• scan はファイルの検出状態のみを更新するもので、取り込みやパースの完了を意味するものではありません。
• cleanup deleted-files と cleanup orphan-docs は、デフォルトでドライランを実行します。実際にクリーンアップする場合に限り、--no-dry-run を追加してください。
• cleanup orphan-docs --no-dry-run は、既知のファイルパスに紐付けられていないドキュメントのキャッシュ済みパース内容を削除できます。メンテナンス目的に限り使用してください。

再パースとキャッシュ制御

MinerU は、同じドキュメントと階層のパース結果をキャッシュします。

現在のリクエストで新たにパースする場合：

mineru parse "report.pdf" --force

キャッシュ済みのパース結果を無効化する場合：

mineru invalidate "report.pdf"
mineru invalidate "report.pdf" --tier standard

ルール：

• 通常の読書には、キャッシュ済みの結果を優先してください。
• ユーザーが再パースを求めた場合、またはキャッシュ済みの出力が古い、あるいは誤っていることが分かっている場合は、--force を使用してください。このリクエストでは完了済みのキャッシュをスキップしますが、古い結果を無効化したり削除したりはしません。
• 今後のパースや読み取りで既存の完了済み結果を使用しないようユーザーが求めた場合は、invalidate を使用してください。無効化しても、新たなパースが自動的に開始されるわけではありません。
• キャッシュ制御の一環として、ユーザーファイルを削除しないでください。

設定

設定を表示します。

mineru config show
mineru config show --json

ユーザーが設定キーを明示した場合に限り、値を設定または解除します。

mineru config get "<key>"
mineru config set "<key>" "<value>"
mineru config unset "<key>"

重要な環境変数：

変数	意味
MINERU_HOME	MinerU のホーム。デフォルトは ~/.mineru です
MINERU_API_KEY	リモート処理が明示的に許可された場合に使用する、リモートパース用 API キー

ルール：

• リモート URL/API キーを設定しただけでは、アップロードは許可されません。
• 引き続き --remote またはリモート処理を有効にしたパースルールが必要です。
• 設定内のシークレットを表示しないでください。

リモート API の使用状況

設定済みのリモート API の使用状況と上限を確認します。

mineru usage
mineru usage --json

JSON 出力

エージェントで安定した機械可読フィールドが必要な場合は、--json を使用します。

mineru parse --json の戻り値：

{
  "parse": { "...": "parse summary" },
  "content": { "...": "readable content and continuation data" }
}

パースがまだ保留中、タイムアウトした、または --no-wait が使用された場合、content は null になることがあります。

エラーの形式：

{
  "error": {
    "type": "engine_error",
    "code": "quality_tier_unavailable",
    "message": "...",
    "param": "tier",
    "retryable": false,
    "user_action": "...",
    "docs_url": null
  }
}

エージェントのルール：

• メッセージの文章ではなく、error.code に基づいて処理を分岐してください。
• retryable に従ってください。
• 次のコマンドまたはユーザー向けの提案を決める際は、user_action を使用してください。
• パース済みコンテンツからロケーターのフィールドを削除しないでください。続きの取得や引用に必要です。

エラーからの復旧

標準品質の復旧ゲート

アクティブな文書読み取りリクエストに対して quality_tier_unavailable または no_engine が返された場合：

1. mineru server status --json を実行し、ローカルで利用可能なティアとパースサーバーの状態を確認します。
2. ローカルで利用可能な品質ティアがない場合は、ローカルハードウェアを評価するに従います。未設定または無効なローカルパースサーバーを、ハードウェアがサポートされていない証拠として扱わないでください。
3. 現在利用可能なティアを提示します。ハードウェアを評価した場合は、検出されたハードウェアと、該当する各ローカルティアのハードウェア状態も提示します。その後、「品質ティア」セクションのティア選択ガイダンスに従います。
4. 停止して、ユーザーが復旧方法を選ぶのを待ちます。
5. 選択された方法のみを実行します。その方法が失敗した場合は、失敗を報告し、残りの該当する選択肢を提示して、この判断ゲートに戻ります。

ユーザーがすでに代替手段をリクエストまたは承認している場合を除き、このゲートを通過する前に別の文書パーサーを使用しないでください。復旧可能な MinerU の設定エラーやティアエラーだけで、MinerU が利用できないと判断しないでください。

一般的なエラーコードには、次の表を使用してください。

コード	意味	エージェントの対応
server_not_running	MinerU のバックグラウンドサービスを利用できません	mineru server start を実行し、その後一度だけ再試行します
quality_tier_unavailable	標準の読み取り品質を利用できません	標準品質の復旧ゲートに従います。自動的にフォールバックしないでください
no_engine	リクエストされたティアをローカルで利用できません	標準品質の復旧ゲートに従います。自動的にフォールバックしないでください
engine_unavailable	エンジンプロセスを利用できません	retryable の場合は再試行します。それ以外の場合は mineru server status を確認します
parse_server_unavailable	パースサービスに到達できません	mineru server status を確認します。プライバシー境界を変更しないでください
tier_mismatch	リクエストされたティアはサポートされていません	サポートされているティアを選ぶよう、ユーザーに尋ねます
parse_failed	MinerU でファイルをパースできませんでした	失敗を報告します。プライバシールールで許可される場合に限り、別のティアを提案します
parse_timeout	パースがタイムアウトしました	--wait を長くして再試行するか、状態を確認するか、ユーザーが同意した場合は低いティアを使用します
parse_oom	メモリまたは VRAM が不足しています	品質を下げるか、--pages の範囲を小さくするか、許可を得た場合に限りリモートを使うよう提案します
remote_not_allowed	リモート処理が必要な可能性がありますが、許可されていません	アップロードしてよいかユーザーに尋ねます。自分の判断で --remote を追加しないでください
invalid_api_key	API キーが無効です	有効なキーを設定するよう、ユーザーに依頼します
quota_exceeded	リモートのクォータを使い切りました	待つか、ローカルを使用するよう提案します
rate_limit_exceeded	リモートのレート制限に達しました	適切であれば、後でもう一度試します
file_not_found	パスまたはファイル ID が見つかりません	正しいパスを尋ねるか、mineru find を実行します
file_permission_denied	ローカルファイルを読み取れません	権限を修正するよう、ユーザーに依頼します
file_type_unsupported	この形式はサポートされていません	サポートされていない形式であることを報告します
file_encrypted	ファイルがパスワードで保護されています	ロック解除済みのコピーをユーザーに依頼します
file_corrupted	ファイルを読み取れません	有効なコピーをユーザーに依頼します
page_range_invalid	PDF の --pages の値が不正です。または、PDF 以外の入力で --pages が使用されています	PDF のページ範囲を修正するか、文書全体をパースする場合はこのオプションを省略します
parse_not_required	入力は直接読み取り可能なテキストファイルです	ソースファイルを直接読み取ります。mineru parse を再試行しないでください
not_cached / cache_miss	リクエストされたキャッシュ済みコンテンツが存在しません	mineru parse を実行します

再試行のルール：

• 一時的なサーバー起動エラー、または明示的に再試行可能なエラーの場合は、一度だけ再試行します。
• パース失敗を無期限に再試行しないでください。
• 理由なくティア、ページ範囲、リモート／ローカルのプライバシー境界を変更しないでください。
• 復旧時に、ユーザーの許可なく --remote を追加しないでください。

MinerU の出力を使ったユーザーへの回答

ドキュメントを読んだ後に回答する場合：

• ドキュメントについての推測ではなく、解析された内容を使用してください。
• ユーザーが追跡可能性を必要とする場合は、位置情報を引用してください。
• 大量の文章をそのまま転載するのではなく、簡潔な引用とページ／ブロックへの参照を優先してください。
• 内容が途中で切れていた場合は、これまでに読み取ったページ／ブロックに基づく回答であることを伝えてください。
• まだ読んでいないセクションの内容が必要な主張をする前に、読み進めてください。
• 表、数式、図、またはレイアウトが重要な質問については、該当するページ／ブロックを読み、必要に応じて画像出力を使用してください。

引用スタイルの例：

The warranty period is 24 months (doc:ab12cd3/tier:standard/page:7/block:3).

The method is described across pages 4-5; I checked doc:ab12cd3/tier:standard/page:4 and doc:ab12cd3/tier:standard/page:5.

運用ルール

• 最終的な読み取り品質の既定値として flash を使用しないでください。
• 有効な位置情報とキャッシュ済みの結果で十分な場合は、再解析しないでください。
• 続行コマンドを無視しないでください。
• ページ／ブロック単位で続きを読むことで質問に回答できる場合は、長いドキュメント全体を読み込まないでください。
• ソースファイルを削除しないでください。
• シークレット、API キー、不要なローカルパスを公開しないでください。
• JSON の error.code または next_request を利用できる場合、人間の文章に基づいて分岐しないでください。