> 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/ko/blocks/blocks/data-storage/roboflow-vision-events.md). # Roboflow Vision 이벤트 이미지, 모델 예측, 이벤트 메타데이터를 Roboflow Vision Events API로 보내 모니터링, 품질 관리, 안전 알림, 사용자 지정 이벤트 추적을 수행합니다. ## 이 블록의 작동 방식 이 블록은 워크플로 이미지와 모델 예측을 Roboflow Vision Events API에 업로드하여, Roboflow 대시보드에서 조회, 필터링, 시각화할 수 있는 구조화된 이벤트를 생성합니다. 1. 입력 이미지 및/또는 출력 이미지(시각화)를 공개 API를 통해 Vision Events 이미지 저장소에 선택적으로 업로드합니다 2. 모델 예측(객체 탐지, 분류, 인스턴스 분할 또는 키포인트 탐지)을 Vision Events 주석 형식으로 변환하여 입력 이미지에 첨부합니다 3. 지정된 이벤트 유형, 사용 사례, 이벤트 데이터 및 사용자 지정 메타데이터로 비전 이벤트를 생성합니다 4. 기본 제공 속도 제한을 적용합니다 (`cooldown_seconds`, 기본값 1초) 따라서 고빈도 비디오 워크플로가 프레임마다 하나의 이벤트로 API를 과부하시키지 않도록 합니다 5. 논블로킹 실행을 위한 fire-and-forget 모드를 지원합니다 ## 속도 제한 비디오 워크플로는 초당 여러 번 실행될 수 있어, 기본적으로는 각 프레임마다 이벤트(및 해당 이미지)를 전송하게 됩니다. 이를 방지하기 위해 이 블록은 연속된 이벤트 사이에 쿨다운을 적용합니다: 기본적으로 초당 최대 1개의 이벤트만 전송됩니다. 쿨다운 기간에 트리거된 이벤트는 삭제되며, 그리고 `throttling_status` 출력이 다음으로 설정되고 `True`. 조정 `cooldown_seconds` 를 필요에 맞게 조정하거나, 다음으로 설정하세요: `0` 속도 제한을 완전히 비활성화합니다(예: 의도적으로 버스트가 발생하는 사용 사례). 쿨다운 타이머는 블록 인스턴스에 저장되므로, 지속적인 WebRTC 세션과 같은 장기 실행을 제한합니다. HTTP로 제공되는 워크플로(예: `/workflows/run`)는 요청마다 새 블록 인스턴스를 생성하므로, 쿨다운이 별도의 HTTP 호출 간에 제한을 걸지 않습니다. ## 배포 모드 기본적으로 이 블록은 이벤트를 다음으로 보냅니다: **Roboflow Vision Events API** (클라우드 / Serverless API)로, 이미지를 업로드하고 공개 API를 통해 이벤트를 전송합니다. 엣지 배포의 경우 다음을 활성화하세요: **로컬 이벤트 저장소에 쓰기** 대신 로컬 Event Ingestion Service로 이벤트를 전송합니다. 이 모드에서는 이미지가 요청에 직접 포함되며(업로드 단계 없음), 이벤트는 다음으로 전송됩니다: `/v2/events`. 이벤트 저장소 URL의 기본값은 `http://localhost:8001` 이며 재정의할 수 있습니다. 이 모드에서는 Roboflow API 키가 필요하지 않습니다. 로컬 서비스에 인증이 필요하면 다음을 설정하세요: `EVENT_INGESTION_API_KEY` 추론 서버의 환경 변수. ## 이벤트 유형 * **quality\_check**: 제조/검사 QA, 합격/불합격 결과 및 선택적 신뢰도 * **inventory\_count**: 위치, 품목 수, 품목 유형을 포함한 재고 추적 * **safety\_alert**: 경고 유형, 심각도(낮음/중간/높음), 설명이 포함된 안전 위반 * **custom**: 자유 형식 값 문자열을 사용하는 사용자 정의 이벤트 * **operator\_feedback**: 이전 이벤트에 대한 작업자 검토/수정(correct/incorrect/inconclusive) ## 요구 사항 기본(클라우드) 모드에서는 다음 권한을 가진 유효한 Roboflow API 키가 필요합니다: `vision-events:write` 범위가 필요하며, 환경 또는 워크플로 구성에서 설정됩니다. Roboflow API 키는 다음이 **로컬 이벤트 저장소에 쓰기** 활성화되면 Roboflow API 키가 필요하지 않습니다(위의 배포 모드 참조). ## 일반적인 사용 사례 * **품질 관리**: 이미지와 탐지 오버레이로 검사 결과를 자동으로 기록합니다 * **안전 모니터링**: 비디오 스트림에서 위반이 감지되면 안전 알림을 전송합니다 * **생산 분석**: 시각적 증거와 함께 재고 수량 및 생산 지표를 추적합니다 * **실시간 모니터링**: 실시간 비디오 처리 워크플로에서 fire-and-forget 이벤트 로깅 ### 유형 식별자 단계에서 다음 식별자를 사용하세요 `"type"` 필드: `roboflow_core/roboflow_vision_events@v1` 워크플로우에 이 블록을 단계로 추가하려면. ### 속성 | **이름** | **유형** | **설명** | 참조 | | ---------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | | `name` | `str` | 이 단계에 대한 고유 식별자를 입력하세요.. | ❌ | | `event_type` | `str` | 생성할 비전 이벤트 유형.. | ✅ | | `solution` | `str` | 이벤트를 연결할 사용 사례입니다. 이벤트는 워크스페이스 내에서 사용 사례별로 네임스페이스가 지정됩니다.. | ✅ | | `external_id` | `str` | 다른 시스템과의 연계를 위한 외부 식별자입니다(최대 1000자).. | ✅ | | `qc_result` | `str` | 품질 검사 결과: pass 또는 fail.. | ✅ | | `location` | `str` | 재고 수량 집계를 위한 위치 식별자입니다.. | ✅ | | `item_count` | `정수` | 집계된 품목 수입니다.. | ✅ | | `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]]` | 이벤트에 첨부할 평면 key-value 메타데이터입니다. 키는 \[a-zA-Z0-9\_ -]+ 패턴과 일치해야 하며(최대 100자), 문자열 값은 최대 1000자입니다.. | ✅ | | `fire_and_forget` | `bool` | True이면 이벤트가 비동기적으로 전송되고 워크플로는 기다리지 않고 계속 진행됩니다. False이면 블록이 API 응답을 기다립니다.. | ✅ | | `disable_sink` | `bool` | True이면 블록이 비활성화되고 이벤트가 전송되지 않습니다.. | ✅ | | `cooldown_seconds` | `Union[float, int]` | 이 블록이 전송하는 연속된 이벤트 사이의 최소 초 수입니다. 쿨다운 기간에 트리거된 이벤트는 삭제되며, 그리고 `throttling_status` 출력은 True로 설정됩니다. 기본값은 1초(초당 최대 1개 이벤트)이며, 고빈도 비디오 워크플로가 프레임마다 하나의 이벤트로 Vision Events API를 과부하시키지 않도록 합니다. 의도적으로 버스트가 발생하는 사용 사례에서 속도 제한을 비활성화하려면 0으로 설정하세요.. | ✅ | | `write_to_event_store` | `bool` | True이면 Roboflow Vision Events API(클라우드) 대신 로컬 Event Ingestion Service(엣지 배포)로 이벤트를 전송합니다. 이미지는 요청에 포함되며 이벤트는 다음으로 전송됩니다: `/v2/events`. 이 모드에서는 Roboflow API 키가 필요하지 않습니다.. | ✅ | | `event_store_url` | `str` | 로컬 Event Ingestion Service의 기본 URL입니다. 다음이 활성화된 경우에만 사용됩니다: `로컬 이벤트 저장소에 쓰기` 가 활성화된 경우에만 사용됩니다.. | ✅ | 이 **참조** 열은 워크플로우 런타임에서 사용 가능한 동적 값으로 속성을 매개변수화할 수 있는 가능성을 나타냅니다 `워크플로우` 런타임입니다. 자세한 내용은 *바인딩* 을 참조하세요. ### 런타임 호환성 `소프트` - 런타임 `호스팅 서버리스`, `전용 배포`; 실행 `원격` : 쿨다운/속도 제한 타이머는 프로세스 메모리에 저장됩니다. 상태 비저장 또는 다중 복제본 HTTP 런타임에서 원격 단계 실행을 사용하면 각 요청이 새 작업자를 받으므로 쿨다운이 속도를 제한하지 않습니다. 쿨다운은 지속적인 WebRTC 세션에서 로컬 단계 실행을 사용할 때만 문서화된 대로 작동합니다. ### 입력 및 출력 바인딩 사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 `Roboflow Vision 이벤트` 버전 `v1` 을 가지고 있는지.
입력 및 출력 바인딩 * 입력 * `input_image` ([*`이미지`*](/workflows/ko/developer-guide/developer-guide/kinds/image.md)): 원본 입력 이미지입니다. Vision Events API에 업로드되며 탐지 주석의 기준 이미지로 사용됩니다.. * `output_image` ([*`이미지`*](/workflows/ko/developer-guide/developer-guide/kinds/image.md)): 선택적 출력/시각화 이미지(예: 시각화 블록에서 생성된 이미지)입니다. Vision Events 대시보드에서 기본 이미지로 표시됩니다.. * `예측` (*Union\[*[*`object_detection_prediction`*](/workflows/ko/developer-guide/developer-guide/kinds/object-detection-prediction.md)*,* [*`classification_prediction`*](/workflows/ko/developer-guide/developer-guide/kinds/classification-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ko/developer-guide/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/ko/developer-guide/developer-guide/kinds/keypoint-detection-prediction.md)*]*): 입력 이미지에 탐지 주석으로 포함할 선택적 모델 예측입니다. 객체 탐지, 인스턴스 분할, 키포인트 탐지 및 분류 예측을 지원합니다.. * `event_type` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 생성할 비전 이벤트 유형입니다.. * `solution` (*Union\[*[*`roboflow_solution`*](/workflows/ko/developer-guide/developer-guide/kinds/roboflow-solution.md)*,* [*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)*]*): 이벤트를 연결할 사용 사례입니다. 이벤트는 워크스페이스 내에서 사용 사례별로 네임스페이스가 지정됩니다.. * `external_id` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 다른 시스템과의 연계를 위한 외부 식별자입니다(최대 1000자).. * `qc_result` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 품질 검사 결과: pass 또는 fail.. * `location` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 재고 수량 집계를 위한 위치 식별자입니다.. * `item_count` ([*`정수`*](/workflows/ko/developer-guide/developer-guide/kinds/integer.md)): 집계된 품목 수입니다.. * `item_type` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 집계 중인 품목 유형입니다.. * `alert_type` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 경고 유형 식별자(예: no\_hardhat, spill\_detected).. * `severity` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 안전 알림의 심각도 수준입니다.. * `alert_description` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 안전 알림의 설명입니다.. * `custom_value` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 사용자 정의 이벤트를 위한 임의의 값입니다.. * `related_event_id` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 검토 중인 이벤트의 이벤트 ID입니다.. * `feedback` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 관련 이벤트에 대한 작업자 피드백입니다.. * `custom_metadata` ([*`*`*](/workflows/ko/developer-guide/developer-guide/kinds/wildcard.md)): 이벤트에 첨부할 평면 key-value 메타데이터입니다. 키는 \[a-zA-Z0-9\_ -]+ 패턴과 일치해야 하며(최대 100자), 문자열 값은 최대 1000자입니다.. * `fire_and_forget` ([*`boolean`*](/workflows/ko/developer-guide/developer-guide/kinds/boolean.md)): True이면 이벤트가 비동기적으로 전송되고 워크플로는 기다리지 않고 계속 진행됩니다. False이면 블록이 API 응답을 기다립니다.. * `disable_sink` ([*`boolean`*](/workflows/ko/developer-guide/developer-guide/kinds/boolean.md)): True이면 블록이 비활성화되고 이벤트가 전송되지 않습니다.. * `cooldown_seconds` (*Union\[*[*`float`*](/workflows/ko/developer-guide/developer-guide/kinds/float.md)*,* [*`정수`*](/workflows/ko/developer-guide/developer-guide/kinds/integer.md)*]*): 이 블록이 전송하는 연속된 이벤트 사이의 최소 초 수입니다. 쿨다운 기간에 트리거된 이벤트는 삭제되며, 그리고 `throttling_status` 출력은 True로 설정됩니다. 기본값은 1초(초당 최대 1개 이벤트)이며, 고빈도 비디오 워크플로가 프레임마다 하나의 이벤트로 Vision Events API를 과부하시키지 않도록 합니다. 의도적으로 버스트가 발생하는 사용 사례에서 속도 제한을 비활성화하려면 0으로 설정하세요.. * `write_to_event_store` ([*`boolean`*](/workflows/ko/developer-guide/developer-guide/kinds/boolean.md)): True이면 Roboflow Vision Events API(클라우드) 대신 로컬 Event Ingestion Service(엣지 배포)로 이벤트를 전송합니다. 이미지는 요청에 포함되며 이벤트는 다음으로 전송됩니다 `/v2/events`. 이 모드에서는 Roboflow API 키가 필요하지 않습니다.. * `event_store_url` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 로컬 Event Ingestion Service의 기본 URL입니다. 다음이 활성화된 경우에만 사용됩니다 `로컬 이벤트 저장소에 쓰기` 가 활성화된 경우에만 사용됩니다.. * 출력 * `error_status` ([`boolean`](/workflows/ko/developer-guide/developer-guide/kinds/boolean.md)): 불리언 플래그. * `throttling_status` ([`boolean`](/workflows/ko/developer-guide/developer-guide/kinds/boolean.md)): 불리언 플래그. * `event_id` ([`string`](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 문자열 값. * `message` ([`string`](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 문자열 값.
예시 JSON 정의 ```json { "name": "", "type": "roboflow_core/roboflow_vision_events@v1", "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, "write_to_event_store": false, "event_store_url": "http://localhost:8001" } ```