xiaomi-ocr

Xiaomi-OCR-0

OCR、ドキュメント解析、KIE、または OCR-VQA が必要なタスクでは、このスキルを使用します。推論は、Hugging Face のチェックポイント SeerRay-Lab/Xiaomi-OCR-0 と SGLang、vLLM、または実験的な Ollama バックエンドを使って、ユーザーのマシン上で実行されます。MCP サービスがプロンプト、画像／PDF の準備、任意のレイアウト分割、切り抜き処理、並行処理、出力形式を管理します。タスクツールを呼び出してください。これらの手順を別々のツールやモデルへの直接リクエストで再現しないでください。

このリポジトリの MCP は、MCP サーバーホスト上のループバック HTTP エンドポイントに推論リクエストを送信します。Mify は呼び出しません。他にインストールされているスキルやサービスが xiaomi-ocr という名前を共有している場合があります。ファイルの処理場所を説明する前に、ツールの説明と設定から、選択されている MCP を特定してください。リモート MCP の場合、image_path と pdf_path はエージェントのマシンではなく、そのサーバーのファイルシステムを参照します。

ローカル推論をセットアップする

推論バックエンドを選択する

明示されたバックエンド／モデルの希望と、ユーザーが求める精度を尊重してください。それ以外の場合は、次のようにします。

• 既存のローカルサービス： 動作中の Xiaomi-OCR-0 エンドポイントと、設定済みのバックエンド／モデルを再利用します。MCP の設定、実行中のサービス、モデル一覧を確認してください。OpenAI 互換 URL だけではランタイムを特定できません。ユーザーの要件に反しない限り、動作中のバックエンドを維持してください。
• 対応 GPU 環境： 特に精度が重視される作業では、元の SeerRay-Lab/Xiaomi-OCR-0 チェックポイントを使う SGLang または vLLM を優先します。互換性のあるインストール済みランタイムとキャッシュ済みの重みを再利用してください。新規セットアップの場合は、ホストと Qwen3_5ForConditionalGeneration に対する現在の公式ランタイムサポートを確認し、対応している場合は vLLM を、互換性のある選択肢が SGLang の場合は SGLang を選択してください。
• SGLang／vLLM が利用できない、または適さないデスクトップ／ローカル環境： ホストに BF16 モデルを実行できる十分なメモリがある場合は、Qwen3.5 対応の Ollama を使用します。互換性のある macOS 環境を含め、手軽なローカル実行方法です。完全なリポジトリにあるOllama のセットアップに関する注意事項を読んでください。デフォルトでは longwayxu/xiaomi-ocr-0:bf16 を使用します。すでに存在する場合は再利用し、そうでない場合はユーザーのセットアップ／ダウンロードの許可を得て取得してください。量子化タグに黙って置き換えないでください。

Ollama は引き続き実験的な機能です。選択する場合は、文書に記載されている数式の違いを説明してください。BF16 の重みを使用しても、HF の出力との一致は保証されません。ユーザーが HF と同等の結果を求める場合は、SGLang／vLLM を介して元のチェックポイントを使用してください。その方法を利用できない場合は、制約を説明し、Ollama を選択する前にユーザーと精度のトレードオフを解決してください。バックエンド名だけを根拠に、数値的な同等性を約束しないでください。

MCP インストーラーを実行する前に、次の 3 つの変数すべてを設定してください。これにより、以前のバックエンドの値が誤って引き継がれるのを防げます。

サービス	XIAOMI_OCR_BACKEND	XIAOMI_OCR_LOCAL_URL（デフォルト）	XIAOMI_OCR_MODEL（デフォルト）
SGLang / vLLM	openai	http://127.0.0.1:8000/v1	SeerRay-Lab/Xiaomi-OCR-0
Ollama	ollama	http://127.0.0.1:11434/v1	longwayxu/xiaomi-ocr-0:bf16

既存のサービスの場合は、実際のループバックポートと、サービスが提供するモデル名を使用してください。インストーラーはこれらの値を MCP の設定に保存します。Ollama を使用する場合も含め、画像の準備とタスクのプロンプトは、この MCP サービス内で行ってください。

インストールして接続する

