roboflow-batch-processing

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

バッチ処理

Roboflow の自動スケーリングコンピューティングで、非常に大量の画像や動画に対して Roboflow Workflow を実行します。各ジョブは一時的な Data Staging バッチを処理します。2 つの入力方法の違いは、誰がそのバッチにデータを入れるかだけです。

• Asset Library ジョブ — ファイルはすでに Roboflow にあります。プラットフォームに対象を指定すると、プラットフォームがファイルを選択してステージングします。
• ステージ済みジョブ — ファイルは Roboflow の外部（ローカルディスク、クラウドバケット、参照ファイル）にあるため、inference-cli を使って自分でステージングします。アクセスできるのは、お使いのマシンと認証情報だけです。ワークスペースには何もインポートされず、ステージ済みデータは約 7 日後に期限切れになります。

どちらを選ぶ？ 3 つの質問

1. ファイルはすでに Roboflow（Asset Library）にありますか？ 安定した冪等性キーと、選択条件 image_ids、query、all_images=true のいずれか 1 つだけを指定して、batch_processing_asset_library_job_create を呼び出します。プラットフォームがアクセスを確認し、ファイルを選択してステージングし、Workflow との互換性を検証して課金し、永続的なジョブを登録します。返された taskId を batch_processing_asset_library_task_get でタスクが終了状態になるまでポーリングし、その後 jobId を batch_processing_job_get で監視します。
2. ファイルは Roboflow の外部にあり、出力だけが必要ですか？ 以下で説明するように、自分でステージングし、batch_processing_guide と batch_processing_run を使って実行します（従来型の ETL 構成で、ワークスペースには何も保存されません）。ステージングと結果のエクスポートは、ファイルにアクセスできるマシン上で実行する必要があります。
3. Roboflow の外部にあるファイルを Roboflow の中に取り込みたいですか（ラベル付け、キュレーション、トレーニングなど）？ これはバッチ処理ジョブではなく、インポートです。データソースでバケットをミラーリングします（connect_cloud_storage。cloud-storage スキルを参照）。ミラーリング後、ファイルは Asset Library の画像になるため、一括予測も必要な場合は、それらを対象に Asset Library ジョブを実行します（従来型の ELT 構成で、最初にロードしてから変換します）。

「データソース」と「バケットミラー」は同じものです。データソースは、Asset Library にデータを取り込むバケットミラー設定のユーザー向けの名称です。データソース自体が Workflow を実行することはありません。

パイプラインの用語では、ステージ済みジョブは ETL フローの T にあたり（ロードは行われません）、Asset Library ジョブは ELT フローの T にあたります。ロードはアップロードまたはデータソースのミラーリングによって、すでに完了しています。

前提条件

• ワークスペースでバッチ処理機能が有効になっている必要があります。有効化が必要な呼び出しは、402 エラー「このワークスペースではバッチ処理が有効になっていません。プランをアップグレードするか、https://roboflow.com/sales から営業にお問い合わせください。」で失敗します。
• ジョブはクレジットを消費するため、ワークスペースに正の残高が必要です。
• Workflow はワークスペースにすでに存在している必要があります（workflows_list、workflows_create）。ジョブは workflow_id で Workflow を参照します。インライン仕様を指定する方法はありません。
• API キー：inference-cli は環境変数 ROBOFLOW_API_KEY を読み込みます。また、すべてのコマンドで --api-key=<key> も使用できます。roboflow login で保存したキー（~/.config/roboflow/config.json）は inference-cli に読み込まれません。環境変数に設定するか、--api-key を明示的に指定してください。api_keys_create MCP ツールでキーを作成します。ユーザーにプライベートキーをチャットへ貼り付けるよう求めないでください。

各ステップの実行場所とその理由

MCP サーバーはユーザーのディスクの読み書きができないため、次の2つのステップは inference-cli でのみ実行します。

• ステージングは、ファイルにアクセスできるマシン（ローカルディスク）上で、またはユーザーのクラウド認証情報を使って（バケットソースの場合）実行します。
• 結果のエクスポート（export-batch）では、ローカルディレクトリにダウンロードします。

その間の処理では API キーだけが必要なので、どちらの方法でも実行できます。MCP ツール（batch_processing_run、batch_processing_staged_job_start、batch_processing_job_get、batch_processing_jobs_list、batch_processing_job_logs、batch_processing_job_abort、batch_processing_job_restart、および batch_processing_asset_library_* と batch_processing_staging_* の各ファミリー）を使うか、同等の CLI コマンドを使います。ホストにシェルがない場合、またはユーザーがローカルに inference-cli を持っていない場合は MCP ツールを優先してください。ユーザーがすでにターミナルを使っている場合は CLI を優先してください。どちらのコンテンツタイプでも、コマンド一式はセクション1～5に記載されています。

