엣지 AI 기반 통학 시간대
교통 위험 모니터링 시스템 구축 및 인식 개선 — 프로젝트 개요

상자 안은 코드명, 이름은 상자 바깥. 회색 점선 = 엣지 보드 한 대 안(Jetson 또는 Pi), 붉은 점선 = 영상이 존재하는 두 구간(프레임 · 크롭, 모두 메모리). 카운터 매뉴얼의 지도에 QUE · VLM · MON 세 상자와 inferences 층이 추가된 것이 전부이며, 초록 경로만으로도 K1~K3가 나옴.

컴포넌트 설명표 (지도의 코드명 순)

문제 확인(1주 관찰)이 맨 앞에 오고, GATE 0 GATE 1 GATE 2 GATE 3 네 곳은 사람이 통과를 결정함. 카운터 매뉴얼의 게이트 3개에 GATE 2 · VLM 판정 검증이 끼어든 것이 차이. VLM 트랙(R5)은 GATE 1을 지난 뒤에만 시작 — 지표가 먼저, 연구가 그 위에.

01트랙 비교표

02Jetson 런타임 세팅 (R1 · 문서 순서대로)

# 0) 현재 상태 확인 — 계획서의 "JetPack 6" 가정을 여기서 깸
cat /etc/nv_tegra_release            # R39 (rel 39.2.x) 이면 JetPack 7.2.x
apt list --installed 2>/dev/null | grep -E "nvidia-jetpack|tensorrt|cuda-toolkit"
python3 --version                    # 3.12
# 1) 전력 모드 · 데스크톱 끄기 · 계측 도구
sudo nvpmodel -q ; sudo nvpmodel -m 0 ; sudo jetson_clocks      # MAXN SUPER 여부는 -q 출력에서 확인
sudo systemctl set-default multi-user.target && sudo reboot     # GUI 메모리 반환 (필요 시 graphical 로 복귀)
sudo pip3 install -U jetson-stats && jtop                        # 메모리 · 전력 · 온도 한눈에
# 2) 프로젝트 venv (시스템 site-packages 상속 — CUDA · OpenCV 접근)
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/xparapx/<REPO>.git ~/traffic && cd ~/traffic
uv venv --system-site-packages && uv sync
# 3) PyTorch/TensorRT 휠 — JetPack 7.2 (CUDA 13) 용 aarch64 휠을 NVIDIA PyPI(jp7) 또는 검증된 릴리스에서. cu126 휠은 동작하지 않음
# 4) YOLO11 → TensorRT 엔진 (보드에서, 30분 내외)
uv run yolo export model=yolo11n.pt format=engine half=True imgsz=640 device=0   # → yolo11n.engine (models/ · git 제외)
# 5) llama.cpp CUDA 빌드 · VLM 서버 (모델 파일은 git 제외)
git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp && cmake -B build -DGGML_CUDA=ON && cmake --build build -j
./build/bin/llama-server -m models/qwen2.5-vl-3b-q4_k_m.gguf --mmproj models/mmproj-qwen2.5-vl-3b-f16.gguf -ngl 99 -c 2048 --port 8090
# 6) 카메라 확인
v4l2-ctl --list-devices ; v4l2-ctl -d /dev/video0 --list-formats-ext        # ELP: MJPG 1920x1200 @30 확인
v4l2-ctl -d /dev/video0 -c exposure_auto=1 -c exposure_absolute=150               # 수동 노출 고정 (역광 대비)
gst-launch-1.0 v4l2src device=/dev/video0 ! image/jpeg,width=1920,height=1080,framerate=30/1 ! nvv4l2decoder mjpeg=1 ! nvvidconv ! video/x-raw,format=BGRx ! fakesink -v
gst-launch-1.0 nvarguscamerasrc ! nvvidconv ! fakesink                       # CSI (IMX477/219)
# 7) 원격
curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up

03백엔드 경계 — 코드에 그어 두는 두 줄

from typing import Protocol, Iterator
import numpy as np

class Detection:  # 정규화 좌표 · 원 라벨 · 신뢰도 — 백엔드가 무엇이든 같은 모양
    __slots__ = ("label", "conf", "x1", "y1", "x2", "y2")

class Detector(Protocol):
    def infer(self, frame_bgr: np.ndarray) -> list[Detection]: ...
    def stats(self) -> dict: ...            # {"infer_ms": .., "backend": "tensorrt"}

