本番導入準備チェックリスト

Roboflow デプロイの本番導入準備 - HTTP エラー処理と再試行、タイムアウトとコールドスタート、レート制限、Dedicated Deployment のレプリカサイズ。

選択したら デプロイ オプションを、このページを使用して、本番トラフィックを処理する前に統合を堅牢化してください。エラー処理と再試行、タイムアウトとコールドスタート、レート制限、レプリカのサイジングについて説明します。対象は 専用デプロイメント.

HTTP エラーと再試行

Roboflow の推論 API および管理 API は、標準 HTTP ステータス コードを使用します。ツール間の完全な対応表（REST ステータス コード、SDK 例外、CLI 終了コード）は、 エラーとステータス コードにあります。本番環境での重要な原則は、実際に再試行可能なものだけを再試行することです:

ステータス	再試行？	ガイダンス
200 / 204	-	成功。
400	いいえ	不正なリクエストです。ペイロードを修正してください。再試行しても同じ不正なリクエストが送信されます。
401 / 403	いいえ	認証またはアクセスの失敗です。再試行してもキーは有効になりません。API キーとそのスコープを確認してください。
402 / 423	いいえ	プランの制限、クォータ到達、または請求の一時停止です。 請求 側で解決し、ループで再試行しないでください。
404	いいえ	リソースが存在しないか、キーからは表示されません。
429	はい	レート制限に達しています。バックオフし、指数バックオフで再試行してください（ レート制限).
5xx	はい	一時的なサーバーエラーです。バックオフを使用して安全に再試行できます。

バックオフ パターン。 対象: 429 および 5xxについては、指数バックオフとジッター（例: ランダムなオフセットを加えた 1 秒、2 秒、4 秒、8 秒）で再試行し、試行回数に上限を設けてください。決して自動的に再試行しないでください 401/403/404/400 。代わりに、それらはアプリケーションに通知してください。

次を呼び出す場合: 専用デプロイメント 管理サービス（https://roboflow.cloud）では、レスポンス コードを明示的に確認してください: 200 は JSON 本文を返し、それ以外のコードは文字列としてエラー メッセージを返します。

タイムアウトとコールドスタート

この Serverless Cloud API は、オンデマンドでモデルをロードします。サーバーにまだ常駐していないモデルへの最初のリクエスト（「ウォームアップ」）には数秒かかる場合があります。また、アイドル状態だったモデル（たとえば、推論間隔が約 10 分）はアンロードされ、次回の呼び出し時に再ロードが必要になる場合があります。

• クライアントのタイムアウトを十分に長く設定してください。 コールドスタート時に発生するほど短いクライアント タイムアウトを設定すると、本来は成功していたリクエストが失敗します。最初のリクエスト時およびアイドル期間後は、ウォームアップのための余裕を確保してください。

• モデルを事前にウォームアップしてください。 予測可能なレイテンシが重要な場合は、レイテンシに敏感なトラフィックの前にウォームアップ リクエストを送信し、モデルがすでにキャッシュされているようにしてください。

• レスポンス ヘッダーを監視してください。 サーバーレスのレスポンスには、 x-model-cold-start （このリクエストがロード コストを負担したかどうか）と x-processing-timeが含まれます。これらを使用して、コールドスタートの頻度と処理時間を監視してください。これらのヘッダーが請求にどのように影響するかについては、 サーバーレス料金 を参照してください。

• アップロードを制限内に収めてください。 Serverless Cloud API は、最大 20 MBまでのファイル アップロードを受け付けます。それより大きい画像は拒否されます。送信前に画像を縮小してください（Python SDK はこれを自動的に行います）。画像はいずれにせよモデルの入力サイズにリサイズされるため、通常は精度に影響しません。バッチ処理でも、画像 1 枚あたり同じ 20 MB の上限が適用されます。

コールドスタートなしで低レイテンシを継続的に実現するには、 専用デプロイメント または セルフホスト型推論 を共有サーバーレス エンドポイントの代わりに使用してください。

レート制限

• Serverless Cloud API。 次の場合: 429、速度を落とし、指数バックオフで再試行してください。継続的に制限に達する場合や、より高いスループットが必要な場合は、エンタープライズ サポート担当者または Roboflow フォーラムにお問い合わせいただくか、 専用デプロイメント.

• Deployment Manager API。 エッジデバイス管理エンドポイントでは、エンドポイントごとに明示的な制限が適用され、超過時には 429 が返されます。たとえば、デバイスログは IP アドレスあたり毎分 5 リクエスト および グローバルで毎分 50 回に制限され、テレメトリの読み取りは デバイスあたり毎分 60 リクエスト に制限されます（10 秒間に 10 リクエストのバーストを許容）。統合にポーリングを組み込む前に、正確な制限とエラー形式について Deployment Manager API を参照してください。

対象のパスについて文書化された数値がない場合は、 429 を固定の予算とみなすのではなく、バックオフすべきシグナルとして扱い、 サポートにお問い合わせください 。より高い上限が必要な場合は、

専用デプロイメントのレプリカ サイジング

次を作成する場合: 専用デプロイメント、以下を設定できます: min_replicas および max_replicas （どちらもデフォルトは 1):

• min_replicas は、稼働状態を維持するレプリカ数です。最小値を大きくすると、常時稼働容量のコストは増えますが、バースト的な負荷時のコールドスタート レイテンシを減らせます。

• max_replicas は、負荷時にデプロイメントがスケールアウトできる上限を定めます。ピーク スループットを高めるには、この値を増やしてください。

安定したトラフィックの場合、 min_replicas および max_replicas の 1 が最も簡単な出発点です。単一のレプリカがピーク負荷に追いつけない場合は max_replicas を増やし、アイドル状態の後の最初のリクエストが遅すぎる場合は min_replicas を増やしてください。

自動一時停止との相互作用

専用デプロイメント 非アクティブ状態が一定期間続くと自動的に一時停止します — dev-cpu および dev-gpu タイプでは 1 時間に固定されています — API キーを使用してリクエストを送信すると再開します。一時停止中のデプロイメントはレプリカを提供していないため、それを再開するリクエストでは再開レイテンシが発生します。

• 次の 永続的な prod-cpu / prod-gpu タイプは、常に準備ができている必要がある本番トラフィックに使用してください。

• 一時的な dev-cpu / dev-gpu タイプはテストとプロトタイピング用に限定してください。これらは数時間後に自動的に削除されます。

• 稼働時間ではなくリクエスト数に基づく請求、またはカスタムの一時停止／レプリカ ポリシーが必要な場合は、 営業担当者にお問い合わせください.

本番稼働前に

• 再試行はすべての送信呼び出しを対象とし、再試行するのは 429 および 5xx のみで、バックオフを使用します。

• クライアント タイムアウトは、サーバーレスのコールドスタートを吸収できるほど十分に長く設定されています。

• 画像は、20 MB のアップロード上限内に収まるよう縮小されています。

• API キーには、必要最小限の スコープ が使用され、ハードコードではなくシークレットとして保存されています。

• 専用デプロイメントでは、 min_replicas / max_replicas は負荷に合わせてサイズ設定されており、 prod-* タイプが常時稼働トラフィック用に選択されています。

• デプロイメントを監視しています。 モデル監視 を参照し、エラー率とレイテンシの悪化に対してアラートを設定してください。