1. 既存のサービス、ランタイムのインストール状況、キャッシュ済みの重み、利用可能なメモリを確認し、上記のルールに従ってバックエンドを選択します。選択した接続経路と、必要な環境構築やダウンロードについて説明します。既存のセットアップ許可でこれらの変更が対象となる場合は、その許可を利用し、許可が不足している場合、または互換性や精度に関する選択が未解決の場合に限って確認します。インストールを開始するために、ユーザーがランタイムを選ぶ必要はありません。

2. 選択したランタイムがインストールされていない場合は、現在の公式インストールガイドに照らして、OS、GPU、ドライバー、関連する CUDA/PyTorch 環境を確認します。SGLang/vLLM では、Qwen3_5ForConditionalGeneration のサポートが必要です。Ollama では、リンク先のセットアップ手順に従います。デフォルトでは別のランタイムを置き換えず、互換性のある既存のインストールを再利用します。

3. 選択したサービスをループバックにバインドして起動します。Ollama では、リンク先の手順に従い、上記のモデルタグを使用します。SGLang/vLLM の例を以下に示します（ハードウェアに合わせてテンソル並列度とメモリ制限を調整してください）。

   python -m sglang.launch_server \
     --model-path SeerRay-Lab/Xiaomi-OCR-0 \
     --host 127.0.0.1 --port 8000 --context-length 16384
   

   vllm serve SeerRay-Lab/Xiaomi-OCR-0 \
     --host 127.0.0.1 --port 8000 \
     --trust-remote-code --max-model-len 16384
   

   エンジンがモデルを読み込めない、または画像を受け付けない場合は、最新の互換性に関する注意事項を確認します。既存のセットアップ許可でアップグレードが対象とならない場合は、アップグレードの許可を得ます。ホスト型エンドポイントには切り替えないでください。MCP の接続後、推論の準備が完了したと報告する前に、実際の画像リクエストを検証します。

4. GitHub リポジトリ全体を再利用するか、クローンします。MCP は共有の evaluation_pipeline/ モジュールと postprocess/ モジュールをインポートします。そのチェックアウト内の skills/xiaomi-ocr/ でインストーラーを実行します（Codex では bash install.sh --agent=codex、その他のエージェントでは bash install.sh）。Skill を個別に使用する場合は、XIAOMI_OCR_REPO にリポジトリ全体のチェックアウト先を設定します。bash install.sh を実行する前に、非公開の .venv を作成し、requirements.txt のパッケージをダウンロードすること、および該当する場合は Codex の設定に MCP エントリーを 1 つ登録することを説明します。利用可能な場合は、互換性のある既存の MCP 環境を再利用します。環境の作成や依存関係のダウンロードについて、すでに許可が得られていない場合は、ユーザーの許可を得てください。その他のエージェントでは、生成された mcp-config.json のエントリーを、無関係なエントリーを置き換えずに、現在のエージェントの MCP 設定にマージしてから、再起動または再スキャンします。MCP サービスはモデルのループバックリスナーにのみ接続します。

5. エージェントが支援するセットアップをすべて完了する場合は、ユーザーがページ単位のみのセットアップを希望しない限り、印刷文書の領域モードを含めます。セットアップ計画の一環として、PaddlePaddle/PaddleX パッケージと、PP-DocLayoutV3 の重みがダウンロードされる可能性について説明します。既存のセットアップ許可でこれらのダウンロードが対象となる場合は、その許可を利用します。対象とならない場合に限って確認します。

   OS、Python バージョン、CPU/GPU のサポート状況、利用可能な GPU メモリを、公式の PaddlePaddle インストールガイド および PaddleX インストールガイド に照らして確認します。 互換性のある PaddlePaddle ホイールを MCP 環境にインストールし、その環境の Python を使って -m pip install -r <repo>/requirements-paddlex.txt を実行します。これには paddlex[cv] と shapely が含まれます。PP-DocLayoutV3 には paddlex のみでは不十分です。互換性のある パッケージとキャッシュ済みの重みを再利用します。GPU メモリが限られている場合は、サポートされている CPU ビルドを使用し、MCP 環境に XIAOMI_OCR_LAYOUT_DEVICE=cpu を設定します。Demo が別の Python 環境を使用する場合は、Demo のセットアップ時に、そちらにも領域検出の依存関係をインストールします。 PP-DocLayoutV3 をローカルに読み込み（初回使用時に重みがダウンロードされる場合があります）、mode="region" を指定して ocr_image を実際に1回呼び出し、領域モードが使用可能であることを確認してから報告してください。領域検出、切り抜き、OCR は MCP サーバー内で行われます。プラットフォームがサポートされていない場合、またはセットアップに失敗した場合は、失敗した手順を報告し、確認済みのページ OCR、KIE、VQA の機能は維持してください。ページモードを領域モードとして誤って提示しないでください。

