> 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/hi/blocks/blocks/data-storage/vision-event-bundle.md).

# विज़न इवेंट बंडल लिखें

विज़न इवेंट्स को स्वयं-निहित tarball बंडलों के रूप में स्थानीय डायरेक्टरी में लिखें।

विजन इवेंट्स को Roboflow Vision Events API पर भेजने के बजाय स्थानीय फ़ाइलसिस्टम पर स्वयं-निहित tarball बंडलों के रूप में सीरियलाइज़ करें। यह एयर-गैप्ड और OT-नेटवर्क परिनियोजनों के लिए डिज़ाइन किया गया है, जहाँ inference server के पास क्लाउड तक कोई मार्ग नहीं होता: एक ग्राहक file-mover सेवा बंडलों को नेटवर्क के बाहर ले जाती है, और बाद में एक uploader प्रत्येक बंडल को Roboflow के `POST /vision-events/bundle` endpoint पर बिना उसे अनपैक किए।

## बंडल फ़ॉर्मैट (संस्करण 1)

प्रत्येक इवेंट के लिए एक tarball, लिखा जाता है `target_directory`:

```
event_<UTC timestamp>_<eventId>.tar.gz
├── payload.json               # इवेंट payload (versioned contract, camelCase)
└── images/<file_id>.jpg       # image members, file_id एक uuid4 है
```

`payload.json` का आकार समान है `POST /vision-events` request body से, इन अंतरों के साथ:

* `bundleFormatVersion` बंडल contract version की पहचान करता है (वर्तमान में `1`)
* `images[].file` / `images[].inputFile` के बजाय संदर्भ tar सदस्य पथों का उपयोग करें `sourceId` / `inputSourceId` (cloud इन्हें ingest समय source ids में resolve करता है)
* `useCaseId` केवल तब मौजूद होता है जब वैकल्पिक **Use Case** इस block पर field सेट हो; air-gapped परिनियोजन आमतौर पर इसे unset छोड़ते हैं ताकि OT नेटवर्क में कोई cloud identifiers संग्रहीत न हों, और uploader इसे `useCaseId` query parameter के माध्यम से इसके बजाय प्रदान करता है

Media members type-नामित directories के अंतर्गत रहते हैं (`images/` अभी के लिए); भविष्य के media types sibling directories का उपयोग करेंगे, इसलिए consumers को unknown top-level directories को ignore करना चाहिए।

## Atomic Writes

बंडल target directory में dot-prefixed temporary file पर लिखे जाते हैं, fsync किए जाते हैं, और atomically उनके अंतिम `event_*.tar.gz` नाम पर rename किए जाते हैं (rename के बाद directory fsync की जाती है)। एक file-mover service जो `event_*.tar.gz` से मेल खाती है (या dotfiles को skip करती है) कभी भी partially written bundle नहीं पकड़ सकती।

## Rate Limiting

वीडियो workflows प्रति सेकंड कई बार चल सकते हैं, जिससे डिफ़ॉल्ट रूप से हर frame के लिए एक bundle लिखा जाएगा। block लगातार events के बीच cooldown लागू करता है: डिफ़ॉल्ट रूप से प्रति सेकंड अधिकतम एक event लिखा जाता है। cooldown अवधि के दौरान trigger हुए events drop कर दिए जाते हैं और `throttling_status` output को `True`पर सेट किया जाता है। `cooldown_seconds` को अपनी आवश्यकताओं के अनुसार समायोजित करें, या इसे `0` पर सेट करें ताकि rate limiting पूरी तरह निष्क्रिय हो जाए।

## आवश्यकताएँ

**Local Filesystem Access**: इस block को स्थानीय फ़ाइलसिस्टम पर write access की आवश्यकता होती है और यह self-hosted `inference`के लिए अभिप्रेत है। फ़ाइलसिस्टम access को environment variables के माध्यम से नियंत्रित किया जा सकता है:

* सेट करें `ALLOW_WORKFLOW_BLOCKS_ACCESSING_LOCAL_STORAGE=False` block को disable करने के लिए (यह एक error उठाएगा)
* सेट करें `WORKFLOW_BLOCKS_WRITE_DIRECTORY` को एक absolute path पर सेट करें ताकि writes केवल एक विशिष्ट directory और उसकी उपdirectories तक सीमित रहें

