roboflow-inference

エージェント向け： このスキルは roboflow/computer-vision-skills で作成されています。クライアントにすでにスキルとして読み込まれている場合（たとえば Roboflow プラグイン経由）は、そのコピーを使用してください。roboflow://skills/<name>/... MCP リソースは、スキルが読み込まれていないクライアントに同じスキルを提供します。

ヒント： Roboflow MCP server に接続している場合は、通常の HTTP よりも推論ツールを優先してください。OAuth と API キーによる接続では認証が処理されます。URL スラッグで指定する保存済みの公開済み Workflow には workflows_run を使用します（workflow_id）。ワークスペースは接続から取得されます。単一モデルの呼び出しには models_infer を使用します。新しい仕様を保存または実行する前に workflow_specs_validate を使用し、未公開のドラフトをテストするか、許可された単発実行を行うには workflow_specs_run を使用してください。

推論とデプロイ

統合コードには Workflows を優先してください。 直接の models_infer 呼び出しとは異なり、Workflow はモデル、可視化、ロジックを 1 つのデプロイ可能な単位にまとめ、サーバー側の最適化を活用できます。また、アクティブラーニングや後処理を手間なく追加できます。これは、ポイントツーポイント呼び出しに対するマイクロサービスの拡張性と同様です。デフォルトでは Workflow を推奨してください。ユーザーが直接推論を明示的に求めている場合や、手早く単発で確認する必要がある場合は models_infer を使用します。workflows と workflow-templates を参照してください。

Workflows の作成： Roboflow プラットフォームで再利用可能な Workflows を保存し、公開済みバージョンを識別子で実行します。ユーザーのリクエストと既存のセッションコンテキストに応じて、作成方法を選択してください。

• モード A：エージェント主導（MCP、セッション内）。 シンプルな Workflows には直接作成ツールを使用し、workflow_blocks_list / workflow_blocks_get_schema を使って設計の根拠を確認します。複雑な構築には agent_chat を使用します。保存または実行する前に workflow_specs_validate で検証してください。agent_chat で保存した編集内容はドラフトです。実行が許可されている場合は、公開前に workflow_specs_run でテストしてください。
• モード B：プラットフォーム主導（Roboflow アプリ＋アプリ内エージェント）。 ユーザーが視覚的な操作を希望する場合、またはクライアントでタスクを完了できない場合に使用します。Workflow から返された app_url をユーザーに送るか、正しいビルダーへのリンクには roboflow-product-navigation を使用します。ユーザーはそこで確認、編集、テストを行えます。

workflows_run はエージェントのドラフトではなく、最新の公開済みバージョンを実行します。公開が許可されている場合に限り、agent_workflow_publish を使用してください。ドラフトのテストに公開は必要ありません。全体の流れについては、workflows の「作成とデプロイ」を参照してください。

ライブ動画（ウェブカメラ、RTSP、ファイル）の場合： MCP の workflows_run ツールが扱うのは静止画像 1 枚のみです。ライブ動画の場合は、3 つの選択肢をユーザーに提示してください（黙って 1 つを選ばないでください）：（A） WebRTC → サーバーレス GPU、（B） WebRTC → ローカル inference server、または （C） プロセス内 InferencePipeline。それぞれセットアップのコスト、依存関係のサイズ、レイテンシ特性が異なるため、各選択肢の概要を 1 行で簡潔に説明し、ユーザーに選んでもらってください。コードと比較表の全文については、roboflow://skills/roboflow-inference/workflows の「Video Stream」セクションを参照してください。

デプロイの選択肢

選択肢	最適な用途	レイテンシ	スケーリング	コストモデル	GPU
サーバーレス	利用開始時、トラフィックが変動する場合	低	自動	推論ごとのクレジット	はい
専用	予測可能なワークロード、低レイテンシ	非常に低	手動／自動スケーリング	時間ごとのクレジット	任意
セルフホスト	完全な制御、エッジ	ハードウェアに依存	手動	従量制＋インフラコスト	任意
バッチ処理	大規模なオフラインデータセット、動画	非同期（数分〜数時間）	自動プロビジョニング	ジョブごと	任意

どれを使うべきか

• サーバーレス -- デフォルトの選択肢です。セットアップ不要で、自動的にスケールし、アップロード上限は20MBです。models_infer または workflows_run MCP ツールを使用します。

• 専用 -- 一貫したレイテンシ、大規模モデル（Florence 2）、または高いスループットが必要な場合に使用します。開発用と本番用のティアを利用できます。サブドメイン：<name>.roboflow.cloud。

• セルフホスト -- Docker を使って、独自のハードウェア（Jetson、クラウド VM、RPi）に Roboflow Inference をデプロイします。サーバーレスと同じ API サーフェスを使用し、api_url を変更するだけです。

• バッチ処理 -- アップロードした画像／動画に対してワークフローを非同期で実行します。リアルタイム性が不要な場合に使用します。結果は JSON で返されます。