def load(cfg: dict) -> Detector:
    if cfg["backend"] == "tensorrt":
        from .tensorrt_yolo import TensorRTYolo   # ultralytics YOLO("yolo11n.engine")
        return TensorRTYolo(cfg["engine"], conf=0.40, classes=[0, 1, 2, 3, 5, 7])
    if cfg["backend"] == "hailo":
        from .hailo_yolo import HailoYolo         # HailoRT .hef + 후처리
        return HailoYolo(cfg["hef"], conf=0.40)
    raise ValueError(cfg["backend"])

# vlm/__init__.py 도 같은 꼴: class Tagger(Protocol): def tag(self, crop_bgr, meta) -> dict
#   llama_cpp 백엔드 = HTTP(localhost:8090, OpenAI 호환) · hailo 백엔드 = GenAI SDK

04현장 기하 검토 — 3층 중앙탑 창에서 교문 · 도로까지 (사진 기반 추정 · 실측 전)

항공사진의 화살표 시작점(본관 3층 중앙탑 창)을 기준으로 시야 · 가림 · 거리 · 렌즈를 검토함. 아래 수치는 사진 축척 추정이며, R0에서 지도 거리 재기(네이버 · 카카오맵)와 창 높이 실측으로 바꿔 넣은 뒤 렌즈를 확정함.

카운터 매뉴얼 절 K(사선 구도 · 프레임 미저장 · track_id · 가상선 · 호모그래피 · p85 · 5분 버킷 · QC · ORB · 기준 프로파일 · 규범 메시지 · 검토 큐 · systemd)는 그대로 전제. 여기는 이 프로젝트에서 새로 나오는 말만.

01후보 변수 측정 가능성 등급 (카운터 표 + VLM 후보)

02정의 (등교 시간대 = 등교 시각 − 40분 ~ 등교 시각)

01하는 것 · 하지 않는 것 (VLM 추가분)

02통제 세션 규칙 (2안이 필요할 때만)

• 학교 개인정보 보호 담당자에게 설계서(절 1 · 2 · 3) 제출 · 확인 — VLM 크롭 처리 · 텍스트 저장 범위 · 통제 세션 여부 명시
• 교육청 영상정보처리기기 · 개인정보 지침 해당 여부 확인 (문의 기록)
• 학교장 · 학생안전부 승인 · 학부모회 사전 설명 (VLM은 "정차 사유 태그"로만 설명)
• 안내문 게시 (창 안쪽 · 교문) 후 카메라 전원 ON
• CLAUDE.md 프라이버시 조항 v1: "이미지 파일 쓰기 코드 금지 · VLM 출력은 enum JSON만 · 금칙어 필터 통과 전 DB 기록 금지"

01트리거 · 크롭 · 프롬프트 · 결합 규칙

import asyncio, time, json, re, numpy as np
from .vlm import load as load_tagger            # llama_cpp | hailo 백엔드
ENUM = {"boarding", "waiting", "delivery", "other"}
BAN  = re.compile(r"(색|흰|검정|빨간|파란|승용|SUV|승합|트럭|남성|여성|아이|어린이|노인|\d{2,3}[가-힣]\d{4})")

class SlowLoop:
    def __init__(s, cfg, db, mon):
        s.q = asyncio.Queue(maxsize=cfg.get("queue_max", 8)); s.tagger = load_tagger(cfg); s.db, s.mon = db, mon; s.dropped = 0
    def submit(s, event_id, crop_rgb, meta):     # Fast Loop 스레드에서 호출 · 절대 블록하지 않음
        try: s.q.put_nowait((event_id, crop_rgb, meta))
        except asyncio.QueueFull:
            s.q.get_nowait(); s.q.put_nowait((event_id, crop_rgb, meta)); s.dropped += 1
    async def run(s):
        while True:
            event_id, crop, meta = await s.q.get(); t0 = time.time(); m0 = s.mon.snapshot()
            try:    out = s.tagger.tag(crop, meta)              # dict 또는 예외
            except Exception as e: out = {"tag": "unknown", "err": type(e).__name__}
            finally: del crop                                   # 크롭은 여기서 끝
            tag = out.get("tag") if out.get("tag") in ENUM and not BAN.search(json.dumps(out, ensure_ascii=False)) else "unknown"
            row = {"event_id": event_id, "model_type": "VLM_ONLY", "tag": tag, "door_open": bool(out.get("door_open")),
                   "person_near": bool(out.get("person_near")), "conf": out.get("conf"),
                   "latency_ms": int((time.time() - t0) * 1000), **s.mon.delta(m0)}   # mem_mb · power_w · gpu_pct
            s.db.insert_inference(row); s.db.insert_inference(hybrid(meta, row))     # HYBRID 행 · YOLO_ONLY 행은 Fast Loop이 이미 씀

01대안 비교 · 이 개요의 결정

