Post

Building Real-Time Video AI Applications 정리

Building Real-Time Video AI Applications 정리

1장. Real-Time Video AI란?

1. 개념

Real-Time Video AI는 카메라나 비디오 스트림에서 실시간으로 의미 있는 정보를 뽑아내는 기술이다.

예를 들어 CCTV 영상에서 사람, 차량, 장비, 위험 상황 등을 감지하고 그 결과를 서버나 화면으로 전달하는 구조다.

1
2
3
4
5
6
7
8
9
카메라 / 영상 입력
↓
프레임 처리
↓
AI 모델 추론
↓
객체 탐지 / 분류 / 추적
↓
결과 표시 / 저장 / 알림 전송

2. 대표적인 Computer Vision Task

작업의미예시
Classification이미지 전체가 무엇인지 분류이 이미지는 차량이다
Localization하나의 객체 위치를 찾음차량 위치 좌표 반환
Object Detection여러 객체의 위치와 종류를 찾음사람 3명, 차량 2대 탐지
Segmentation픽셀 단위로 객체 영역을 구분사람 영역을 마스크로 분리

3. Video AI 사용 예시

1
2
3
4
5
6
7
교통량 분석
병원 안전 모니터링
공장 불량 탐지
매장 고객 동선 분석
스포츠 영상 분석
구급차 내부 상황 분석
환자/장비 객체 탐지

4. 핵심 이해

이미지 AI는 한 장의 이미지를 분석하는 경우가 많지만, 비디오 AI는 프레임이 계속 들어온다. 그래서 단순히 모델을 잘 만드는 것뿐 아니라, 영상 입력부터 추론 결과 처리까지 전체 파이프라인이 중요하다.


2장. Video AI Pipeline 전체 구조

대부분의 비디오 AI 애플리케이션은 비슷한 구조를 가진다.

1
2
3
4
5
6
7
8
9
10
11
12
13
Video Input
↓
Decode
↓
Mux / Batch
↓
Preprocess
↓
AI Inference
↓
Postprocess
↓
Display / Save / Send

1. 단계별 설명

단계역할
Video Input파일, RTSP, CCTV, USB 카메라 등에서 영상 입력
Decode압축된 영상을 프레임으로 해석
Mux / Batch여러 영상 스트림을 하나의 batch로 묶음
Preprocessresize, format 변환, normalization
AI InferenceTensorRT 모델 등으로 객체 탐지/분류
Postprocessbbox, confidence, class 결과 정리
Display / Save / Send화면 출력, 파일 저장, 서버 전송

2. OpenCV 방식과 DeepStream 방식 차이

OpenCV 방식

1
2
3
4
while True:
    ret, frame = cap.read()
    result = model(frame)
    draw_result(frame, result)

장점은 이해하기 쉽다는 것이다. 하지만 카메라가 여러 대가 되고, FPS와 latency가 중요해지면 코드가 복잡해진다.

DeepStream 방식

1
source → decoder → streammux → inference → osd → sink

DeepStream은 각 단계를 plugin처럼 연결해서 실시간 영상 처리 파이프라인을 만든다.

3. 왜 Pipeline이 중요한가?

비디오 AI에서는 모델 추론만 빠르다고 전체 시스템이 빠른 게 아니다.

1
2
3
4
5
6
7
영상 읽기
디코딩
전처리
추론
후처리
저장
전송

이 모든 과정이 병목 없이 이어져야 한다.


3장. Edge AI와 DeepStream이 필요한 이유

1. Cloud 처리의 한계

모든 영상을 클라우드로 보내서 처리하면 다음 문제가 생긴다.

1
2
3
4
네트워크 지연
대역폭 비용 증가
원본 영상 전송으로 인한 개인정보 문제
네트워크 불안정 시 서비스 장애

2. Edge 처리의 장점

Edge는 카메라 근처 또는 현장 장비에서 바로 추론하는 방식이다.

1
2
3
4
5
6
7
카메라
↓
Jetson / GPU 서버
↓
현장에서 AI 추론
↓
결과만 서버로 전송