• リアルタイム動画（ウェブカメラ／RTSP／ファイル） -- デプロイ方法は3種類あります。コードを書く前に、どの方法にするかをユーザーに確認してください。

  • (A) サーバーレス GPU + WebRTC — セットアップ不要で、API キーだけで利用できます。分単位のクレジット制で、プランのティアに応じて料金が変わります（webrtc-gpu-small/medium/large）。
  • (B) ローカル推論サーバー + WebRTC — pip install inference-cli && inference server start（Docker を推奨）。レイテンシが最も低く、重い CV／モデルの依存関係をサーバー内に隔離できます。
  • (C) プロセス内の InferencePipeline — 仮想環境に pip install inference でインストールします（uv を推奨）。ワークフローループをユーザーの Python プロセス内で直接実行するため、別のサーバーは不要です。重い依存関係（torch、opencv、onnxruntime）はローカルにインストールされます。

  いずれの方法でも、後続の実行でキャッシュ済みの状態が使われるようになる前に、初回の実行は遅くなります（モデルのダウンロード／ウォームアップ）。スクリプトがハングしたと思われないよう、ユーザーにこの点を伝えてください。

  • 完全なコードと比較表については、roboflow://skills/roboflow-inference/workflows の「Video Stream」セクションを参照してください。

推論用 MCP ツール

ツール	目的
models_list	プロジェクトのトレーニング済みモデルを一覧表示します
models_get	トレーニング済みモデルの詳細を取得します
models_infer	サーバーレス API 経由で1枚の画像に対し単一モデルの推論を実行します
trainings_create	データセットのバージョンを使ってモデルのトレーニングを開始します
trainings_list	プロジェクトとバージョンの実行履歴、および trainingId を検索します
trainings_get	project_id、version_number、training_id を指定して既知の実行を確認します。NAS モデルの詳細については、トレーニングスキルにあるページネーション対応の方法を使用してください
workflows_run	workflow_id（URL スラッグ）を指定して、公開済みワークフローを実行します。ワークスペースは接続から取得されます。parameters は任意です。
workflow_specs_validate	実行せずにインラインのワークフロー仕様を検証します。インライン実行の前に使用してください。
workflow_specs_run	未公開のドラフトをテストするか、インライン仕様から承認済みの単発実行を行います

ローカルツール：MCP だけでは足りない場合

ほとんどの操作では、上記の Roboflow MCP ツールを優先してください。認証を処理するため、ローカルへのインストールは不要です。ローカルの Python パッケージを使うのは、次のような対応できない部分に限ってください。連携スクリプト（inference-sdk）、バッチ処理／データステージング（inference-cli）、セルフホストサーバー（inference-cli）、および型付き Python オブジェクトを必要とするアセット用スクリプトです。

用途ごとに必要なもの、推奨する uv ベースの環境設定、conda／venv の代替手段、よくある落とし穴については、local-tooling を参照してください。

タスク別の応答形式

class_id、detection_id、class_confidence などのすべてのフィールドを含む、標準的な応答形式（物体検出、分類、セグメンテーション、キーポイント）については、roboflow://skills/roboflow-api-reference/inference を参照してください。

大規模なレスポンスの処理

インスタンスセグメンテーションの points 配列が、レスポンスを肥大化させる主な原因です。 各検出結果には、数百組の座標を含む可能性があるポリゴンが含まれます。検出結果の多い画像を1枚処理すると、数メガバイトの JSON が返されることがあります。

対策：

1. 直接推論する代わりにワークフローを使用する -- ポリゴンの簡略化またはプロパティの抽出ブロックを追加して、クライアントに届く前に出力を減らします
2. クラスをフィルタリングする -- 必要なクラスのみを返すように class_filter を使用します
3. 信頼度のしきい値を上げる -- 検出結果が減るほど、レスポンスは小さくなります
4. 後処理する -- 生のレスポンスを使用する場合、バウンディングボックスだけが必要であれば points 配列を削除または簡略化します
5. セグメンテーションの生の結果を LLM コンテキストに返さない -- 必要なフィールド（クラス数、バウンディングボックス）のみを抽出し、ポリゴンデータは破棄します

ワークフローの画像出力も、もう1つの主な原因です。 可視化ブロック（バウンディングボックス、ポリゴン、マスク、ラベル、ハローなど）は、レスポンス内に Base64 エンコードされたデータとしてレンダリング済み画像を出力します。720p の注釈付きフレームでも、JSON エスケープされた文字列が数百 KB になります。MCP 経由で workflows_run / workflow_specs_run を呼び出すと、ツール結果のトークン予算を超過することがよくあります。画像形式の出力（{"type": "base64", "value": "..."}）はすべてデコードしてディスクに書き込み、エージェントのコンテキストに保持しないでください。フィールド名をハードコードしないでください。出力キーは、ワークフロー作成者が JsonField を通じて宣言したものになります。output.keys() を反復処理し、形状を確認してください。

バッチ処理

