데이터 집계기

시간 기반 통계를 생성하기 위해 워크플로 데이터를 집계합니다.

구성 가능한 시간 기반 또는 실행 기반 간격으로 워크플로 단계의 데이터를 수집하고 처리하여 통계 요약과 분석 보고서를 생성하며, 포괄적인 데이터 스트림 분석을 위해 선택적으로 UQL 기반 데이터 변환을 사용하면서 여러 집계 연산(sum, average, max, min, count, distinct values, value counts)을 지원합니다.

이 블록의 작동 방식

이 블록은 지정된 간격으로 워크플로 단계의 데이터를 수집하고 집계하여 통계 요약을 생성합니다. 대부분의 블록이 모든 입력에 대해 데이터를 출력하는 것과 달리, 이 블록은 내부 상태를 유지하고 구성된 간격에 도달했을 때만 집계 결과를 출력합니다. 이 블록은:

1. 다른 워크플로 단계로부터 데이터 입력을 받습니다( 데이터 필드 매핑으로 변수 이름을 워크플로 단계 출력에 매핑)

2. 집계 전에 데이터를 변환하기 위해 선택적으로 UQL(Query Language) 연산을 적용합니다(예: 탐지 결과에서 클래스 이름 추출, 시퀀스 길이 계산, 값 필터링 또는 변환) 를 사용하여 data_operations 각 입력 변수에 대해

3. 지정된 설정에 따라 데이터를 내부 집계 상태로 누적합니다 aggregation_mode 각 변수에 대해