कोई Roboflow API key आवश्यक नहीं है: block कभी भी नेटवर्क से बात नहीं करता।

## Event Types

* **quality\_check**: निर्माण/निरीक्षण QA, pass/fail परिणाम और वैकल्पिक confidence के साथ
* **inventory\_count**: स्थान, item count, और item type के साथ inventory tracking
* **safety\_alert**: सुरक्षा उल्लंघन, alert type, severity (low/medium/high), और विवरण के साथ
* **custom**: उपयोगकर्ता-परिभाषित events, मुक्त-रूप value string के साथ
* **operator\_feedback**: पिछले events की operator समीक्षा/सुधार (correct/incorrect/inconclusive)

### प्रकार पहचानकर्ता

step में निम्नलिखित पहचानकर्ता का उपयोग करें `"type"` field: `roboflow_core/vision_event_bundle@v1` workflow में block को step के रूप में जोड़ने के लिए।

### गुण

| **नाम**             | **प्रकार**                                | **विवरण**                                                                                                                                                                                                                                                                                                                                                                                  | Refs |
| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| `name`              | `str`                                     | इस step के लिए एक unique identifier दर्ज करें..                                                                                                                                                                                                                                                                                                                                            | ❌    |
| `target_directory`  | `str`                                     | वह directory path जहाँ event bundles लिखे जाएंगे। यदि यह मौजूद नहीं है तो स्वचालित रूप से बनाया जाएगा। यदि WORKFLOW\_BLOCKS\_WRITE\_DIRECTORY सेट है, तो यह path अनुमत directory की एक subdirectory होना चाहिए..                                                                                                                                                                           | ✅    |
| `event_type`        | `str`                                     | बनाए जाने वाले vision event का प्रकार..                                                                                                                                                                                                                                                                                                                                                    | ✅    |
| `solution`          | `str`                                     | वैकल्पिक use case जिसे bundle में `useCaseId`के रूप में शामिल किया जाए। air-gapped परिनियोजनों में इसे unset छोड़ें ताकि bundle में कोई cloud identifiers संग्रहीत न हों - uploader upload समय पर use case प्रदान करता है। ingest endpoint पर भेजा गया एक `useCaseId` query parameter हमेशा bundled value को override करता है..                                                            | ✅    |
| `external_id`       | `str`                                     | अन्य प्रणालियों के साथ correlation के लिए बाहरी पहचानकर्ता (अधिकतम 1000 वर्ण)..                                                                                                                                                                                                                                                                                                            | ✅    |
| `qc_result`         | `str`                                     | Quality check परिणाम: pass या fail..                                                                                                                                                                                                                                                                                                                                                       | ✅    |
| `location`          | `str`                                     | inventory count के लिए location identifier..                                                                                                                                                                                                                                                                                                                                               | ✅    |
| `item_count`        | `int`                                     | गिने गए items की संख्या..                                                                                                                                                                                                                                                                                                                                                                  | ✅    |
| `item_type`         | `str`                                     | गिने जा रहे item का प्रकार..                                                                                                                                                                                                                                                                                                                                                               | ✅    |
| `alert_type`        | `str`                                     | Alert type identifier (जैसे no\_hardhat, spill\_detected)..                                                                                                                                                                                                                                                                                                                                | ✅    |
| `severity`          | `str`                                     | सुरक्षा alert के लिए severity स्तर..                                                                                                                                                                                                                                                                                                                                                       | ✅    |
| `alert_description` | `str`                                     | सुरक्षा alert का विवरण..                                                                                                                                                                                                                                                                                                                                                                   | ✅    |
| `custom_value`      | `str`                                     | custom events के लिए मनमाना मान..                                                                                                                                                                                                                                                                                                                                                          | ✅    |
| `related_event_id`  | `str`                                     | समीक्षित किए जा रहे event का event ID..                                                                                                                                                                                                                                                                                                                                                    | ✅    |
| `feedback`          | `str`                                     | संबंधित event पर operator feedback..                                                                                                                                                                                                                                                                                                                                                       | ✅    |
| `custom_metadata`   | `Dict[str, Union[bool, float, int, str]]` | event में जोड़ने के लिए flat key-value metadata। Keys को pattern \[a-zA-Z0-9\_ -]+ (अधिकतम 100 वर्ण) से मेल खाना चाहिए। String values अधिकतम 1000 वर्ण..                                                                                                                                                                                                                                   | ✅    |
| `fire_and_forget`   | `bool`                                    | यदि True है, तो bundle asynchronous रूप से लिखा जाता है और workflow बिना रुके जारी रहता है। यदि False है, तो block write पूरा होने की प्रतीक्षा करता है..                                                                                                                                                                                                                                  | ✅    |
| `disable_sink`      | `bool`                                    | यदि True है, तो block निष्क्रिय है और कोई bundle नहीं लिखा जाता..                                                                                                                                                                                                                                                                                                                          | ✅    |
| `cooldown_seconds`  | `Union[float, int]`                       | इस block द्वारा लिखे गए लगातार event bundles के बीच सेकंडों की न्यूनतम संख्या। cooldown अवधि के दौरान trigger हुए events drop कर दिए जाते हैं और `throttling_status` output को True पर सेट किया जाता है। उच्च-आवृत्ति वीडियो workflows प्रति frame एक bundle न लिखें, इसके लिए डिफ़ॉल्ट 1 सेकंड है। जानबूझकर bursty use cases के लिए rate limiting निष्क्रिय करने हेतु इसे 0 पर सेट करें.. | ✅    |