장점은 다음과 같다.

장점설명
빠른 응답현장에서 바로 판단 가능
낮은 대역폭원본 영상 전체가 아니라 결과만 전송 가능
네트워크 의존도 감소인터넷이 불안정해도 일부 처리 가능
개인정보 보호민감한 원본 영상을 저장/전송하지 않을 수 있음

3. DeepStream의 위치

DeepStream은 모델 학습 도구가 아니다. 학습된 모델을 영상 스트림에 붙여서 실시간으로 돌리는 도구다.

1
2
3
4
5
6
7
8
TAO Toolkit
= 모델 학습 / 전이학습 / 최적화

TensorRT
= 모델 추론 속도 최적화

DeepStream
= 영상 입력부터 AI 추론, 결과 처리까지 연결

4장. DeepStream SDK란?

1. 정의

DeepStream SDK는 NVIDIA가 제공하는 실시간 비디오/센서 스트리밍 분석 SDK다. GStreamer 기반으로 동작하며, NVIDIA GPU에서 빠르게 실행되도록 여러 하드웨어 가속 plugin을 제공한다.

2. DeepStream이 해주는 일

1
2
3
4
5
6
7
8
9
영상 입력 처리
하드웨어 디코딩
여러 스트림 batch 처리
AI inference 실행
객체 추적
bounding box 표시
metadata 추출
결과 저장
서버로 메시지 전송

3. DeepStream이 적합한 상황

DeepStream은 이런 경우에 의미가 크다.

1
2
3
4
5
6
카메라가 여러 대다
실시간 FPS가 중요하다
Jetson 또는 NVIDIA GPU에서 돌린다
TensorRT 모델을 사용한다
객체 탐지 결과를 서버로 보내야 한다
서비스 배포까지 고려한다

반대로 단순히 모델 정확도만 테스트하는 단계라면 Python + OpenCV + PyTorch가 더 편할 수 있다.

4. DeepStream 구조 예시

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
filesrc
↓
h264parse
↓
nvv4l2decoder
↓
nvstreammux
↓
nvinfer
↓
nvtracker
↓
nvdsosd
↓
sink

5장. GStreamer 핵심 개념

DeepStream은 GStreamer 기반이기 때문에 GStreamer 용어를 알아야 한다.

1. Element

Element는 파이프라인의 처리 단위다.

예를 들어:

1
2
3
4
5
6
7
filesrc       : 파일 읽기
h264parse     : H.264 비디오 파싱
nvv4l2decoder : 비디오 디코딩
nvstreammux   : 여러 스트림 묶기
nvinfer       : AI inference
nvdsosd       : bbox/text 표시
sink          : 출력

코드에서는 보통 이렇게 만든다.

1
2
3
4
5
6
7
source = Gst.ElementFactory.make("filesrc", "file-source")
parser = Gst.ElementFactory.make("h264parse", "h264-parser")
decoder = Gst.ElementFactory.make("nvv4l2decoder", "decoder")
streammux = Gst.ElementFactory.make("nvstreammux", "stream-muxer")
pgie = Gst.ElementFactory.make("nvinfer", "primary-inference")
nvosd = Gst.ElementFactory.make("nvdsosd", "onscreendisplay")
sink = Gst.ElementFactory.make("filesink", "file-output")

2. Pad

Pad는 element의 입구와 출구다.

1
2
source pad : 데이터가 나가는 곳
sink pad   : 데이터가 들어오는 곳

데이터는 항상 이런 식으로 흐른다.

1
element A의 source pad → element B의 sink pad

3. Bin

Bin은 여러 element를 묶는 컨테이너다.

4. Pipeline

Pipeline은 가장 상위의 bin이다. 전체 element를 담고 실행 상태를 관리한다.

1
pipeline = Gst.Pipeline()

5. Bus

Bus는 pipeline에서 발생하는 메시지를 애플리케이션으로 전달한다.

예를 들어:

1
2
3
에러 발생
영상 끝남
상태 변경

이런 이벤트를 감지할 수 있다.


6장. Buffer, Metadata, Probe

1. Buffer

Buffer는 GStreamer에서 데이터가 이동하는 기본 단위다. 비디오에서는 보통 프레임 데이터가 buffer에 담겨 이동한다.

1
buffer = 영상 프레임이 담긴 상자

2. Metadata

DeepStream은 AI 추론 결과를 buffer에 metadata로 붙인다.

예를 들어 객체 탐지 결과 metadata에는 다음 정보가 들어간다.

1
2
3
4
5
6
7
frame number
object count
class id
confidence
bounding box 좌표
tracking id
label

3. Probe

Probe는 pad에 붙이는 callback이다. 파이프라인 중간에서 지나가는 buffer와 metadata를 읽을 수 있다.

비유하면:

1
2
3
4
pipeline = 컨베이어벨트
buffer = 컨베이어벨트 위 박스
metadata = 박스에 붙은 검사표
probe = 중간 검사원

4. Probe 기본 코드 구조

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def osd_sink_pad_buffer_probe(pad, info, u_data):
    # buffer 가져오기
    gst_buffer = info.get_buffer()
    if not gst_buffer:
        return Gst.PadProbeReturn.OK

    # batch metadata 가져오기
    batch_meta = pyds.gst_buffer_get_nvds_batch_meta(hash(gst_buffer))

    # frame metadata 순회
    l_frame = batch_meta.frame_meta_list
    while l_frame is not None:
        frame_meta = pyds.NvDsFrameMeta.cast(l_frame.data)

        # object metadata 순회
        l_obj = frame_meta.obj_meta_list
        while l_obj is not None:
            obj_meta = pyds.NvDsObjectMeta.cast(l_obj.data)

            class_id = obj_meta.class_id
            confidence = obj_meta.confidence
            rect = obj_meta.rect_params

            print(class_id, confidence, rect.left, rect.top, rect.width, rect.height)

            l_obj = l_obj.next

        l_frame = l_frame.next

    return Gst.PadProbeReturn.OK

5. Probe를 붙이는 코드

1
2
3
4
5
6
osdsinkpad = nvosd.get_static_pad("sink")
osdsinkpad.add_probe(
    Gst.PadProbeType.BUFFER,
    osd_sink_pad_buffer_probe,
    0
)

보통 nvdsosd의 sink pad에 probe를 붙인다. 이 위치는 화면에 bbox를 그리기 직전이라 metadata를 읽기 좋다.


7장. 단일 DNN DeepStream Application

단일 DNN 애플리케이션은 하나의 AI 모델만 사용하는 구조다.

예를 들어 TrafficCamNet 하나를 사용해 차량, 사람, 표지판 등을 탐지한다.

1. 전체 구조

1
2
3
4
5
6
7
8
9
10
11
Input Video
↓
Decode
↓
StreamMux
↓
Primary Inference
↓
OSD
↓
Output

2. Pipeline 예시

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
filesrc
↓
h264parse
↓
nvv4l2decoder
↓
nvstreammux
↓
nvinfer
↓
nvvideoconvert
↓
nvdsosd
↓
encoder
↓
filesink

3. 코드 흐름

1단계. GStreamer 초기화

1
Gst.init(None)

2단계. Pipeline 생성

1
pipeline = Gst.Pipeline()

3단계. Element 생성

1
2
3
4
5
6
7
8
source = Gst.ElementFactory.make("filesrc", "file-source")
h264parser = Gst.ElementFactory.make("h264parse", "h264-parser")
decoder = Gst.ElementFactory.make("nvv4l2decoder", "nvv4l2-decoder")
streammux = Gst.ElementFactory.make("nvstreammux", "stream-muxer")
pgie = Gst.ElementFactory.make("nvinfer", "primary-inference")
nvvidconv = Gst.ElementFactory.make("nvvideoconvert", "convertor")
nvosd = Gst.ElementFactory.make("nvdsosd", "onscreendisplay")
sink = Gst.ElementFactory.make("filesink", "file-sink")