02메모리 예산 — 가정을 적고 실측으로 지움

03실측 프로토콜 (R5 · 통제 세션 또는 등교 3일)

import subprocess, re, time, threading
PAT = re.compile(r"RAM (\d+)/(\d+)MB.*?SWAP (\d+)/(\d+)MB.*?GR3D_FREQ (\d+)%.*?(?:VDD_IN|VIN_SYS_5V0) (\d+)mW.*?(?:gpu|GPU)@([\d.]+)C")
class Mon:                                   # tegrastats 1 Hz 를 파싱해 최신값 유지 (Pi 백엔드는 vcgencmd)
    def __init__(s): s.v = {}; threading.Thread(target=s._loop, daemon=True).start()
    def _loop(s):
        p = subprocess.Popen(["tegrastats", "--interval", "1000"], stdout=subprocess.PIPE, text=True)
        for line in p.stdout:
            m = PAT.search(line)
            if m: s.v = dict(ts=time.time(), ram_mb=int(m[1]), swap_mb=int(m[3]), gpu_pct=int(m[5]), power_w=int(m[6]) / 1000, temp_c=float(m[7]))
    def snapshot(s): return dict(s.v)
    def delta(s, m0): now = s.v; return dict(mem_mb=now.get("ram_mb"), power_w=now.get("power_w"), gpu_pct=now.get("gpu_pct"), swap_mb=now.get("swap_mb"))
# 정규식은 보드의 실제 tegrastats 한 줄로 R1 에서 맞춤 — 필드명이 JetPack 버전마다 다름

-- events 확장: Slow Loop 대상인지 · 최종 risk 는 HYBRID 행에서 가져오되 표시용으로 캐시
ALTER TABLE events ADD COLUMN event_id TEXT;            -- UUID v4 · 3표 조인 키 (id 는 로컬 정수 유지)
ALTER TABLE events ADD COLUMN risk_level TEXT;          -- SAFE | WARNING | DANGER (HYBRID 기준 캐시)
ALTER TABLE qc_5min ADD COLUMN vlm_dropped INTEGER;     -- 큐 드롭 수
ALTER TABLE qc_5min ADD COLUMN power_w REAL;            -- 5분 평균 전력 (MON)
ALTER TABLE qc_5min ADD COLUMN mem_mb INTEGER;          -- 5분 최대 RAM
ALTER TABLE qc_5min ADD COLUMN throttle INTEGER;        -- 온도 throttling 비트

-- 판정: 같은 event_id 에 model_type 별 1행 (섀도 로깅)
CREATE TABLE inferences(
  id INTEGER PRIMARY KEY, event_id TEXT NOT NULL, ts TEXT NOT NULL,
  model_type TEXT NOT NULL,            -- YOLO_ONLY | VLM_ONLY | HYBRID
  risk_level TEXT NOT NULL,            -- SAFE | WARNING | DANGER
  tag TEXT, door_open INTEGER, person_near INTEGER, conf REAL,   -- VLM 출력 (enum 만 · 자유 문장 없음)
  latency_ms INTEGER, mem_mb INTEGER, power_w REAL, gpu_pct INTEGER, swap_mb INTEGER,
  model_ver TEXT, prompt_ver TEXT, rules_ver TEXT, backend TEXT, -- 재현성 (yolo11n-fp16-trt10 · qwen2.5vl-3b-q4 · p1 · h1 · tensorrt|hailo)
  UNIQUE(event_id, model_type));

-- 사람 라벨: 창가 실시간 육안 기록 · 통제 세션 대본 — 이미지 없이 만드는 유일한 정답
CREATE TABLE labels(
  id INTEGER PRIMARY KEY, event_id TEXT NOT NULL, ts TEXT NOT NULL,
  hazard INTEGER NOT NULL,             -- 1 = 실제 위험 정차 (구역 밖 · 시야 가림) · 0 = 정상
  tag TEXT,                            -- boarding | waiting | delivery | other (사람 판정)
  labeler TEXT NOT NULL, source TEXT NOT NULL,   -- live | session
  note TEXT);

-- 벤치 실행: B0~B4 각 실행의 요약 (초 단위 시계열은 qc_5min · inferences 에 이미 있음)
CREATE TABLE bench_runs(
  id INTEGER PRIMARY KEY, started TEXT, ended TEXT, board TEXT, mode TEXT,   -- jetson|pi · YOLO_ONLY|SHADOW|SEQ_*
  fps_med REAL, fps_p05 REAL, lat_p50_ms INTEGER, lat_p95_ms INTEGER, mem_max_mb INTEGER,
  swap_max_mb INTEGER, power_avg_w REAL, temp_max_c REAL, n_events INTEGER, n_dropped INTEGER, note TEXT);

