README.md

metadata

license: agpl-3.0
base_model: ultralytics/yolov8n
tags:
  - yolov8
  - object-detection
  - onnx
  - onnxruntime
  - raspberry-pi5
  - edge-ai
  - fire-detection
pipeline_tag: object-detection

Edge Fire Detection AI (화재 감시 온점 시스템)

라즈베리파이 5(Raspberry Pi 5) 임베디드 엣지 디바이스 환경에서 실시간으로 불꽃(Flame)과 연기(Smoke)를 감지하고 바운딩 박스를 추적하는 경량 객체 탐지(Object Detection) 모델입니다. YOLOv8n(Nano) 아키텍처를 기반으로 전이 학습(Transfer Learning)을 진행했으며, 하드웨어 연산 부하를 최소화하기 위해 ONNX 포맷 고속 런타임 최적화를 적용했습니다.

1. 학습 데이터 (Training Data)

• 데이터 출처: AI Hub 화재 감지 영상 데이터셋 및 자체 수집 화재 이미지 셋
• 클래스 정의: 총 2개 클래스 (flame: 불꽃 / smoke: 연기)
• 데이터 정제 및 증강 (Data Augmentation):
  • 야간 및 오지 등 저조도 상황에서의 오작동(False Positive)을 차단하기 위해 밝기 변형, 흐림(Blur), 모자이크(Mosaic) 증강 기법을 적용하여 모델의 강건성(Robustness) 확보
  • 엣지 디바이스의 I/O 버스 대역폭 부하를 경감하기 위해 입력 해상도를 320x240 및 640x480 투 트랙 규격으로 스케일링 전처리 수행

2. 모델 성능 (Evaluation Metrics)

평가 지표	파이토치 (.pt) 원본	ONNX 경량 가속 규격	비고 (라즈베리파이 5 CPU 기준)
mAP50 (전체 정확도)	84.5%	83.9%	포맷 변환에 따른 정확도 손실 0.6% 미만 방어
mAP50-95	0.521	0.518	-
추론 속도 (Latency)	약 350ms	약 45ms	ONNX 변환 후 실시간성(20 FPS 이상) 수렴

3. 모델 학습 과정 (Model Training Process)

• 학습 인프라: 고성능 외장 GPU(RTX 5070 Ti, 32GB RAM) 환경 기반 로컬 가속 빌드 구동
• 기반 아키텍처: 3.2M 가벼운 파라미터 구조를 가진 YOLOv8n을 백본(Backbone)으로 채택하여 임베디드 CPU 가동 대역폭 사전 확보
• 하이퍼파라미터 설정:

항목	설정값	비고
Epochs	50	-
Batch Size	32	하드웨어 VRAM 최적화 크기
Optimizer	AdamW	-
Learning Rate	1e-3	초기 학습률 지정
Augmentation	Mosaic (1.0), Blur (0.2)	가혹 환경 오작동 차단용

4. 개발 시행착오 및 트러블슈팅 (Trials & Errors)

임베디드 엣지 AI 시스템 구현 중 발생한 물리/소프트웨어 레이어의 병목 현상과 해결 리포트입니다.

① PyTorch 원시 모델(.pt) 구동 시 레이턴시 저하

• 문제 상황: 학습 완료된 best.pt 가중치를 라즈베리파이 5 CPU 단독 환경에서 추론했을 때 프레임 지연이 약 350ms(3 FPS 미만)까지 늘어나 실시간 화재 탐지가 불가능한 병목 직면.
• 해결 조치: 정적 연산 그래프 구조를 가진 ONNX 포맷으로 모델을 익스포트(format=onnx, imgsz=320)하고, 파이썬 백엔드에 onnxruntime 가속 플러그인을 결합하여 추론 레이턴시를 45ms(22 FPS 이상) 수준으로 비약적으로 단축함.

② Linux V4L2 장치 채널 타임아웃 (select() timeout)