The **Refs** column property को dynamic values से parametrise करने की संभावना को चिह्नित करती है जो `workflow` runtime में उपलब्ध हैं। अधिक जानकारी के लिए देखें *Bindings* .

### रनटाइम संगतता

`soft` - runtime `hosted_serverless`, `dedicated_deployment`; निष्पादन `remote` : Cooldown / rate-limit timer process memory में संग्रहीत होता है। stateless या multi-replica HTTP runtimes पर remote step execution के साथ प्रत्येक request को एक नया worker मिलता है, इसलिए cooldown throttle नहीं करता। Cooldown केवल तब दस्तावेज़ के अनुसार व्यवहार करता है जब InferencePipeline के भीतर local step execution हो।

`soft` - runtime `dedicated_deployment` : Bundles deployment के volume पर persisted होते हैं, लेकिन Roboflow API के माध्यम से पुनर्प्राप्त नहीं किए जा सकते; यह block file-mover प्रक्रिया वाले self-hosted deployments के लिए अभिप्रेत है।

`soft` - runtime `hosted_serverless` : Container disk ephemeral होता है, इसलिए worker के scale down होने पर bundles खो जाते हैं; यदि workflow requests consume करने वाले एक से अधिक replicas हैं, तो परिणाम non-deterministic होगा।

### Input and Output Bindings

उपलब्ध connections इसके binding kinds पर निर्भर करते हैं। देखें कि binding kinds क्या हैं `Write Vision Event Bundle` संस्करण `v1` में है।

<details>

<summary>Input और output bindings</summary>

