> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/workflows/ja/burokku/blocks/data-storage/vision-event-bundle.md). # Vision Event Bundle の書き込み Roboflow Vision Events API に送信する代わりに、ビジョンイベントをローカルファイルシステム上の自己完結型 tarball バンドルとしてシリアライズします。推論サーバーがクラウドへ到達できないエアギャップ環境や OT ネットワーク向けに設計されています。顧客側の file-mover サービスがバンドルをネットワーク外へ搬送し、その後アップローダーが各バンドルを Roboflow の `POST /vision-events/bundle` エンドポイントへ、展開せずに送信します。 ## バンドル形式（バージョン1） イベントごとに 1 つの tarball を書き込みます。 `target_directory`: ``` event__.tar.gz ├── payload.json # イベントのペイロード（バージョン管理された契約、camelCase） └── images/.jpg # 画像メンバー。file_id は uuid4 です ``` `payload.json` 次と同じ構造を持ちます `POST /vision-events` リクエスト本文。ただし、次の違いがあります: * `bundleFormatVersion` バンドル契約のバージョンを識別します（現在は `1`) * `images[].file` / `images[].inputFile` 次の代わりに tar メンバーのパスを参照します `sourceId` / `inputSourceId` （クラウドは取り込み時にそれらを source id に解決します） * `useCaseId` は、オプションの **Use Case** フィールドがこのブロックに設定されている場合にのみ存在します。エアギャップ環境では通常これを未設定のままにして、OT ネットワーク内にクラウド識別子が保存されないようにし、アップローダーが代わりに `useCaseId` query parameter として指定します メディアメンバーは、型名付きディレクトリ（`images/` 現在のところ）に配置されます。将来のメディアタイプは兄弟ディレクトリを使用するため、利用側は未知のトップレベルディレクトリを無視してください。 ## アトミック書き込み バンドルは target ディレクトリ内のドットプレフィックス付き一時ファイルに書き込まれ、fsync され、最終的な `event_*.tar.gz` という名前にアトミックにリネームされます（リネーム後にディレクトリが fsync されます）。 `event_*.tar.gz` （または dotfile をスキップする）は、書き込み途中のバンドルを取得することは決してできません。 ## レート制限 ビデオワークフローは 1 秒あたり何度も実行される可能性があり、デフォルトではフレームごとに 1 つのバンドルを書き込むことになります。このブロックは連続するイベント間にクールダウンを課します。デフォルトでは 1 秒あたり最大 1 件のイベントだけが書き込まれます。クールダウン期間中にトリガーされたイベントは破棄され、 `throttling_status` の出力は `True`に設定されます。 `cooldown_seconds` を要件に応じて調整するか、 `0` に設定してレート制限を完全に無効にします。 ## 要件 **ローカルファイルシステムアクセス**: このブロックにはローカルファイルシステムへの書き込みアクセスが必要で、セルフホスト型 `推論`向けです。ファイルシステムアクセスは環境変数で制御できます: * 次を設定します `ALLOW_WORKFLOW_BLOCKS_ACCESSING_LOCAL_STORAGE=False` ことでブロックを無効にします（エラーが発生します） * 次を設定します `WORKFLOW_BLOCKS_WRITE_DIRECTORY` を絶対パスに設定すると、書き込み先を特定のディレクトリとそのサブディレクトリのみに制限できます Roboflow API キーは不要です。ブロックはネットワークと通信しません。 ## イベントタイプ * **quality\_check**: 製造/検査 QA。合否結果と任意の信頼度を含みます * **inventory\_count**: 在庫追跡。場所、アイテム数、アイテム種別を含みます * **safety\_alert**: 安全違反。警告タイプ、重大度（low/medium/high）、説明を含みます * **custom**: ユーザー定義イベント。自由形式の値文字列を含みます * **operator\_feedback**: 以前のイベントに対するオペレーターによる確認/修正（correct/incorrect/inconclusive） ### タイプ識別子 ステップで次の識別子を使用してください `"type"` フィールド: `roboflow_core/vision_event_bundle@v1` ワークフローのステップとしてこのブロックを追加します。 ### プロパティ | **名前** | **型** | **説明** | 参照 | | ------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | | `name` | `str` | このステップの一意の識別子を入力してください。 | ❌ | | `target_directory` | `str` | イベントバンドルが書き込まれるディレクトリパスです。存在しない場合は自動的に作成されます。WORKFLOW\_BLOCKS\_WRITE\_DIRECTORY が設定されている場合、このパスは許可されたディレクトリのサブディレクトリでなければなりません。 | ✅ | | `event_type` | `str` | 作成するビジョンイベントの種類。 | ✅ | | `solution` | `str` | バンドルに組み込む任意のユースケースとして `useCaseId`。エアギャップ環境では未設定のままにしておき、クラウド識別子がバンドルに保存されないようにしてください。アップローダーが代わりにアップロード時にユースケースを指定します。A `useCaseId` ingest エンドポイントに渡される query parameter は、常にバンドル済みの値を上書きします。 | ✅ | | `external_id` | `str` | 他のシステムとの相関付けのための外部識別子（最大 1000 文字）。 | ✅ | | `qc_result` | `str` | 品質検査結果: 合格または不合格。 | ✅ | | `location` | `str` | 在庫カウントのための場所識別子。 | ✅ | | `item_count` | `int` | カウントされたアイテム数。 | ✅ | | `item_type` | `str` | カウント対象のアイテムの種類。 | ✅ | | `alert_type` | `str` | 警告タイプ識別子（例: no\_hardhat, spill\_detected）。 | ✅ | | `severity` | `str` | 安全アラートの重大度レベル。 | ✅ | | `alert_description` | `str` | 安全アラートの説明。 | ✅ | | `custom_value` | `str` | カスタムイベント用の任意の値。 | ✅ | | `related_event_id` | `str` | レビュー対象のイベントの event ID。 | ✅ | | `feedback` | `str` | 関連イベントに対するオペレーターのフィードバック。 | ✅ | | `custom_metadata` | `Dict[str, Union[bool, float, int, str]]` | イベントに付与するフラットなキー/値メタデータ。キーはパターン \[a-zA-Z0-9\_ -]+（最大 100 文字）に一致する必要があります。文字列値は最大 1000 文字です。 | ✅ | | `fire_and_forget` | `bool` | True の場合、バンドルは非同期に書き込まれ、ワークフローは待機せずに継続します。False の場合、ブロックは書き込み完了まで待機します。 | ✅ | | `disable_sink` | `bool` | True の場合、ブロックは無効化され、バンドルは書き込まれません。 | ✅ | | `cooldown_seconds` | `Union[float, int]` | このブロックが書き込む連続するイベントバンドル間の最小秒数。クールダウン期間中にトリガーされたイベントは破棄され、 `throttling_status` の出力は True に設定されます。デフォルトは 1 秒で、高頻度のビデオワークフローがフレームごとにバンドルを書き込まないようにします。意図的にバーストの多いユースケースでは 0 に設定してレート制限を無効にします。 | ✅ | この **参照** 列は、動的値を使ってプロパティをパラメータ化できることを示します `ワークフロー` ランタイムです。詳細は *バインディング* をご覧ください。 ### ランタイム互換性 `ソフト` - ランタイム `hosted_serverless`, `dedicated_deployment`；実行 `リモート` 冷却/レート制限タイマーはプロセスメモリに保存されます。ステートレスまたはマルチレプリカの HTTP ランタイムでリモートステップ実行を行うと、各リクエストごとに新しいワーカーが割り当てられるため、cooldown はスロットリングしません。cooldown が文書どおりに動作するのは、InferencePipeline 内でローカルステップ実行する場合のみです。 `ソフト` - ランタイム `dedicated_deployment` バンドルはデプロイメントのボリュームに永続化されますが、Roboflow API から取得することはできません。このブロックは、file-mover プロセスを伴うセルフホスト型デプロイメント向けです。 `ソフト` - ランタイム `hosted_serverless` コンテナのディスクは一時的なため、ワーカーがスケールダウンするとバンドルは失われます。ワークフロー要求を消費するレプリカが複数ある場合、結果は非決定的になります。 ### 入出力バインディング 利用可能な接続は、その binding kind に依存します。どの binding kind が `Vision Event Bundle を書き込む` バージョン `v1` を持ちます。
入出力バインディング * input * `target_directory` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): イベントバンドルが書き込まれるディレクトリパス。存在しない場合は自動的に作成されます。WORKFLOW\_BLOCKS\_WRITE\_DIRECTORY が設定されている場合、このパスは許可されたディレクトリのサブディレクトリでなければなりません。 * `input_image` ([*`image`*](/workflows/ja/gaido/developer-guide/kinds/image.md)): 元の入力画像です。バンドルに保存され、検出アノテーションのベース画像として使用されます。 * `output_image` ([*`image`*](/workflows/ja/gaido/developer-guide/kinds/image.md)): 任意の出力/可視化画像（例: 可視化ブロックの出力）。イベントが取り込まれた後は、主要画像として表示されます。 * `predictions` (*Union\[*[*`classification_prediction`*](/workflows/ja/gaido/developer-guide/kinds/classification-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*,* [*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*]*): 入力画像に検出アノテーションとして含める任意のモデル予測です。物体検出、インスタンスセグメンテーション、キーポイント検出、分類の予測をサポートします。 * `event_type` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): 作成するビジョンイベントの種類。 * `solution` (*Union\[*[*`roboflow_solution`*](/workflows/ja/gaido/developer-guide/kinds/roboflow-solution.md)*,* [*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)*]*): バンドルに組み込む任意のユースケースとして `useCaseId`。エアギャップ環境では未設定のままにしておき、クラウド識別子がバンドルに保存されないようにしてください。アップローダーが代わりにアップロード時にユースケースを指定します。A `useCaseId` ingest エンドポイントに渡される query parameter は、常にバンドル済みの値を上書きします。 * `external_id` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): 他のシステムとの相関付けのための外部識別子（最大 1000 文字）。 * `qc_result` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): 品質検査結果: 合格または不合格。 * `location` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): 在庫カウントのための場所識別子。 * `item_count` ([*`integer`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)): カウントされたアイテム数。 * `item_type` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): カウント対象のアイテムの種類。 * `alert_type` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): 警告タイプ識別子（例: no\_hardhat, spill\_detected）。 * `severity` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): 安全アラートの重大度レベル。 * `alert_description` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): 安全アラートの説明。 * `custom_value` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): カスタムイベント用の任意の値。 * `related_event_id` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): レビュー対象のイベントの event ID。 * `feedback` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)): 関連イベントに対するオペレーターのフィードバック。 * `custom_metadata` ([*`*`*](/workflows/ja/gaido/developer-guide/kinds/wildcard.md)): イベントに付与するフラットなキー/値メタデータ。キーはパターン \[a-zA-Z0-9\_ -]+（最大 100 文字）に一致する必要があります。文字列値は最大 1000 文字です。 * `fire_and_forget` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): True の場合、バンドルは非同期に書き込まれ、ワークフローは待機せずに継続します。False の場合、ブロックは書き込み完了まで待機します。 * `disable_sink` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): True の場合、ブロックは無効化され、バンドルは書き込まれません。 * `cooldown_seconds` (*Union\[*[*`float`*](/workflows/ja/gaido/developer-guide/kinds/float.md)*,* [*`integer`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)*]*): このブロックが書き込む連続するイベントバンドル間の最小秒数。クールダウン期間中にトリガーされたイベントは破棄され、 `throttling_status` の出力は True に設定されます。デフォルトは 1 秒で、高頻度のビデオワークフローがフレームごとにバンドルを書き込まないようにします。意図的にバーストの多いユースケースでは 0 に設定してレート制限を無効にします。 * output * `error_status` ([`boolean`](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): ブールフラグ。 * `throttling_status` ([`boolean`](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): ブールフラグ。 * `event_id` ([`string`](/workflows/ja/gaido/developer-guide/kinds/string.md)): 文字列値。 * `bundle_path` ([`string`](/workflows/ja/gaido/developer-guide/kinds/string.md)): 文字列値。 * `message` ([`string`](/workflows/ja/gaido/developer-guide/kinds/string.md)): 文字列値。
JSON 定義の例 ```json { "name": "", "type": "roboflow_core/vision_event_bundle@v1", "target_directory": "/data/vision-event-bundles", "input_image": "$inputs.image", "output_image": "$steps.visualization.image", "predictions": "$steps.object_detection_model.predictions", "event_type": "quality_check", "solution": "my-use-case", "external_id": "batch-2025-001", "qc_result": "pass", "location": "warehouse-A", "item_count": 42, "item_type": "widget", "alert_type": "no_hardhat", "severity": "high", "alert_description": "Worker detected without hardhat in zone B", "custom_value": "anomaly detected at 14:32", "related_event_id": "evt_abc123", "feedback": "correct", "custom_metadata": { "camera_id": "cam_01", "location": "$inputs.location" }, "fire_and_forget": true, "disable_sink": false, "cooldown_seconds": 1 } ```