4. 경과 시간 또는 실행 횟수를 추적합니다(기준: interval_unit (초, 분, 시간 또는 실행)

5. 대부분의 경우, 내부적으로 데이터를 수집하는 동안 빈 출력을 반환합니다(하위 처리 종료)

6. 간격 임계값에 도달하면(경과 시간 또는 실행 횟수 기준) 집계 통계를 계산하고 출력합니다

7. 집계 결과를 출력한 후 내부 상태를 비우고 다음 간격에 대한 데이터 수집을 시작합니다

8. 출력 필드를 동적으로 다음과 같이 생성합니다 {variable_name}_{aggregation_mode} (예: predictions_avg, classes_distinct, count_values_counts)

이 블록은 숫자 데이터에 대해 여러 집계 모드(sum, avg, max, min, values_difference), 카운팅 연산(count, count_distinct), 그리고 값 분석(distinct, values_counts). 목록형 데이터의 경우, 연산이 각 요소를 자동으로 처리합니다(예: count 목록 길이를 추가하고, distinct 각 요소를 고유 집합에 추가합니다). 간격은 시간 기반(비디오 스트림에서 실제 시계 시간이 중요할 때 유용) 또는 실행 기반(비디오 파일 처리에서 경과 시간보다 프레임 수가 더 중요할 때 유용)일 수 있습니다.

일반적인 사용 사례

• 비디오 스트림 분석: 라이브 비디오 스트림의 시간 간격별로 탐지 결과를 집계하여(예: 분당 평균 객체 수 계산, 시간당 관측된 고유 클래스 추적, 30초 창에서 최소/최대 탐지 수 계산) 연속 비디오 처리 워크플로에서 실시간 분석 및 모니터링을 가능하게 합니다

• 배치 비디오 처리: 실행 기반 간격을 사용하여 비디오 프레임 전반의 통계를 집계하고(예: 100프레임당 평균 탐지 수 계산, 500프레임 창에서 고유 객체 수 계산, 배치당 총 탐지 수 합산) 경과 시간보다 프레임 수가 더 중요한 사전 녹화 비디오 파일에 대해 의미 있는 분석을 가능하게 합니다

• 시계열 메트릭 수집: 시간이 지남에 따라 워크플로 메트릭을 수집하고 요약합니다(예: 탐지 수 집계, 평균 신뢰도 점수 계산, 고유 클래스 발생 추적, 값 분포 계산). 운영 워크플로에 대한 통계 분석 및 보고를 가능하게 합니다

• 모델 성능 분석: 여러 입력에 걸쳐 모델 예측을 분석합니다(예: 평균 예측 수 계산, 고유 예측 클래스 추적, 최소/최대 신뢰도 점수 계산, 각 클래스의 발생 횟수 계산). 포괄적인 모델 성능 평가와 인사이트를 가능하게 합니다

• 데이터 스트림 요약: 고빈도 데이터 스트림을 주기적인 보고서로 요약합니다(예: 60초마다 탐지 결과를 요약 통계로 집계, 시간당 평균 계산, 실행별 요약 생성). 대용량 워크플로에 대한 효율적인 데이터 축소 및 분석을 가능하게 합니다

• 다중 모델 비교: 비교를 위해 여러 모델의 결과를 집계합니다(예: 모델 간 평균 탐지 수 비교, 모델별 고유 클래스 추적, 모델 앙상블에 대한 집계 통계 계산). 다양한 추론 파이프라인 간 비교 분석을 가능하게 합니다

다른 블록에 연결하기

이 블록은 워크플로 단계로부터 데이터를 받고 집계 통계를 주기적으로 출력합니다:

• 탐지 또는 분석 블록 뒤에서 (예: 객체 탐지, 인스턴스 분할, 분류)를 사용하여 시간 경과 또는 프레임 전반에 걸쳐 예측 결과를 집계하고, 모델 출력 및 탐지 패턴에 대한 통계 분석을 가능하게 합니다

• 데이터 처리 블록 다음 (예: Expression, Property Definition, Detections Filter)와 같이 숫자 또는 목록 출력을 생성하여 간격별로 계산된 값, 메트릭 또는 변환된 데이터를 집계하는

• 싱크 블록 이전에 (예: CSV Formatter, Local File Sink, Webhook Sink)로 주기적인 집계 보고서를 저장하여 개별 데이터 포인트 대신 요약된 분석 데이터를 효율적으로 저장하고 내보낼 수 있게 합니다

• 비디오 처리 워크플로에서 시간 기반 또는 프레임 기반 분석 보고서를 생성하여 프레임별 출력 대신 주기적인 통계 요약을 포함한 포괄적인 비디오 분석을 가능하게 합니다

• 시각화 또는 보고 블록 전에 대시보드, 차트 또는 요약을 만들기 위해 집계된 데이터가 필요한, 시계열 데이터의 추세와 통계를 시각화할 수 있게 합니다

• 분석 파이프라인에서 고빈도 데이터를 주기적 요약으로 축소해야 하는 곳에서, 원시 대용량 데이터 스트림 대신 통계적 인사이트의 효율적인 하위 단계 처리 및 저장을 가능하게 합니다

유형 식별자

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

속성

이름	유형	설명	참조
name	str	이 단계에 대한 고유 식별자를 입력하세요..	❌
data_operations	Dict[str, List[Union[ClassificationPropertyExtract, ConvertDictionaryToJSON, ConvertImageToBase64, ConvertImageToJPEG, DetectionsFilter, DetectionsOffset, DetectionsPropertyExtract, DetectionsRename, DetectionsSelection, DetectionsShift, DetectionsToDictionary, Divide, ExtractDetectionProperty, ExtractFrameMetadata, ExtractImageProperty, LookupTable, Multiply, NumberRound, NumericSequenceAggregate, PickDetectionsByParentClass, RandomNumber, SequenceAggregate, SequenceApply, SequenceElementsCount, SequenceLength, SequenceMap, SortDetections, StringMatches, StringSubSequence, StringToLowerCase, StringToUpperCase, TimestampToISOFormat, ToBoolean, ToNumber, ToString]]]	집계 전에 데이터를 변환하는 UQL(Query Language) 작업 체인에 변수 이름(데이터에서 가져옴)을 매핑하는 선택적 딕셔너리입니다. 작업은 순서대로 적용되어 값을 추출, 필터링 또는 변환합니다(예: DetectionsPropertyExtract를 사용하여 탐지 결과에서 클래스 이름 추출, SequenceLength를 사용하여 시퀀스 길이 계산, 값 필터링, 계산 수행). 키는 데이터의 변수 이름과 일치해야 합니다. 변환이 필요 없는 변수는 비워 두거나 생략하세요. 예: {'predictions': [{'type': 'DetectionsPropertyExtract', 'property_name': 'class_name'}]}..	❌
aggregation_mode	Dict[str, List[str]]	집계할 연산 목록에 대한 변수 이름(데이터에서 가져옴) 매핑 사전입니다. 각 집계는 '{variable_name}_{aggregation_mode}'라는 이름의 출력 필드를 생성합니다. 지원되는 연산: 'sum'(숫자 값의 합계), 'avg'(숫자 값의 평균), 'max'/'min'(숫자 값의 최대/최소), 'count'(값 개수, 목록의 경우 목록 길이 추가), 'distinct'(고유 값 목록), 'count_distinct'(고유 값 수), 'values_counts'(값 발생 횟수 사전), 'values_difference'(숫자 값의 최대값과 최소값의 차이). 목록의 경우 연산은 각 요소를 처리합니다. 변수당 여러 집계를 지원합니다. 예: {'predictions': ['distinct', 'count_distinct', 'avg']}..	❌
interval_unit	str	집계 간격을 측정하는 단위: 'seconds', 'minutes', 'hours'(시간 기반, 마지막 출력 이후 경과한 실제 시계 시간을 사용 - 비디오 스트림에 유용) 또는 'runs'(실행 기반, 워크플로 실행 횟수를 계산 - 시간보다 프레임 수가 더 중요한 비디오 파일 처리에 유용)입니다. 시간 기반 간격은 집계 출력 사이의 경과 시간을 추적합니다. 실행 기반 간격은 블록이 데이터를 받는 횟수를 셉니다. 블록은 간격 임계값에 도달하면 집계 결과를 출력하고 상태를 비웁니다..	❌
interval	정수	interval_unit에 지정된 단위로 된 집계 간격의 길이입니다. 0보다 커야 합니다. 이 블록은 내부적으로 데이터를 누적하고 이 간격 임계값에 도달하면 집계 결과를 출력합니다. 시간 기반 단위(seconds, minutes, hours)의 경우, 이는 마지막 출력 이후 경과한 지속 시간입니다. 'runs'의 경우, 이는 마지막 출력 이후의 워크플로 실행 수(예: 처리된 프레임 수)입니다. 결과를 출력한 후 블록은 내부 상태를 초기화하고 새 집계 창을 시작합니다. 대부분의 시간 동안 이 블록은 데이터를 수집하는 동안 빈 출력을 반환합니다..	❌

이 참조 열은 워크플로우 런타임에서 사용 가능한 동적 값으로 속성을 매개변수화할 수 있는 가능성을 나타냅니다 워크플로우 런타임입니다. 자세한 내용은 바인딩 을 참조하세요.

런타임 호환성

소프트 - 런타임 호스팅 서버리스, 전용 배포; 실행 원격; 입력 비디오 : 이 블록은 프로세스 메모리에서 비디오별 상태를 유지합니다(video_metadata.video_identifier로 키 지정). 상태 비저장 또는 다중 복제 HTTP 런타임에서 원격 단계 실행을 사용하면 연속 요청이 서로 다른 작업자 프로세스에서 처리될 수 있으므로, 상태가 호출 사이에 초기화되어 추적 / 카운팅 / 집계를 위한 출력은 의미가 없어집니다. 안정적인 프레임 간 결과를 위해 지속적인 WebRTC 세션에서 로컬 단계 실행을 사용하세요.

소프트 - 입력 이미지 : 이 블록은 비디오나 반복 프레임 워크플로의 시간적 문맥에 의존합니다. 정지 이미지/사진에는 추적, 비교, 집계 또는 시각화할 의미 있는 히스토리가 없으므로 이 블록은 거의 또는 전혀 이점을 제공하지 않습니다.

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 데이터 집계기 버전 v1 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • 데이터 (*): 워크플로 단계 출력에 대한 데이터의 변수 이름을 매핑하는 사전입니다. 각 키는 집계를 위한 변수 이름이 되고, 각 값은 워크플로 단계 출력을 참조하는 선택자입니다(예: predictions, metrics, computed values). 이러한 변수는 어떤 집계를 계산할지 지정하기 위해 aggregation_mode에서 사용됩니다. 예: {'predictions': '$steps.model.predictions', 'count': '$steps.counter.total'}..

• 출력

  • * (*): 어떤 요소와도 동일한 값.

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/data_aggregator@v1",
	    "data": {
	        "predictions": "$steps.model.predictions",
	        "reference": "$inputs.reference_class_names"
	    },
	    "data_operations": {
	        "predictions": [
	            {
	                "property_name": "class_name",
	                "type": "DetectionsPropertyExtract"
	            }
	        ]
	    },
	    "aggregation_mode": {
	        "predictions": [
	            "distinct",
	            "count_distinct"
	        ]
	    },
	    "interval_unit": "seconds",
	    "interval": 10
	}