* input
  * `target_directory` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): वह directory path जहाँ event bundles लिखे जाएंगे। यदि यह मौजूद नहीं है तो स्वचालित रूप से बनाया जाएगा। यदि WORKFLOW\_BLOCKS\_WRITE\_DIRECTORY सेट है, तो यह path अनुमत directory की एक subdirectory होना चाहिए..
  * `input_image` ([*`image`*](/workflows/hi/developer-guide/developer-guide/kinds/image.md)): मूल input image। bundle में संग्रहीत और detection annotations के लिए base image के रूप में उपयोग की जाती है..
  * `output_image` ([*`image`*](/workflows/hi/developer-guide/developer-guide/kinds/image.md)): एक वैकल्पिक output/visualized image (जैसे किसी visualization block से)। event ingest होने के बाद प्राथमिक image के रूप में प्रदर्शित होती है..
  * `predictions` (*Union\[*[*`classification_prediction`*](/workflows/hi/developer-guide/developer-guide/kinds/classification-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/hi/developer-guide/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/hi/developer-guide/developer-guide/kinds/keypoint-detection-prediction.md)*,* [*`object_detection_prediction`*](/workflows/hi/developer-guide/developer-guide/kinds/object-detection-prediction.md)*]*): input image पर detection annotations के रूप में शामिल करने के लिए वैकल्पिक model predictions। object detection, instance segmentation, keypoint detection, और classification predictions का समर्थन करता है..
  * `event_type` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): बनाने वाले vision event का प्रकार..
  * `solution` (*Union\[*[*`roboflow_solution`*](/workflows/hi/developer-guide/developer-guide/kinds/roboflow-solution.md)*,* [*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)*]*): वैकल्पिक use case जिसे bundle में `useCaseId`के रूप में शामिल किया जाए। air-gapped परिनियोजनों में इसे unset छोड़ें ताकि bundle में कोई cloud identifiers संग्रहीत न हों - uploader upload समय पर use case प्रदान करता है। ingest endpoint पर भेजा गया एक `useCaseId` query parameter हमेशा bundled value को override करता है..
  * `external_id` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): अन्य प्रणालियों के साथ correlation के लिए बाहरी पहचानकर्ता (अधिकतम 1000 वर्ण)..
  * `qc_result` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): Quality check परिणाम: pass या fail..
  * `location` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): inventory count के लिए location identifier..
  * `item_count` ([*`integer`*](/workflows/hi/developer-guide/developer-guide/kinds/integer.md)): गिने गए items की संख्या..
  * `item_type` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): गिने जा रहे item का प्रकार..
  * `alert_type` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): Alert type identifier (जैसे no\_hardhat, spill\_detected)..
  * `severity` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): सुरक्षा alert के लिए severity स्तर..
  * `alert_description` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): सुरक्षा alert का विवरण..
  * `custom_value` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): custom events के लिए मनमाना मान..
  * `related_event_id` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): समीक्षित किए जा रहे event का event ID..
  * `feedback` ([*`string`*](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): संबंधित event पर operator feedback..
  * `custom_metadata` ([*`*`*](/workflows/hi/developer-guide/developer-guide/kinds/wildcard.md)): event में जोड़ने के लिए flat key-value metadata। Keys को pattern \[a-zA-Z0-9\_ -]+ (अधिकतम 100 वर्ण) से मेल खाना चाहिए। String values अधिकतम 1000 वर्ण..
  * `fire_and_forget` ([*`boolean`*](/workflows/hi/developer-guide/developer-guide/kinds/boolean.md)): यदि True है, तो bundle asynchronous रूप से लिखा जाता है और workflow बिना रुके जारी रहता है। यदि False है, तो block write पूरा होने की प्रतीक्षा करता है..
  * `disable_sink` ([*`boolean`*](/workflows/hi/developer-guide/developer-guide/kinds/boolean.md)): यदि True है, तो block निष्क्रिय है और कोई bundle नहीं लिखा जाता..
  * `cooldown_seconds` (*Union\[*[*`float`*](/workflows/hi/developer-guide/developer-guide/kinds/float.md)*,* [*`integer`*](/workflows/hi/developer-guide/developer-guide/kinds/integer.md)*]*): इस block द्वारा लिखे गए लगातार event bundles के बीच सेकंडों की न्यूनतम संख्या। cooldown अवधि के दौरान trigger हुए events drop कर दिए जाते हैं और `throttling_status` output को True पर सेट किया जाता है। उच्च-आवृत्ति वीडियो workflows प्रति frame एक bundle न लिखें, इसके लिए डिफ़ॉल्ट 1 सेकंड है। जानबूझकर bursty use cases के लिए rate limiting निष्क्रिय करने हेतु इसे 0 पर सेट करें..
* output
  * `error_status` ([`boolean`](/workflows/hi/developer-guide/developer-guide/kinds/boolean.md)): Boolean flag.
  * `throttling_status` ([`boolean`](/workflows/hi/developer-guide/developer-guide/kinds/boolean.md)): Boolean flag.
  * `event_id` ([`string`](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): String मान.
  * `bundle_path` ([`string`](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): String मान.
  * `message` ([`string`](/workflows/hi/developer-guide/developer-guide/kinds/string.md)): String मान.

</details>

<details>

<summary>उदाहरण JSON परिभाषा</summary>

```json
{
	    "name": "<your_step_name_here>",
	    "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": "ज़ोन B में hardhat के बिना worker पाया गया",
	    "custom_value": "14:32 पर anomaly का पता चला",
	    "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
	}
```

</details>