公式ランタイムのリファレンス： SGLang Qwen3.5 ガイド · vLLM Qwen3.5 モデル実装 · vLLM 対応モデル。

適切なタスクとドキュメントモードを選択する

• 印刷された通常のドキュメント：mode="region" を指定して ocr_image または ocr_pdf を使用します。MCP は PP-DocLayoutV3 をローカルで実行して領域を切り抜き、個別のリクエストを並行して送信した後、読み取り順を復元して出力をまとめます。モデルプロンプトでは OTSL を要求します。MCP は返された Markdown 内で表を HTML に変換し、LaTeX 数式を整形します。
• 情景内のテキスト、手書きのメモ、書道、歴史的な書籍、不規則なレイアウト：mode="page" を使用します。領域検出によって行、段、またはつながった手書き文字が不適切に分割され、文脈が失われたり、認識エラーが重なったりする場合があります。ページ全体モードでは、こうした関係性が保持されます。
• キー情報抽出：kie_image を呼び出します。出力キーが決まっている場合は fields を渡します。MCP がスキーマプロンプトを作成し、解析済みの JSON を返します。一般的なキーと値の抽出には、fields を空のままにします。
• ドキュメント画像に関する質問応答：画像と質問を指定して vqa_image を呼び出します。MCP は簡潔な回答形式を適用します。
• PDF：ocr_pdf を呼び出し、同じドキュメントの指針に従ってページモードまたは領域モードを選択します。ペイロードの切り捨てを避けるため、base64 よりローカルのファイルパスを優先してください。

利用可能な MCP ツールは ocr_image、ocr_pdf、kie_image、vqa_image、runtime_status です。ページ／領域の前処理と後処理は、これらの呼び出し内で行われます。

ocr_image、ocr_pdf、kie_image は max_tokens を受け付けます（デフォルトは 4096）。OCR では、ページモードの場合はページごと、領域モードの場合は領域ごとの最大出力トークン数です。すべての領域タイプに指定値が適用され、PDF の各ページ／領域にはそれぞれ個別の予算が割り当てられます。KIE では、単一の抽出に適用されます。明示的に指定した引数は、XIAOMI_OCR_MAX_TOKENS によるサーバーのデフォルト設定より優先されます。 出力が切り捨てられた場合は、画像／プロンプトのトークン数と要求する出力トークン数の合計が推論サーバーのコンテキストウィンドウに収まる場合に限り、値を増やしてください。コンテキスト超過エラーが発生した場合は、出力の予算を減らすか、入力を小さくする必要があります。vqa_image は簡潔な回答向けに、固定の 1024 トークンの予算を使用します。

ランタイムのモニタリング