4단계. 파일 경로 설정

1
2
source.set_property("location", input_video_path)
sink.set_property("location", output_video_path)

5단계. streammux 설정

1
2
3
4
streammux.set_property("width", 1280)
streammux.set_property("height", 720)
streammux.set_property("batch-size", 1)
streammux.set_property("batched-push-timeout", 4000000)

6단계. nvinfer 설정 파일 연결

1
pgie.set_property("config-file-path", "config_infer_primary.txt")

4. nvinfer config 파일의 역할

DeepStream에서는 모델 관련 설정을 config 파일로 분리한다.

예시로 들어가는 정보:

1
2
3
4
5
6
7
8
model-engine-file
onnx-file
labelfile-path
batch-size
network-mode
num-detected-classes
interval
gie-unique-id

즉, Python 코드에서는 pipeline을 만들고, 모델 설정은 config 파일에서 관리한다.


8장. Element 연결과 실행 코드

1. Pipeline에 element 추가

1
2
3
4
5
6
7
8
pipeline.add(source)
pipeline.add(h264parser)
pipeline.add(decoder)
pipeline.add(streammux)
pipeline.add(pgie)
pipeline.add(nvvidconv)
pipeline.add(nvosd)
pipeline.add(sink)

2. 일반적인 element 연결

1
2
3
4
5
6
source.link(h264parser)
h264parser.link(decoder)
streammux.link(pgie)
pgie.link(nvvidconv)
nvvidconv.link(nvosd)
nvosd.link(sink)

3. decoder와 streammux 연결

nvstreammux는 여러 입력 스트림을 받을 수 있다. 그래서 일반 .link()가 아니라 request pad를 사용한다.

1
2
3
srcpad = decoder.get_static_pad("src")
sinkpad = streammux.get_request_pad("sink_0")
srcpad.link(sinkpad)

이 부분이 초보자에게 헷갈리는 핵심이다.

1
2
3
decoder의 src pad
↓
streammux의 sink_0 pad

4. Bus 설정

1
2
3
4
5
loop = GLib.MainLoop()

bus = pipeline.get_bus()
bus.add_signal_watch()
bus.connect("message", bus_call, loop)

Bus는 pipeline에서 발생하는 메시지를 받아온다. 예를 들어 에러, 종료, 상태 변경 등을 처리한다.

5. Pipeline 실행

1
2
3
4
5
6
7
8
pipeline.set_state(Gst.State.PLAYING)

try:
    loop.run()
except:
    pass

pipeline.set_state(Gst.State.NULL)

뜻은 다음과 같다.

1
2
3
4
5
6
7
PLAYING 상태로 변경
↓
main loop 실행
↓
영상 처리 진행
↓
끝나면 NULL 상태로 종료

9장. Multi-DNN DeepStream Application

Multi-DNN은 여러 개의 AI 모델을 연결해서 사용하는 구조다.

1. 단일 DNN과 Multi-DNN 차이

단일 DNN

1
2
3
4
5
영상
↓
객체 탐지 모델
↓
차량 / 사람 / 표지판 탐지

Multi-DNN

1
2
3
4
5
6
7
영상
↓
1차 모델: 객체 탐지
↓
2차 모델: 탐지된 객체 세부 분류
↓
결과 표시

2. PGIE와 SGIE

용어의미역할
PGIEPrimary GPU Inference Engine전체 프레임에서 객체 탐지
SGIESecondary GPU Inference EnginePGIE가 찾은 객체를 세부 분류

3. 예시 구조

1
2
3
4
5
6
7
8
9
10
11
12
원본 영상
↓
PGIE: TrafficCamNet
차량 / 사람 / 표지판 탐지
↓
SGIE: VehicleTypeNet
탐지된 차량의 종류 분류
↓
OSD
bbox와 label 표시
↓
출력 영상 저장