batch_processing_guide MCP ツールはリクエストを振り分けます。バッチ ID を確定し、ステージングソースを選択して、順序どおりの正確なコマンドを返します。ファイルやネットワークには一切アクセスせず、このドキュメントの内容を繰り返すこともありません。

ステージング済みバッチ用のマスターツール：batch_processing_run

指定したステージング済みバッチを対象に処理を進めるには、batch_processing_run(batch_id, workflow_id, content_type, ...) を優先してください（Asset Library の選択項目には、代わりに batch_processing_asset_library_job_create を使用します）。呼び出すたびに現在の状態を確認し、可能な処理を進めて、ステータスをすぐに返します。

• staging_required — まだバッチがありません。レスポンスに、実行全体の CLI コマンドとクラウド認証情報に関する案内が含まれます。コマンドを実行してから、再度呼び出してください。
• ingest_in_progress — ファイルの登録中です。
• ingest_failed — インジェストが失敗したか、不明なシャード状態が返されました。有料ジョブは開始されていません。
• running — ジョブは開始済み、または実行中です。ステージの進捗状況も含まれます。
• completed — エクスポートバッチ ID と、署名付きダウンロード URL を含む最初の結果ファイルが含まれます。
• failed — ログと再開方法のヒントが含まれます。

サーバーがユーザーに代わって待機することはありません。 終端状態ではないレスポンスには retryAfterSeconds が含まれます。指定された時間だけ待ってから、返された job_id と同じ batch_id を指定して再度呼び出し、処理を再開してください。読み取り専用で再開する場合は、作成時のオプション設定を省略してください。有料ジョブに保存された定義が正しい値として扱われます。サーバーは呼び出し間で状態を保持しません。

ジョブは（ワークスペース、バッチ、ワークフロー）から導出された ID で開始されるため、レスポンスが失われた後に再試行しても、2回目の実行に課金されるのではなく、同じジョブが再登録されます。（プラットフォームは冪等性の比較より前にクレジットを確認するため、再試行時に先に 429 が返ることがあります。）409 は、その ID が異なるバッチ／Workflow ID ですでに存在するか、明示的に指定したオプション設定と競合していることを意味します。ジョブを確認し、保存済みの設定で監視するにはオプション設定を省略するか、別の実行用に新しい job_id を明示的に渡してください。

詳細設定（max_runtime_seconds、max_parallel_tasks、max_image_failure_rate、image_outputs_to_save）を使うには、batch_processing_staged_job_start を直接使用してください。

Webhook

Roboflow は、ユーザーが管理する URL にジョブとインジェストの通知を POST します。MCP 側のリレーはありません。batch_processing_staged_job_start に notifications_url を渡すか、CLI コマンドで --notifications-url を指定して、ユーザー独自の受信先を設定してください。POST には、公開可能キーを含む Authorization ヘッダーが付与されます。

注意点：ローカルの動画ステージングでは --notifications-url はサポートされません（CLI は警告を表示して、このオプションを無視します）。また、規模の小さいローカルの画像バッチ（32ファイル以下）はシンプルなバッチとしてステージングされるため、このオプションは無視されます。シャーディングされたローカル画像、クラウドストレージ、参照ファイルのインジェストでは、いずれもサポートされています。

受信先がない場合は、batch_processing_job_get をポーリングしてください（または、呼び出すたびに進捗状況を報告する batch_processing_run を使ってください）。

1. CLI をインストールする

pip install inference-cli
# For s3:// gs:// az:// sources:
pip install 'inference-cli[cloud-storage]'

以下の各 inference rf-cloud コマンドは、環境変数の ROBOFLOW_API_KEY、またはコマンド自体の --api-key=<key> を使って認証します。

クラウドの認証情報は、CLI を実行しているマシンの標準的な環境変数チェーンから取得されます。AWS の場合はデフォルトの認証情報チェーンを使用します（AWS_PROFILE が適用されます。AWS_ENDPOINT_URL を使って R2／MinIO に接続でき、併せて AWS_REGION が適用されます）。GCS の場合は GOOGLE_APPLICATION_CREDENTIALS、Azure の場合は AZURE_STORAGE_ACCOUNT_NAME と AZURE_STORAGE_ACCOUNT_KEY または AZURE_STORAGE_SAS_TOKEN を使用します。S3／GCS の場合、CLI は署名付き URL（有効期限は 24 時間）を生成します。Azure の場合は SAS トークンを付加するため、その URL はトークンが有効な限り使えます。いずれの場合も、URL は Roboflow に渡され、バケットのシークレットがマシンの外に出ることはありません。

