비전 이벤트 번들 쓰기

비전 이벤트를 로컬 디렉터리에 자체 포함된 tarball 번들로 기록합니다.

비전 이벤트를 Roboflow Vision Events API로 전송하는 대신, 로컬 파일 시스템에 자족형 tarball 번들로 직렬화합니다. 인퍼런스 서버가 클라우드로 라우팅되지 않는 에어갭 및 OT 네트워크 배포용으로 설계되었습니다: 고객의 파일 이동 서비스가 번들을 네트워크 밖으로 전송하고, 업로더는 나중에 각 번들을 Roboflow의 POST /vision-events/bundle 엔드포인트로 압축을 풀지 않고 전송합니다.

번들 형식(버전 1)

이벤트당 하나의 tarball이 다음 위치에 작성됩니다: target_directory:

event_<UTC timestamp>_<eventId>.tar.gz
├── payload.json               # 이벤트 페이로드(버전이 지정된 계약, camelCase)
└── images/<file_id>.jpg       # 이미지 멤버, file_id는 uuid4입니다

payload.json 다음과 같은 구조를 가집니다: POST /vision-events 요청 본문과 동일하지만, 다음 차이점이 있습니다:

• bundleFormatVersion 번들 계약 버전을 식별합니다(현재 1)

• images[].file / images[].inputFile tar 멤버 경로를 참조하며, 대신 sourceId / inputSourceId (클라우드가 수집 시점에 이를 소스 ID로 해석합니다)

• useCaseId 선택 사항인 사용 사례 필드가 이 블록에 설정된 경우에만 존재합니다. 에어갭 배포에서는 일반적으로 이를 설정하지 않아 OT 네트워크에 클라우드 식별자가 저장되지 않으며, 업로더가 대신 이를 다음을 통해 제공합니다: useCaseId 쿼리 파라미터

미디어 멤버는 타입 이름의 디렉터리 아래에 있습니다(images/ 현재 기준); 향후 미디어 유형은 형제 디렉터리를 사용하므로, 소비자는 알 수 없는 최상위 디렉터리를 무시해야 합니다.

원자적 쓰기

번들은 대상 디렉터리의 점(.)으로 시작하는 임시 파일에 기록되고, fsync된 후 최종 event_*.tar.gz 이름으로 원자적으로 이름이 바뀝니다(이름 변경 후 디렉터리에 대해 fsync가 수행됩니다). 다음과 일치하는 파일 이동 서비스는 event_*.tar.gz (또는 dotfile을 건너뜀)는 부분적으로 기록된 번들을 절대 가져갈 수 없습니다.

속도 제한

비디오 워크플로는 초당 여러 번 실행될 수 있으며, 기본적으로는 프레임마다 번들을 작성하게 됩니다. 이 블록은 연속 이벤트 사이에 쿨다운을 적용합니다: 기본적으로 초당 최대 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: 경고 유형, 심각도(낮음/중간/높음), 설명을 포함한 안전 위반

• custom: 자유 형식 값 문자열을 사용하는 사용자 정의 이벤트

• operator_feedback: 이전 이벤트에 대한 작업자 검토/수정(정확함/부정확함/판단 불가)

유형 식별자

단계에서 다음 식별자를 사용하세요 "type" 필드: roboflow_core/vision_event_bundle@v1 워크플로에 이 블록을 단계로 추가하려면.

속성

이름	유형	설명	참조
name	str	이 단계의 고유 식별자를 입력하세요..	❌
target_directory	str	이벤트 번들이 작성될 디렉터리 경로입니다. 존재하지 않으면 자동으로 생성됩니다. WORKFLOW_BLOCKS_WRITE_DIRECTORY가 설정된 경우, 이 경로는 허용된 디렉터리의 하위 디렉터리여야 합니다..	✅
event_type	str	생성할 비전 이벤트의 유형입니다..	✅
solution	str	번들에 포함할 선택적 사용 사례로 useCaseId. 에어갭 배포에서는 설정하지 않아 번들에 클라우드 식별자가 저장되지 않도록 하세요 - 대신 업로더가 업로드 시 사용 사례를 제공합니다. A useCaseId 수집 엔드포인트로 전달되는 쿼리 파라미터가 항상 번들된 값을 덮어씁니다..	✅
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	검토 중인 이벤트의 이벤트 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 런타임에서 원격 단계 실행을 사용하면 각 요청이 새 워커를 받으므로 쿨다운이 제한을 적용하지 않습니다. 쿨다운은 InferencePipeline 내부의 로컬 단계 실행에서만 문서화된 대로 동작합니다.