簡潔な概要を確認するには、runtime_status({}) を使用します。解決済みデバイス、実行中のタスク、処理能力、直近で完了した3件のタスクが表示されます。ハードウェアを調査せずに特定のタスクを追跡するには、runtime_status({"request_id":"…"}) を使用します。IDは進行状況メッセージと、OCR結果の後に表示される独立した Runtime: テキストブロックに記載されています。最初のコンテンツブロックは引き続きOCR結果です。ランタイムブロックを抽出したドキュメントのテキストに含めないでください。完了したタスクの直近8件分のサマリーは、置き換えられるか、このプロセスが再起動されるまで照会できます。利用できないIDに対しては、完了を捏造せず found: false が返されます。実行中タスクのページ別およびステージ別の詳細を確認するには verbose: true を使用します。概要で最新のデバイス情報が必要な場合に限り refresh: true を使用してください。それ以外の場合、情報は30秒間キャッシュされます。これはこのサーバープロセスだけを報告するもので、別のDemo/MCPプロセスは対象ではありません。タスクのデバイス情報は、そのタスク中に最後に観測された情報です。最新のデバイス情報を取得する場合は、概要を確認してください。記録されたキャッシュ経過時間は、観測時点での経過時間です。人が読み取れるデバイスの配置には display_device を、ホストの nvidia-smi におけるカード番号には gpu_indices を使用してください。生の予測器 device はプロセスローカルのCUDAインデックスを使用する場合があるため、物理インデックスの代わりに使用してはいけません。デバイスラベルにUUIDは公開されません。CPUでの実行はランタイムメタデータで確認する必要があります。NVIDIAツールがないことやGPU上にデータがあることだけでは、CPUでの実行を証明できません。CPU + GPU は報告されたオフロード状態をそのまま示します。モデルは読み込みません。ランタイムで解決されたデバイスとその情報源を報告し、設定済み／要求されたデバイスとは分けてください。未ロードまたは観測不能なデバイスは不明のままにします。PaddleXはGPUを自動選択する場合があります。XIAOMI_OCR_LAYOUT_DEVICE=cpu を設定すると、MCPの再起動後にCPUレイアウトが選択されます。モニタリングを求められたことだけを理由に、ユーザーのデバイス配置を変更しないでください。

クライアントがMCPの進行状況に対応している場合は、ツールリクエストのメタデータに一意の _meta.progressToken を含めてください。進行状況は、レイアウトの読み込み／検出、キュー待ち、推論、PDFのページ／領域、組み立てを対象とし、待機中のハートビートも含みます。完了率を捏造せず、これらの更新をそのまま伝えてください。プロトコルの progress の数値はイベントの通し番号であり、割合でも作業件数でもありません。作業件数には、共有サマリーの pages と regions を使用してください。ページ数には、failed ページと成功した blank ページを含む、処理済みページ数が表示されます。PDFの領域合計は、total_is_final が true になるまで、検出済み領域の数を示します。現在の状況は phase、active_pages、elapsed_ms、last_activity_ms（ハートビート以外のイベントからの経過時間）、error、warning で確認できます。応答がないことだけでは、タスクが停止しているとは判断できません。終了状態では、完了、一部完了、失敗、キャンセルが区別されます。クライアントが進行状況に対応していない場合でも、構造化されたstderrログと最終結果の _meta.xiaomi_ocr サマリーを利用できます。別のOCR呼び出しが実行中でも、runtime_status を照会できます。

出力の処理

モデルの読み取り順序と Markdown を維持してください。読み取れない内容を補完せず、モデルの不確実性をそのまま残してください。テーブル変換とドキュメントの組み立ては MCP 内で行われます。エージェントに別の後処理ツールを呼び出すよう依頼しないでください。KIE では JSON のキーと値を維持し、VQA では根拠のない詳細を加えず、簡潔に回答してください。

MCP からローカルモデルが利用できないと報告された場合は、まず設定済みのサービスを確認してから、上記のバックエンド選択およびセットアップの承認ルールに従ってください。リージョンモードで PaddleX/PaddlePaddle が不足していると報告された場合は、追加パッケージとレイアウト用重みがダウンロードされる可能性を説明し、既存の承認を使用するか、インストールがその承認の対象外であれば許可を求めてください。その間、ページ全体モードは引き続き利用できます。

Demo と MCP は、同じ execute_tool および CallMonitor の実装を通じて実行されます。各サービスプロセス内で同時に実行されるタスクは最大 2 件で、OCR 推論の同時実行数はデフォルトで 4 です（XIAOMI_OCR_CONCURRENCY）。ビジーエラーが発生した場合は、タスクの完了後に再試行してください。Demo は画像のスナップショットを集約し、中間更新を 1 秒あたり 2 回に抑えます。また、アクティブな PDF ジョブを 1 秒に 1 回ポーリングします。アイドル状態のページでは、ハードウェアのポーリングは行われません。