4. Multi-DNN Pipeline 예시

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
filesrc
↓
h264parse
↓
nvv4l2decoder
↓
nvstreammux
↓
pgie = nvinfer
↓
sgie = nvinfer
↓
nvvideoconvert
↓
nvdsosd
↓
sink

5. 코드 예시

1
2
3
4
5
pgie = Gst.ElementFactory.make("nvinfer", "primary-inference")
sgie = Gst.ElementFactory.make("nvinfer", "secondary-inference")

pgie.set_property("config-file-path", "config_infer_primary_trafficcamnet.txt")
sgie.set_property("config-file-path", "config_infer_secondary_vehicletypenet.txt")

6. SGIE가 동작하는 방식

SGIE는 전체 프레임을 다시 보는 것이 아니다. PGIE가 찾은 객체 영역을 crop해서 그 부분만 분류한다.

1
2
3
4
5
6
7
전체 프레임
↓
PGIE가 차량 bbox 탐지
↓
bbox 영역 crop
↓
SGIE가 차량 타입 분류

예를 들어:

1
2
PGIE 결과: car detected
SGIE 결과: sedan / SUV / truck / van

7. Multi-DNN이 필요한 이유

객체 탐지 모델 하나에 모든 기능을 넣으면 모델이 복잡해질 수 있다. 그래서 역할을 나누면 더 유연하다.

1
2
1차 모델: 어디에 객체가 있는지 찾기
2차 모델: 그 객체가 어떤 세부 타입인지 판단

10장. 성능 지표와 실무 적용 정리

1. 주요 성능 지표

지표의미
Accuracy분류 정확도
IoU예측 bbox와 실제 bbox가 얼마나 겹치는지
mAP객체 탐지 모델의 대표 성능 지표
FPS초당 처리 프레임 수
Throughput전체 처리량
Latency입력부터 결과까지 걸리는 시간
GPU UtilizationGPU 사용률
Memory Footprint실행 중 차지하는 메모리 크기

2. FPS와 Latency 차이

FPS

1
1초에 몇 프레임을 처리하는가?

예를 들어 30 FPS면 1초에 30장을 처리한다는 뜻이다.

Latency

1
프레임이 들어와서 결과가 나올 때까지 걸리는 시간

실시간 알림이 중요한 시스템에서는 latency가 매우 중요하다.

3. DeepStream이 좋은 경우

1
2
3
4
5
NVIDIA GPU 또는 Jetson을 사용한다
RTSP/CCTV 스트림을 여러 개 처리한다
실시간 FPS가 중요하다
TensorRT 모델을 사용한다
객체 탐지 결과 metadata를 서버로 보내야 한다

4. DeepStream이 과할 수 있는 경우

1
2
3
4
5
이미지 몇 장만 테스트한다
모델 정확도만 실험한다
카메라 1대만 간단히 확인한다
NVIDIA 하드웨어가 없다
비NVIDIA NPU를 사용한다

5. 네 프로젝트에 적용한다면

예를 들어 구급차/병원/교육장 영상 분석에 적용하면 다음 구조가 가능하다.

1
2
3
4
5
6
7
8
9
10
11
카메라 영상
↓
DeepStream pipeline
↓
BVM / 손동작 / 장비 / 사람 탐지 모델
↓
metadata 추출
↓
이벤트 판단
↓
CMS 또는 서버 전송

예시 이벤트:

1
2
3
4
5
BVM이 감지됨
손 위치가 잘못됨
특정 장비가 화면에서 사라짐
환자 주변에 사람이 접근함
특정 행동이 일정 시간 지속됨

6. 전체 핵심 요약

DeepStream은 모델을 학습시키는 도구가 아니다.

1
2
3
모델 학습: TAO / PyTorch / TensorFlow
모델 최적화: TensorRT
실시간 영상 파이프라인: DeepStream

DeepStream의 핵심은 다음과 같다.

1
2
3
4
5
6
GStreamer 기반 pipeline
NVIDIA 하드웨어 가속 plugin
nvinfer를 통한 TensorRT inference
metadata 기반 결과 처리
probe callback을 통한 결과 접근
multi-stream / multi-DNN 확장 가능