2. バッチをステージングする

バッチ ID に使用できる文字は、小文字、数字、-、_ です。ステージングしたバッチは約 7 日後に期限切れになります。

# Local images (>32 images are packed into tar shards automatically)
inference rf-cloud data-staging create-batch-of-images \
  --batch-id my-batch --images-dir ./images

# Local videos (uploaded one by one via signed URLs)
inference rf-cloud data-staging create-batch-of-videos \
  --batch-id my-batch --videos-dir ./videos

# Cloud bucket (S3/GCS/Azure; glob over object paths).
# Videos work exactly the same way: create-batch-of-videos.
inference rf-cloud data-staging create-batch-of-images \
  --batch-id my-batch --data-source cloud-storage \
  --bucket-path 's3://my-bucket/images/**/*.jpg'

inference rf-cloud data-staging create-batch-of-videos \
  --batch-id my-batch --data-source cloud-storage \
  --bucket-path 's3://my-bucket/videos/**/*.mp4'

# References file: JSONL lines of {"name": ..., "url": "https://..."}
inference rf-cloud data-staging create-batch-of-images \
  --batch-id my-batch --data-source references-file --references refs.jsonl

画像と動画のどちらを扱うかは、パスから推測されるのではなく、選択するものです。create-batch-of-images と create-batch-of-videos はどちらも、すべてのデータソースを受け付けます。コンテンツに合った方を選んでください。

シャーディング、クラウドストレージ、参照データの取り込みは非同期です。ジョブを開始する前に、バッチの取り込みが完了するまで待ってください。

inference rf-cloud data-staging show-batch-details --batch-id my-batch
inference rf-cloud data-staging list-ingest-details --batch-id my-batch

または、ファイル数と、pending フラグおよび failed フラグを含む ingest ブロックを返す batch_processing_staging_batch_get MCP ツールを使います。pending が true、または failed が true の間はジョブを開始しないでください。ジョブの実行にはクレジットが必要であり、入力が不完全なまま実行されるためです。

実用上の上限：取り込みリクエストあたり最大 20,000 件の画像参照（自動的に分割されます。動画参照はリクエストあたり最大 5,000 件で、分割されません）、1 バッチあたりの動画は約 1,000 件を推奨します。画像形式は jpg/png/webp/bmp/jp2、動画形式は mp4/mov/avi/mkv/flv/wmv/m4v です。batch_processing_staging_batches_list では、ワークスペース内のステージング済みバッチ（入力とジョブの結果）をすべて確認できます。

3. ジョブを開始する

CLI、画像：

inference rf-cloud batch-processing process-images-with-workflow \
  --batch-id my-batch --workflow-id my-workflow --machine-type gpu

CLI、動画：

inference rf-cloud batch-processing process-videos-with-workflow \
  --batch-id my-batch --workflow-id my-workflow --machine-type gpu \
  --max-video-fps 5

共通のオプションフラグ：--workers-per-machine 1|2|4|8、 --aggregation-format jsonl|csv、--save-image-outputs、 --image-outputs-to-save <name>、--image-input-name <name>、 --workflow-params params.json、--max-runtime-seconds <n>、 --max-parallel-tasks <n>、--job-id <id>、--job-name <name>、 --notifications-url <url>、--part-name <part>。

画像のみ：--max-image-failure-rate 0.0-1.0（動画ジョブで指定するとサーバーが拒否します）。動画のみ：--max-video-fps <n>。

MCP での同等の方法：

batch_processing_staged_job_start(
  job_id="my-stable-job-id",           # required; reuse for retries
  batch_id="my-batch", workflow_id="my-workflow",
  content_type="images",            # or "videos"
  machine_type="gpu",               # cpu|gpu, optional
  workers_per_machine=4,            # 1, 2, 4 or 8, optional
  aggregation_format="jsonl",       # or "csv"
  save_image_outputs=True,          # persist crops/visualizations
)

動画の場合は、content_type="videos" を設定し、必要に応じて max_video_fps=5（予測のサブサンプリング）を指定します。このツールは、画像ジョブでの max_video_fps と、動画ジョブでの max_image_failure_rate をプラットフォームと同様に拒否します。