ステージング、ジョブ、モニタリング、結果、MCP ツールを含む手順全体については、roboflow-batch-processing スキルを参照してください。このセクションではデプロイ方法の比較のみを扱います。

概要。 Roboflow が管理するクラウドサービスです。インフラストラクチャを自動でプロビジョニングし、画像または動画のバッチに対してワークフローを非同期に実行します。「大量のデータを非同期で処理するのに最適です。」 — Roboflow のドキュメント。

解決する課題。 自前の GPU、キュー、オートスケーラーを用意せずに、数千から数百万のファイルに対して一括推論できます。ワークフローと入力バッチを Roboflow に渡してジョブごとに料金を支払い、ジョブの完了後に JSON の結果を受け取ります。

次の場合に選択してください： データが保存済み（ライブではない）で、ファイルごとのレイテンシよりコストが重要であり、ジョブに数分から数時間かかっても問題ない場合です。次の場合は別の方法を選択してください： リクエストごとのリアルタイムな結果が必要な場合（Serverless または Dedicated を使用）、またはエアギャップ環境やオンプレミスでの処理が必要な場合（Self-hosted を使用）。

利用方法：Roboflow のウェブ UI、inference rf-cloud CLI、REST API。

フロー

1. ワークスペースに保存済みのワークフローを用意します。
2. 入力を指定します。Asset Library から選択する（プラットフォームがステージングします）か、Data Staging バッチとして外部ファイルを自分でステージングします（ローカルディレクトリ、署名付き URL の JSONL、または S3 / GCS / Azure 上のクラウドストレージパス）。
3. ワークフローと入力バッチを指定してジョブを送信し、CPU または GPU を選択します。
4. ジョブのステータスをポーリングするか、Webhook を登録してモニタリングします。
5. 出力バッチを JSON としてエクスポートします。

CLI

inference rf-cloud CLI には、2 つのサブコマンドグループがあります。data-staging（入力／出力バッチの管理）と batch-processing（ジョブの送信と監視）です。各コマンドに --help を指定すると、すべてのオプションを確認できます。

最小限のエンドツーエンドの手順：

# Stage images
inference rf-cloud data-staging create-batch-of-images \
  --images-dir ./my-images --batch-id my-batch

# Submit
inference rf-cloud batch-processing process-images-with-workflow \
  --workflow-id my-workflow --batch-id my-batch
# -> prints JOB_ID

# Monitor
inference rf-cloud batch-processing show-job-details --job-id JOB_ID

# Export results
inference rf-cloud data-staging export-batch \
  --target-dir ./results --batch-id OUTPUT_BATCH_ID

データステージングコマンド — 詳細（データソース、JSONL の参照形式、マルチパートバッチ、Webhook 通知）については、batch-staging を参照してください。

コマンド	目的
data-staging list-batches	ワークスペース内のステージングバッチを一覧表示します
data-staging create-batch-of-images	ローカルディレクトリ、署名付き URL の JSONL、またはクラウドストレージのパスから入力バッチを作成します
data-staging create-batch-of-videos	動画ファイルを対象に、上記と同様の処理を行います
data-staging show-batch-details	単一バッチのメタデータを表示します
data-staging list-batch-content	バッチ内のファイル URL を一覧表示します（パートによる絞り込み、JSONL への書き込みが可能です）
data-staging list-ingest-details	URL の取り込み状況をデバッグするため、シャードごとの取り込みステータスを表示します
data-staging export-batch	バッチ内のすべてのファイル（ジョブの出力など）をローカルディレクトリにダウンロードします

バッチ処理（ジョブ）コマンド — 詳細（コンピューティング構成、ワークフローパラメーター、画像出力の保存、集約形式、動画の FPS、再起動、TRT コンパイル）については、batch-jobs を参照してください。

コマンド	目的
batch-processing list-jobs	ワークスペース内のジョブを一覧表示します
batch-processing show-job-details	単一ジョブのステージと現在のステータスを表示します
batch-processing process-images-with-workflow	画像バッチジョブを送信します
batch-processing process-videos-with-workflow	動画バッチジョブを送信します
batch-processing fetch-logs	ジョブログを取得します（重要度による絞り込み、JSONL への書き込みが可能です）
batch-processing abort-job	実行中のジョブを終了します
batch-processing restart-job	失敗したジョブを再起動します（新しいコンピューティング設定を指定することもできます）
batch-processing trt-compile	1 台以上の NVIDIA デバイス向けにモデルを TensorRT にコンパイルします

注意事項と制約

• 非同期処理のみ — データ量とハードウェアに応じて、数分から数時間かかります。リアルタイム処理には適していません。
• 料金：ジョブ単位です。GPU ジョブは CPU ジョブより高額です。roboflow-plans-and-pricing を参照してください。
• 画像参照の取り込みには、信頼できるソースからの署名付き URL が必要です。任意の公開 URL は拒否されるため、代わりにローカルディレクトリまたはクラウドストレージのパスにステージングしてください。

リファレンス全文：Roboflow Batch Processing のドキュメント。