부록. 핵심 용어 정리

용어뜻
DeepStreamNVIDIA의 실시간 비디오 AI SDK
GStreamer멀티미디어 파이프라인 프레임워크
Elementpipeline의 처리 단계
Padelement의 입구/출구
Source Pad데이터가 나가는 pad
Sink Pad데이터가 들어오는 pad
Bin여러 element를 묶는 컨테이너
Pipeline전체 처리 흐름
Buffer영상 데이터가 담겨 이동하는 단위
Eventstream 상태 정보를 전달하는 단위
MetadataAI 추론 결과 정보
Probepad에 붙여 metadata를 읽는 callback
Buspipeline 메시지를 애플리케이션에 전달
nvinferTensorRT 기반 inference plugin
nvstreammux여러 stream을 batch로 묶는 plugin
nvv4l2decoderNVIDIA 하드웨어 디코더
nvdsosdbbox/text를 영상에 그리는 plugin
PGIE1차 inference 모델
SGIE2차 inference 모델
TAO Toolkit모델 학습/전이학습/최적화 도구
TensorRTNVIDIA 추론 최적화 엔진
FPS초당 처리 프레임 수
Latency입력부터 결과까지 지연 시간
Throughput전체 처리량
Memory Footprint실행 중 메모리 사용량

부록. 외워야 할 코드 뼈대

1. 초기화

1
2
Gst.init(None)
pipeline = Gst.Pipeline()

2. Element 생성

1
2
3
4
5
6
7
source = Gst.ElementFactory.make("filesrc", "file-source")
parser = Gst.ElementFactory.make("h264parse", "h264-parser")
decoder = Gst.ElementFactory.make("nvv4l2decoder", "decoder")
streammux = Gst.ElementFactory.make("nvstreammux", "stream-muxer")
pgie = Gst.ElementFactory.make("nvinfer", "primary-inference")
nvosd = Gst.ElementFactory.make("nvdsosd", "onscreendisplay")
sink = Gst.ElementFactory.make("filesink", "file-sink")

3. 설정

1
2
3
source.set_property("location", input_video_path)
pgie.set_property("config-file-path", "config_infer_primary.txt")
sink.set_property("location", output_video_path)

4. Pipeline에 추가

1
2
for element in [source, parser, decoder, streammux, pgie, nvosd, sink]:
    pipeline.add(element)

5. 연결

1
2
3
4
5
6
7
8
9
10
source.link(parser)
parser.link(decoder)

srcpad = decoder.get_static_pad("src")
sinkpad = streammux.get_request_pad("sink_0")
srcpad.link(sinkpad)

streammux.link(pgie)
pgie.link(nvosd)
nvosd.link(sink)

6. Probe 추가

1
2
3
4
5
6
osdsinkpad = nvosd.get_static_pad("sink")
osdsinkpad.add_probe(
    Gst.PadProbeType.BUFFER,
    osd_sink_pad_buffer_probe,
    0
)

7. 실행

1
2
3
pipeline.set_state(Gst.State.PLAYING)
loop.run()
pipeline.set_state(Gst.State.NULL)

최종 정리 문장

DeepStream은 “AI 모델을 학습하는 도구”가 아니라, “이미 학습된 모델을 실시간 영상 스트림에 연결해서 서비스처럼 돌리는 파이프라인 도구”다.

따라서 DeepStream을 공부할 때는 모델 구조보다 다음을 이해하는 것이 중요하다.

1
2
3
4
5
영상이 pipeline을 어떻게 흐르는가?
각 element가 어떤 역할을 하는가?
AI 결과가 metadata로 어디에 붙는가?
probe로 결과를 어떻게 꺼내는가?
단일 DNN과 Multi-DNN 구조가 어떻게 다른가?

이 글은 Velog 에 처음 올렸습니다.

This post is licensed under CC BY 4.0 by the author.