CLIの使用方法

Roboflow CLIを使用してBatch Processingジョブを作成および管理します。

インストールすることで 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 キーの確認方法についてサポートが必要な場合は、こちらをご覧ください authentication guide.

データを取り込む

画像

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 によって署名付き URL を生成するために使用されます。これらが アップロードされることは決してありません Roboflow サーバーへ。

生成された署名付き URL の有効期間は 24 時間です。batch processing job がこの時間内に完了するようにしてください。

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

署名付き URL 取り込み

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

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

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

参照ファイル形式（JSONL）:

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

署名付き 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 の場合。

ジョブの進行状況を監視する

start コマンドは Job IDを出力します。これを使ってステータスを確認します:

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

結果をエクスポートする

ジョブの詳細には output batch IDが含まれます。これを使って結果をエクスポートします:

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

Webhook 自動化

ステータスをポーリングする代わりに、Webhook を使用して取り込みまたは処理の完了時に通知を受け取ることができます。

データ取り込み Webhook

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": "単一画像の最大サイズは 20971520B です。"
            }
        ],
        "content_truncated": false
    },
    "delivery_attempt": 1
}

ジョブ完了 Webhook

追加する --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
}

クラウドストレージ認証

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. サービスアカウントキー ファイル （自動化に推奨）:

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 トークンを生成する:

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

カスタムスクリプト

高度なユースケース向けに、署名付き 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