• 문제 상황: 최신 라즈베리파이 OS(Bookworm) 커널에서 OpenCV로 웹캠을 호출할 때 미디어 컨트롤러 가속 스택이 /dev/video0 자원을 독점 점유(Lock)하여 select() timeout과 함께 하드웨어 좀비 락 현상 발생.
• 해결 조치: OpenCV 카메라 개시 코드단에 V4L2 백엔드를 명시적으로 지정(cv2.VideoCapture(0, cv2.CAP_V4L2))하고, 주피터 서버 구동 시 리눅스 에뮬레이션 호환 레이어 환경 변수인 LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libv4l/v4l1compat.so를 프리로드 래핑하여 커널 점유 충돌을 우회함.

③ USB 버스 대역폭 초과 및 픽셀 오염 (error dequeuing buf)

• 문제 상황: 압축 코덱 기능이 없는 일반 웹캠의 원시 데이터(Raw YUYV)를 640x480 해상도로 수신 시, 라즈베리파이 USB 대역폭 한계로 프레임 버퍼가 누수되어 화면이 지질거리거나 검은색(Black Screen)으로 죽는 현상 발생.
• 해결 조치: 웹캠을 전력 및 전송 효율이 높은 파란색 USB 3.0 포트로 물리적 이동 정렬을 수행한 후, 코드 레벨에서 입력 해상도를 320x240으로 대폭 낮추고 고속 압축 스트리밍 포맷(MJPG) 코덱 지정을 강제화하여 데이터 버스 통로를 복구함.

④ 주피터 네트워크 웹 소켓 붕괴 크래시 (ZMQError)

• 문제 상황: 추론 while 루프가 초당 수십 장의 이미지를 지연 없이 주피터 인라인 위젯(ipywidgets) 화면으로 밀어 넣으면서 통신 버퍼 오버플로우로 인해 주피터 커널이 정지하고 소켓이 터지는 현상 발생.
• 해결 조치: 이미지 변환 및 전송 루틴 직후 미세 유휴 연산 타임인 time.sleep(0.04) 지연 버퍼 로직을 안착시켜 초당 전송률을 20~25프레임 수준으로 안정화함으로써 연속 구동 안전성을 확보함.

5. 사용 방법 (Inference Code)

import cv2
import numpy as np
from ultralytics import YOLO
from IPython.display import display
import ipywidgets as widgets
import time

def main():
    model_path = "best.onnx"
    model = YOLO(model_path, task='detect')

    # V4L2 가속 백엔드 매핑
    cap = cv2.VideoCapture(0, cv2.CAP_V4L2)
    cap.set(cv2.CAP_PROP_FRAME_WIDTH, 320)
    cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 240)
    cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)

    time.sleep(1) # 하드웨어 안정화 대기
    if not cap.isOpened():
        print("[오류] 카메라 장치를 활성화할 수 없습니다.")
        return

    image_widget = widgets.Image(format='jpeg', width=320, height=240)
    display(image_widget)

    try:
        while cap.isOpened():
            success, frame = cap.read()
            if not success or frame is None:
                continue

            # ONNX 가속 추론 구동 (imgsz 일치)
            results = model(frame, imgsz=320, stream=True)
            for r in results:
                annotated_frame = r.plot()

            # JPEG 압축 후 주피터 렌더링 영역 업데이트
            ret, jpeg = cv2.imencode('.jpg', annotated_frame)
            if ret:
                image_widget.value = jpeg.tobytes()
            
            # ZMQ 과부하 방지용 micro-delay
            time.sleep(0.04) 
            
    except KeyboardInterrupt:
        print("\n사용자에 의해 시스템 가동이 중단되었습니다.")
    finally:
        cap.release()
        cv2.destroyAllWindows()
        print("하드웨어 자원 회수 완료.")

if __name__ == '__main__':
    main()

6. 입출력 형식 (Input / Output Format)

입력(Input): 실시간 임베디드 카메라 비디오 프레임 (320x240 RGB Image)
출력(Output): 
  - 불꽃 및 연기 영역 바운딩 박스(Bounding Box) 시각화 투사
  - 탐지 클래스 레이블 매핑: [flame, smoke]
  - 객체별 추론 신뢰도 수치 출력 (Confidence Score: 0.0 ~ 1.0)

7. 로컬 동기화 가중치 다운로드 CLI

huggingface-cli download firedetection/fire_detection_yolov8n --local-dir ./model