-- 계획서 호환 뷰: 단일 표처럼 읽기
CREATE VIEW traffic_monitoring_events AS
  SELECT i.event_id, i.ts AS timestamp, i.model_type, i.risk_level, i.tag AS context_tag,
         i.latency_ms AS inference_latency_ms, i.mem_mb AS gpu_mem_used_mb, i.power_w AS power_draw_w,
         l.hazard AS is_ground_truth_hazard, l.tag AS gt_tag, e.zone, e.duration_s
  FROM inferences i JOIN events e ON e.event_id = i.event_id LEFT JOIN labels l ON l.event_id = i.event_id;
CREATE INDEX ix_inf_event ON inferences(event_id); CREATE INDEX ix_lab_event ON labels(event_id);

01수집 페이로드 — 누가 어느 표에 쓰는가

01인사이트 → 알림 매핑 (카운터 표 + 추가 3행)

02UI 설계 — 화면 · 포트 · 데이터 원천

Plant_Growth_Monitoring_Demo의 web/(React · Vite · Tailwind v4 · ECharts · PWA · 목 데이터 모드)를 셸로 가져오고, 페이지만 바꿈. 공개 포트는 analysis만 읽고, 이미지 · 라이브 프리뷰는 어느 포트에도 없음.

┌──────────────────────────────┐
│ 교문 앞 통행 · 오늘 09/15(화)  │
│ 안전 지수  ▮▮▮▮▮▮▮░░░ 72 (▲3) │
│ K1 초과율 24% │ K2 6건 │ K3 3건 │
│ 지금 5분: 차 14 · 이륜 3 · 보행 22│
│ QC 통과 91% · 수동 대조 ±8%     │
│ [지난주 리포트] [프로파일] [정차]│
└──────────────────────────────┘

┌──────────────────────────────┐
│ 이벤트 08:21:14 · no_stop · 27 s │
│ 남은 시간 ●●●●○○ 41 s           │
│ 위험한 정차였나요?  [예] [아니오] │
│ 사유  [승하차][대기][배송][기타]  │
│ 라벨러: 김○○   [저장]            │
│ (이미지 없음 · 창가에서 보고 입력)│
└──────────────────────────────┘

03인식 개선 루프 · 알림 규칙

01운영 구조

02저장소 구조 (Plant_Growth_Monitoring_Demo 포맷)

<REPO>/                       # 예: SchoolZone_Edge_Traffic_Demo
  edge/trafficsvc/            # 패키지 (Plant 의 hub/plantsvc 대응): settings · schema · config · db
    capture/                  #   uvc.py · csi_argus.py · picam.py — 같은 제너레이터 인터페이스 (프레임 파일 쓰기 없음)
    detect/                   #   __init__.py(Protocol) · tensorrt_yolo.py · hailo_yolo.py
    counter/                  #   tracker.py(ByteTrack) · geo.py(호모그래피·가상선) · counter.py · acc.py · drift.py(ORB)
    vlm/                      #   __init__.py(Protocol) · llama_cpp.py · hailo_genai.py · prompts/p1.txt · hybrid_rules.py
    slowloop.py · fastloop.py · mon.py · qc.py · api.py(공개/관리) · cli.py(serve·doctor·seed·bench·session) · doctor.py
  analysis/                   # run_daily.py · run_weekly.py · m0_calib.py … m4_conflict.py · b1_confusion.py · b2_resource.py · safety_score.py
  llm/                        # weekly_draft.py · validate.py · prompts/weekly_ko.txt
  notify/                     # dispatch.py (approved 만)
  web/                        # React + Vite + TS + Tailwind v4 + ECharts (src/features/{today,profile,speed,dwell,bench,label,outbox,system})
  deploy/systemd/             # traffic-fast.service.tmpl · traffic-vlm.service.tmpl · traffic-web.service.tmpl · traffic-analysis.timer.tmpl
  scripts/                    # setup_jetson.sh · setup_pi.sh · install.sh · deploy.ps1 · bench.sh · session.sh · rollback.sh
  models/                     # export_trt.sh · fetch_gguf.sh · README (가중치 · 엔진은 git 제외)
  tests/                      # pytest — 합성 궤적 · 큐 드롭 · 검증기 · dispatch(draft 무시) · 스키마 (하드웨어 없이)
  docs/                       # index.html(이 문서) · manual.html(구축 매뉴얼 · 카운터 P1~P7 계승) · WORKLOG.md · GATES.md
  data/                       # traffic.db · config.json · calib/ · sessions/ (전부 git 제외 · 이미지 없음)
  CLAUDE.md  README.md  pyproject.toml  .gitignore