cpu と gpu の選び方（machine_type）

デフォルトのコンピューティング環境は CPU です。バッチ全体に対する有料ジョブを開始する前に、次の 2 点を手早く確認してください。

1. 代表的な画像 1 枚でワークフローをテスト実行します（workflows_run MCP ツール、またはホスト型 API）。実行時間を計測してください。2 回実行し、2 回目の呼び出しを計測します（1 回目はコールドスタートの可能性があります）。1 枚の処理にモデルの実行時間が約 1 秒以上かかる場合、大規模なバッチでは CPU ワーカーの処理が非常に遅くなるため、gpu を選んでください。
2. ワークフローの仕様を確認します（workflows_get）：モデルのステップ数を数え、それぞれのサイズを確認してください。小規模なファインチューニング済み検出器または分類器が 1 つだけなら、cpu が最も安価で、通常は十分です。複数のモデルを連結している場合、または大規模な基盤モデル（SAM ファミリー、CLIP、OCR、VLM ブロック）を含む場合は、gpu を選んでください。

動画では --max-video-fps に応じてフレームごとの処理が増えるため、こちらも gpu を選ぶのがおすすめです。次に、workers_per_machine（1/2/4/8）で 1 台のマシンのスループットを調整します。ワーカーを増やすと使用率は向上しますが、OOM のリスクも高まります。

同じ job_id と同一の定義を使うと冪等になります。異なる定義は 409 エラーで拒否されます。このツールは、有料の登録呼び出しの前に取り込みが完了していることを確認します。マルチパート入力の場合は part_name を指定してください。これは batch_processing_run でもサポートされています。どちらのツールもデフォルトで現在の inference-models バックエンドを使用します。既知の互換性要件がある場合に限り、inference_backend="old-inference" を使用してください。

4. 監視

inference rf-cloud batch-processing show-job-details --job-id my-job
inference rf-cloud batch-processing fetch-logs --job-id my-job
inference rf-cloud batch-processing abort-job --job-id my-job
inference rf-cloud batch-processing restart-job --job-id my-job

MCP の同等ツールは、レンダリングされたテーブルではなく JSON を返します。

• batch_processing_job_get(job_id) — ステータス、現在および予定されているステージ、ステージごとの進捗、出力バッチを確認できます。終了状態は job.isTerminal + job.error です。
• batch_processing_job_logs(job_id) — 診断用の情報ログとエラーログを確認できます。
• batch_processing_job_abort(job_id) / batch_processing_job_restart(job_id) — 実行を停止するか、失敗した実行を再試行します（必要に応じてマシンタイプ、ワーカー数、タイムアウトを上書きできます）。
• batch_processing_jobs_list(search=...) — ワークスペース内の最近のワークフロージョブを検索し、控えていないジョブ ID を見つけられます。内部の TensorRT コンパイルジョブは除外されます。このツールと batch_processing_job_get は、各ジョブに inputSource のラベルを付けます。asset-library はプラットフォームがステージングした選択項目、staged-batch は自分でステージングしたバッチを示します。

5. 結果のダウンロード

結果は、プラットフォームが生成する次のバッチとして Data Staging に保存されます。 <job-id>-processing（シャードごとの未加工出力）と <job-id>-export （ダウンロード可能なアーカイブにパッケージ化されたもの）です。

ダウンロードするとディスクに書き込まれるため、この手順は CLI のみで実行できます。

inference rf-cloud data-staging export-batch \
  --batch-id my-job-export --target-dir ./results

この処理は再開可能です。すでにエクスポートした内容を再取得するには --override-existing を追加し、マルチパートバッチの一部だけを取得するには --part-name <part> を追加してください。

MCP ツール batch_processing_staging_batch_files_list(batch_id="<job-id>-export") を使うと、同じファイルを署名付きの downloadURL とともに一覧表示できます（有効期限は約 24 時間）。そのため、シェルを使えないホストからも取得できます。エクスポートバッチはマルチパートです。パートが 1 つだけの場合はツールが自動的に選択し、複数ある場合は part_name の指定を求めます（パートは batch_processing_staging_batch_get で確認できます）。アーカイブ（.tar / .tar.gz）はダウンロード後に展開する必要があります。一度の呼び出しで一覧表示できるエントリは最大 10,000 件です。この規模を超える場合は、nextPageToken とパートごとの part_name を指定してページネーションを続けるか、再開可能な export-batch ですべて取得してください。

7 日以内に実行してください。ステージング済みの入力と結果は期限切れになります。