CLI Usage

Roboflow CLI を使って Batch Processing jobs を作成・管理します。

をインストールすることで inference-cli へのアクセスが得られます。 inference rf-cloud コマンドを使用でき、Roboflow Batch Processing の中核コンポーネントである Batch Processing と Data Staging を操作できます。

セットアップ

pip install inference-cli
export ROBOFLOW_API_KEY="YOUR-API-KEY-GOES-HERE"

クラウドストレージをサポートするには:

pip install 'inference-cli[cloud-storage]'

API key の見つけ方が必要な場合は、こちらの 認証ガイド.

データを取り込む

画像

inference rf-cloud data-staging create-batch-of-images \
  --images-dir <your-images-dir-path> \
  --batch-id <your-batch-id>

動画

inference rf-cloud data-staging create-batch-of-videos \
  --videos-dir <your-videos-dir-path> \
  --batch-id <your-batch-id>

Batch ID の形式: 小文字のみ、最大 64 文字で、使用できるのは英字、数字、ハイフン (-)、およびアンダースコア (_).

クラウドストレージ

データがすでにクラウドストレージ（S3、Google Cloud Storage、または Azure）にある場合は、ファイルをローカルにダウンロードせずに直接処理できます。

画像の場合:

inference rf-cloud data-staging create-batch-of-images \
  --data-source cloud-storage \
  --bucket-path <cloud-path> \
  --batch-id <your-batch-id>

動画の場合:

inference rf-cloud data-staging create-batch-of-videos \
  --data-source cloud-storage \
  --bucket-path <cloud-path> \
  --batch-id <your-batch-id>

その --bucket-path パラメータは次をサポートします:

• S3: s3://bucket-name/path/

• Google Cloud Storage: gs://bucket-name/path/

• Azure Blob Storage: az://container-name/path/

glob パターンを含めてファイルをフィルタできます:

• s3://my-bucket/training-data/**/*.jpg — すべての JPG ファイルを再帰的に

• gs://my-bucket/videos/2024-*/*.mp4 — 2024-* フォルダ内の MP4 ファイル

• az://container/images/*.png — images フォルダ内の PNG ファイル

クラウドストレージの認証情報は ローカルでのみ CLI により presigned URL を生成するために使用されます。これらが アップロードされることは決してありません Roboflow のサーバーへ。

生成された presigned URL は 24 時間有効です。この時間内に batch processing ジョブが完了するようにしてください。

大規模データセットでは、システムが画像を自動的に 20,000 ファイルごとのチャンクに分割します。動画は 1,000 未満のバッチで最適に動作します。

Signed URL での取り込み

高度な自動化のために、ローカルファイルの代わりに signed URL 経由でデータを取り込むことができます:

• --data-source references-file — signed URL で参照されるファイルを処理します。

• --references <path_or_url> — ファイル URL を含む JSONL ファイルへのパス、またはそのようなファイルを指す signed URL。

Reference File 形式 (JSONL):

{"name": "<unique-file-name-1>", "url": "https://<signed-url>"}
{"name": "<unique-file-name-2>", "url": "https://<signed-url>"}

Signed URL による取り込みは、Growth Plan および Enterprise のお客様にご利用いただけます。

ステージング済みデータを確認

inference rf-cloud data-staging show-batch-details --batch-id <your-batch-id>

ジョブを開始

画像を処理

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

動画を処理

inference rf-cloud batch-processing process-videos-with-workflow \
  --workflow-id <workflow-id> \
  --batch-id <batch-id> \
  --machine-type gpu \
  --max-video-fps <your-desired-fps>

Workflow ID の見つけ方: Roboflow App で Workflow Editor を開き、「Deploy」をクリックして、コードスニペット内の識別子を確認します。

デフォルトでは、処理は CPU で実行されます。 --machine-type gpu 複数のモデルや大規模なモデルを使用する Workflows では、これを使用してください。

ジョブの進行状況を監視

開始コマンドは Job IDを出力します。状態の確認に使用します:

inference rf-cloud batch-processing show-job-details --job-id <your-job-id>

結果をエクスポート

job details には 出力 batch IDが含まれます。結果のエクスポートに使用します:

inference rf-cloud data-staging export-batch \
  --target-dir <dir-to-export-result> \
  --batch-id <output-batch-of-a-job>