03CLAUDE.md 필수 조항 (첫 커밋에)

각 단계는 카운터 매뉴얼의 P1~P7에 대응하고(괄호), 상세 실습 절차는 docs/manual.html로 옮김. 여기는 무엇을 · 언제 · 어디까지와 위임 프롬프트의 컨텍스트 블록만. 프롬프트의 [컨텍스트]에 있는 것 이상을 Claude Code에 요구하지 않음 — 그것이 곧 CLAUDE.md의 현재 상태.

R0문제 확인 · GATE 0 · 저장소 생성 (카운터 절 0 · 2) · 1~2주차

R1Jetson 런타임 · 카메라 · 미저장 캡처 (H · P1) · 2주차

R2검출 · 추적 · 가상선 · 속도 · 정차 · 근접 (P2 · P3) · 3~4주차

R35분 집계 · QC · MON · 서비스 등록 (P4) · 4~5주차

R4수동 대조 GATE 1 (P5) · 5~6주차

R5Slow Loop · 자원 실측 · 라벨 60건 GATE 2 (신규) · 6~9주차

R6대시보드 · 배치 · 알림 · 검토 큐 (P6) · 8~11주차

R7로컬 LLM 리포트 · 전후 비교 · 건의 GATE 3 (P7) · 11~14주차

R8Pi 5 + AI HAT+ 2 이식 (선택 · 12~14주차)

14주 일정 (주차 격자 · 1주차 = 9/14 주)

역할 (팀 5명 기준 · 겸임 가능)

프로젝트 완료 기준 (전부 체크되면 종료)

• 문제 진술 1장(H1~H3 · R1~R3 · K1~K3 · C1 · 목표치)에 담당 교사 서명
• GATE 0 문서(확인 · 승인 · 안내문 사진 · VLM 처리 방식 명시) 보관
• 이미지 · 영상 파일 0건 — 저장소 · Jetson · Pi 전체 검색 결과 첨부 (통제 세션 디렉터리는 별도 삭제 로그)
• 등교일 20일 이상 5분 버킷, qc=0 ≥ 80%
• GATE 1 정확도 표 — 차량류 오차 ≤ 10%
• GATE 2 결과 — 라벨 ≥ 60건, 모델별 혼동행렬, 자원 실측표(절 4) 완성 (통과 여부와 무관하게 공개)
• K1 · K2 · K3 baseline 2주 + 개입 2회 + 전후 비교 결과 공개 (효과 없음 포함)
• 주간 리포트 3회 발송(승인 로그) · 로컬 LLM 실측표
• 월간 건의 리포트 PDF 1건(정확도 부록 + 벤치 표) 제출 또는 제출 준비
• 벤치 표 1장: YOLO / VLM / HYBRID × (FPR · Recall · 정밀도 · fps · ms · MB · W) — 계획서의 가정 열과 실측 열 나란히
• 학생 발표: "우리 데이터로 무엇이 바뀌었고, 하이브리드는 무엇을 주고 무엇을 치렀는가"

명령 (Jetson)

cat /etc/nv_tegra_release                 # JetPack 7.2.x = R39
jtop / tegrastats --interval 1000         # RAM · GPU · 전력 · 온도
sudo nvpmodel -q ; sudo jetson_clocks     # 전력 모드 확인 · 클럭 고정
v4l2-ctl --list-devices                   # 카메라
systemctl status traffic-fast traffic-vlm traffic-web ; journalctl -u traffic-fast -f
systemctl list-timers | grep traffic      # 배치
curl -s localhost:8090/health             # llama-server
sqlite3 data/traffic.db "SELECT model_type, COUNT(*) FROM inferences GROUP BY 1;"
sqlite3 data/traffic.db "SELECT * FROM bench_runs ORDER BY id DESC LIMIT 5;"
find ~/traffic -name "*.jpg" -o -name "*.png" -o -name "*.mp4" -o -name "*.h264"   # 항상 0건 (data/sessions 제외)
tailscale status

참고 자료

글꼴 IBM Plex Sans KR / Mono · 색 토큰은 대시보드 hub/web/app.css와 동일(라이트 기본, 다크 토글) · 세 지도는 archify 규약(상자 안 코드명 · 이름은 바깥 · 큰 글꼴)으로 작성한 인라인 SVG · 이 파일은 외부 의존성 없이 단독 열림(글꼴만 온라인) · 원본: 스쿨존_교통카운터.html(v0.2) + 스쿨존_교통_위험_연구_계획서.html · 확인 기준일 2026-09-14