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

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

विजन इवेंट्स को 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 में है।

Input और output bindings

• input

  • target_directory (string): वह directory path जहाँ event bundles लिखे जाएंगे। यदि यह मौजूद नहीं है तो स्वचालित रूप से बनाया जाएगा। यदि WORKFLOW_BLOCKS_WRITE_DIRECTORY सेट है, तो यह path अनुमत directory की एक subdirectory होना चाहिए..

  • input_image (image): मूल input image। bundle में संग्रहीत और detection annotations के लिए base image के रूप में उपयोग की जाती है..

  • output_image (image): एक वैकल्पिक output/visualized image (जैसे किसी visualization block से)। event ingest होने के बाद प्राथमिक image के रूप में प्रदर्शित होती है..

  • predictions (Union[classification_prediction, instance_segmentation_prediction, keypoint_detection_prediction, object_detection_prediction]): input image पर detection annotations के रूप में शामिल करने के लिए वैकल्पिक model predictions। object detection, instance segmentation, keypoint detection, और classification predictions का समर्थन करता है..

  • event_type (string): बनाने वाले vision event का प्रकार..

  • solution (Union[roboflow_solution, string]): वैकल्पिक 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): अन्य प्रणालियों के साथ correlation के लिए बाहरी पहचानकर्ता (अधिकतम 1000 वर्ण)..

  • qc_result (string): Quality check परिणाम: pass या fail..

  • location (string): inventory count के लिए location identifier..

  • item_count (integer): गिने गए items की संख्या..

  • item_type (string): गिने जा रहे item का प्रकार..

  • alert_type (string): Alert type identifier (जैसे no_hardhat, spill_detected)..

  • severity (string): सुरक्षा alert के लिए severity स्तर..

  • alert_description (string): सुरक्षा alert का विवरण..

  • custom_value (string): custom events के लिए मनमाना मान..

  • related_event_id (string): समीक्षित किए जा रहे event का event ID..

  • feedback (string): संबंधित event पर operator feedback..

  • custom_metadata (*): event में जोड़ने के लिए flat key-value metadata। Keys को pattern [a-zA-Z0-9_ -]+ (अधिकतम 100 वर्ण) से मेल खाना चाहिए। String values अधिकतम 1000 वर्ण..

  • fire_and_forget (boolean): यदि True है, तो bundle asynchronous रूप से लिखा जाता है और workflow बिना रुके जारी रहता है। यदि False है, तो block write पूरा होने की प्रतीक्षा करता है..

  • disable_sink (boolean): यदि True है, तो block निष्क्रिय है और कोई bundle नहीं लिखा जाता..

  • cooldown_seconds (Union[float, integer]): इस 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): Boolean flag.

  • throttling_status (boolean): Boolean flag.

  • event_id (string): String मान.

  • bundle_path (string): String मान.

  • message (string): String मान.

उदाहरण 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
	}