Webhook 自動化

状態のポーリングの代わりに、取り込みまたは処理が完了したときに通知を受け取るために webhooks を使用できます。

Data Ingestion Webhooks

CLI コマンド create-batch-of-images および create-batch-of-videos は次をサポートします:

• --notifications-url <webhook_url> — 通知用 webhook エンドポイント。

• --notification-category <value> — 通知をフィルタします:

  • ingest-status （デフォルト）— 取り込みプロセス全体のステータス。

  • files-status — 個々のファイル処理ステータス。

通知は HTTP POST で配信され、 Authorization ヘッダーには Roboflow Publishable Key が含まれます。

取り込みステータス通知

{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8c20f970-fe10-41e1-9ef2-e057c63c07ff",
    "ingest_id": "8cd48813430f2be70b492db67e07cc86",
    "batch_id": "test-batch-117",
    "shard_id": null,
    "notification": {
        "type": "ingest-status-notification-v1",
        "success": false,
        "error_details": {
            "type": "unsafe-url-detected",
            "reason": "信頼できないドメインが見つかりました: https://example.com/image.png"
        }
    },
    "delivery_attempt": 1
}

ファイルステータス通知

{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
    "ingest_id": "d5cb69aa-b2d1-4202-a1c1-0231f180bda9",
    "batch_id": "prod-batch-1",
    "shard_id": "0d40fa12-349e-439f-83f8-42b9b7987b33",
    "notification": {
        "type": "ingest-files-status-notification-v1",
        "success": true,
        "ingested_files": [
            "000000494869.jpg",
            "000000186042.jpg"
        ],
        "failed_files": [
            {
                "type": "file-size-limit-exceeded",
                "file_name": "big_image.png",
                "reason": "1 枚の画像の最大サイズは 20971520B です。"
            }
        ],
        "content_truncated": false
    },
    "delivery_attempt": 1
}

ジョブ完了 Webhooks

追加 --notifications-url をジョブ開始時に指定します:

inference rf-cloud batch-processing process-images-with-workflow \
  --workflow-id <workflow-id> \
  --batch-id <batch-id> \
  --notifications-url <webhook_url>

ジョブ完了通知

{
  "type": "roboflow-batch-job-notification-v1",
  "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
  "job_id": "<your-batch-job-id>",
  "job_state": "success | fail",
  "delivery_attempt": 1
}

Cloud Storage 認証

AWS S3 および S3 互換ストレージ

認証情報は次から自動検出されます:

1. 環境変数:

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token  # 任意

1. AWS 認証情報ファイル (~/.aws/credentials, ~/.aws/config)

2. IAM ロール (EC2, ECS, Lambda)

名前付きプロファイル:

export AWS_PROFILE=production

S3 互換サービス (Cloudflare R2, MinIO など):

export AWS_ENDPOINT_URL=https://account-id.r2.cloudflarestorage.com
export AWS_REGION=auto  # R2 では region='auto' が必要です
export AWS_ACCESS_KEY_ID=your-r2-access-key
export AWS_SECRET_ACCESS_KEY=your-r2-secret-key

Google Cloud Storage

認証情報は次から検出されます:

1. サービスアカウント key ファイル （自動化に推奨）:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

1. ユーザー認証情報 gcloud CLI から (gcloud auth login)

2. GCP メタデータサービス （Google Cloud Platform 上で実行する場合）

Azure Blob Storage

SAS Token（推奨）:

export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_SAS_TOKEN="sv=2021-06-08&ss=b&srt=sco&sp=rl&se=2024-12-31"

Account Key:

export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_ACCOUNT_KEY=your-account-key

Azure CLI で SAS token を生成します:

az storage container generate-sas \
  --account-name mystorageaccount \
  --name my-container \
  --permissions rl \
  --expiry 2024-12-31T23:59:59Z

カスタムスクリプト

高度なユースケースでは、signed URL ファイルを生成するためのスクリプトを参照してください:

• AWS S3: generateS3SignedUrls.sh

• Google Cloud Storage: generateGCSSignedUrls.sh

• Azure Blob Storage: generateAzureSasUrls.sh

すべてのオプションを確認

inference rf-cloud --help
inference rf-cloud data-staging --help
inference rf-cloud batch-processing --help