소프트 - 런타임 dedicated_deployment : 번들은 배포의 볼륨에 유지되지만 Roboflow API를 통해서는 검색할 수 없습니다. 이 블록은 파일 이동 프로세스가 있는 자체 호스팅 배포용입니다.

소프트 - 런타임 hosted_serverless : 컨테이너 디스크는 휘발성이므로 워커가 축소될 때 번들이 사라집니다. 워크플로 요청을 처리하는 복제본이 두 개 이상이면 결과는 비결정적입니다.

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 종류에 따라 다릅니다. 어떤 바인딩 종류가 비전 이벤트 번들 쓰기 버전의 v1 을 지원하는지 확인하세요.

입력 및 출력 바인딩

• 입력

  • target_directory (string): 이벤트 번들이 작성될 디렉터리 경로입니다. 존재하지 않으면 자동으로 생성됩니다. WORKFLOW_BLOCKS_WRITE_DIRECTORY가 설정된 경우, 이 경로는 허용된 디렉터리의 하위 디렉터리여야 합니다..

  • input_image (image): 원본 입력 이미지입니다. 번들에 저장되며 탐지 주석의 기준 이미지로 사용됩니다..

  • output_image (image): 선택적 출력/시각화 이미지(예: 시각화 블록에서 생성). 이벤트가 수집되면 기본 이미지로 표시됩니다..

  • predictions (Union[classification_prediction, instance_segmentation_prediction, keypoint_detection_prediction, object_detection_prediction]): 입력 이미지에 탐지 주석으로 포함할 선택적 모델 예측입니다. 객체 탐지, 인스턴스 세그멘테이션, 키포인트 탐지, 분류 예측을 지원합니다..

  • event_type (string): 생성할 비전 이벤트의 유형입니다..

  • solution (Union[roboflow_solution, string]): 번들에 포함할 선택적 사용 사례로 useCaseId. 에어갭 배포에서는 설정하지 않아 번들에 클라우드 식별자가 저장되지 않도록 하세요 - 대신 업로더가 업로드 시 사용 사례를 제공합니다. A useCaseId 수집 엔드포인트로 전달되는 쿼리 파라미터가 항상 번들된 값을 덮어씁니다..

  • external_id (string): 다른 시스템과의 연계를 위한 외부 식별자(최대 1000자)..

  • qc_result (string): 품질 검사 결과: 합격 또는 불합격..

  • location (string): 재고 수량 집계를 위한 위치 식별자..

  • item_count (integer): 집계된 품목 수..

  • item_type (string): 집계 중인 품목의 유형..

  • alert_type (string): 경고 유형 식별자(예: no_hardhat, spill_detected)..

  • severity (string): 안전 경고의 심각도 수준..

  • alert_description (string): 안전 경고에 대한 설명..

  • custom_value (string): 사용자 정의 이벤트를 위한 임의 값..

  • related_event_id (string): 검토 중인 이벤트의 이벤트 ID..

  • feedback (string): 관련 이벤트에 대한 작업자 피드백..

  • custom_metadata (*): 이벤트에 첨부할 평면 키-값 메타데이터입니다. 키는 패턴 [a-zA-Z0-9_ -]+와 일치해야 합니다(최대 100자). 문자열 값은 최대 1000자입니다..

  • fire_and_forget (boolean): True이면 번들이 비동기적으로 작성되고 워크플로는 기다리지 않고 계속 진행합니다. False이면 블록이 쓰기 완료를 기다립니다..

  • disable_sink (boolean): True이면 블록이 비활성화되고 번들이 작성되지 않습니다..

  • cooldown_seconds (Union[float, integer]): 이 블록이 작성하는 연속 이벤트 번들 사이의 최소 초 수입니다. 쿨다운 기간에 트리거된 이벤트는 버려지며 throttling_status 출력은 True로 설정됩니다. 기본값은 1초로, 고빈도 비디오 워크플로가 프레임마다 번들을 작성하지 않도록 합니다. 의도적으로 버스트가 많은 사용 사례에서 속도 제한을 비활성화하려면 0으로 설정하세요..

• 출력

  • error_status (boolean): 불리언 플래그.

  • throttling_status (boolean): 불리언 플래그.

  • event_id (string): 문자열 값.

  • bundle_path (string): 문자열 값.

  • 메시지 (string): 문자열 값.

예시 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": "B 구역에서 hardhat 없이 작업자가 감지됨",
	    "custom_value": "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
	}