Skip to content

comm083/SearchLight

BranchesTags

Repository files navigation

🔦 SearchLight - CCTV 자연어 의미 검색 시스템

마지막 업데이트: 2026-04-24

자연어로 CCTV 영상을 검색할 수 있는 AI 기반 통합 검색 시스템입니다. 사용자가 "빨간 옷 입은 사람 찾아줘"라고 입력하면, AI가 의도를 파악하고 관련 CCTV 장면을 의미 기반으로 검색하여 보여줍니다.

🎯 프로젝트 목표

**보안 특화 NLP 기술(의도 분류·시간 파싱)**을 결합하여, 방대한 CCTV 이벤트 데이터를 대화형으로 분석하고 상황별 맞춤 응답을 생성하는 RAG 기반 지능형 보안 보조 시스템 구축.

📌 해결하려는 문제

문제 설명
인간적 오류 (Human Error) CCTV 관제는 장시간 모니터링 과정에서 중요한 장면을 놓치거나 잘못 해석하는 오류가 발생할 수 있다. 이러한 인간적 오류는 사건 대응의 지연이나 부정확한 판단으로 이어져 보안 시스템의 신뢰성을 저하시킨다.
장시간의 CCTV 기록 6~8시간 이상의 긴 영상 기록은 사건 발생 시점을 정확히 기억하거나 기록하지 않으면, 다시 확인하는 데 많은 시간이 소요된다.
비직관적인 인터페이스 기존 CCTV 시스템은 전문가 중심으로 설계되어 있어 일반 사용자가 쉽게 사용하기 어렵다. 이로 인해 원하는 정보를 빠르게 찾기 힘들고, 상황 대응이 지연될 수 있다.

🔧 핵심 기술 스택

기술 역할
KoELECTRA (의도 분류) 사용자 질의의 목적(조회/위험/장애/출입/일상)을 5종으로 분류
시간 파싱 (Time Parsing) "어제 오후 3시", "3일 전 오전 10시" 같은 자연어 시간 표현을 정확한 datetime으로 변환
FAISS (벡터 검색) 자연어 질의와 유사한 CCTV 장면 묘사 텍스트를 의미 기반으로 검색
RAG (검색 증강 생성) 검색된 CCTV 데이터를 컨텍스트로 활용하여 상황별 맞춤 자연어 응답 생성
Supabase (클라우드 DB) 검색 로그 및 이벤트 데이터 저장

🗂️ 프로젝트 구조

SearchLight/
├── ai/
│   ├── data/                   # 공유 데이터 (scene_descriptions.json 등)
│   ├── intent_classifier/      # C담당: KoELECTRA 의도 분류 모듈
│   └── vector_search/          # B담당: FAISS 벡터 검색 모듈
├── backend/                    # FastAPI 백엔드 서버
│   ├── app/
│   │   ├── main.py             # API 엔드포인트 (/api/search)
│   │   └── services/           # DB, 의도분류, 벡터검색 서비스 모듈
│   └── static/images/          # CCTV 예시 이미지 70장 보관
├── database/                   # A담당: SQLite 정형 데이터 관리
├── frontend/                   # React 프론트엔드 (Vite + Tailwind)
└── .env                        # API 키 등 환경변수 (GitHub 비공개)

📊 전체 프로젝트 진행 현황

범례: ✅ 완료 | 🔄 진행중 | ⬜ 미착수

🔗 시스템 통합 (Integration)

항목 상태 비고
FastAPI 백엔드 서버 구동 ✅ /api/search 엔드포인트 정상 작동
FAISS 벡터 검색 → 백엔드 연동 ✅ 150건 장면 묘사 데이터 로드 및 검색 작동
KoELECTRA 의도 분류 → 백엔드 연동 ✅ 임시 모델로 API 연동 완료
Supabase 클라우드 DB 연동 ✅ 검색 로그 정상 저장 확인
React 프론트엔드 UI 구현 ✅ 다크 테마, 애니메이션, 이미지 카드 UI 완성
React 프론트엔드 ↔ 백엔드 연결 ✅ Vite 프록시 설정 완료, API 통신 정상
이미지 static 서빙 설정 ✅ backend/static/images/ 경로로 70장 서빙 중
검색 결과에 이미지 경로 연동 ✅ scene_descriptions.json에 image_path 매핑 완료
API 키 환경변수(.env) 보안 처리 ✅ .gitignore 등록 완료

👤 A. 정형 데이터 & 인프라 (database/)

항목 상태 비고
yolo_events DB 스키마 설계 ✅ Supabase 테이블 및 SQLAlchemy 모델 정의 완료
가상 이벤트 데이터 480건 삽입 ✅ Supabase 클라우드로 이전 완료
시간 기반 정밀 필터링 쿼리 구현 ✅ get_events_by_time 쿼리 모듈 완성
검색 API에서 시간 필터 파라미터 수용 ✅ SearchRequest 모델에 시간 파라미터 추가 완료

👤 B. 비정형 데이터 & 벡터 검색 (ai/vector_search/)

항목 상태 비고
장면 묘사 데이터셋 구축 ✅ 150건 (scene_descriptions.json) 완성
Sentence-Transformers 임베딩 파이프라인 ✅ KR-SBERT 모델 활용
FAISS 인덱스 생성 및 Top-K 검색 ✅ 백엔드 서비스로 통합 완료
예시 사진 70장 경로 DB 연동 ✅ scene_descriptions.json에 image_path 필드 추가 완료
검색 결과에서 이미지 URL 반환 ✅ vector_search.py 수정 완료

👤 C. 의도 분류 & 데이터 증강 (ai/intent_classifier/)

항목 상태 비고
의도 분류 API 모듈 백엔드 연동 ✅ intent_classifier.py 서비스 연동 완료
현재 모델 성능 수치화 ✅ 정확도 20.0% (파인튜닝 필요 확인)
데이터 증강 스크립트 작성 ✅ data_augmentation.py (OpenAI gpt-4o-mini 사용)
수동 학습 데이터 기초 구축 ✅ 카테고리별 20건씩 총 100건 intent_dataset.csv 생성
KoELECTRA 파인튜닝 학습 스크립트 ✅ train.py 작성 완료
OpenAI API 결제 완료 ✅ gpt-4o-mini 사용 가능 (약 13~15원/500건)
GPT 데이터 증강 실행 (300건 목표) ✅ 직접 증강 완료 (300건)
KoELECTRA 파인튜닝 실행 ✅ 학습 완료 (Accuracy: 85%)
파인튜닝 후 성능 재평가 ✅ 테스트셋 90% 달성 (evaluate_current_model.py)
학습된 모델로 백엔드 교체 ✅ model/koelectra_finetuned 경로 자동 적용 완료
5가지 의도 카테고리 전체 지원 ✅ 조회/위험/장애/출입/일상 5종 지원 완료

🚨 지금 당장 실행할 순서 (결제 완료!)

# [1단계] 데이터 증강 실행 (약 2~3분, 비용 13원 내외)
python ai/intent_classifier/data_augmentation.py

# [2단계] 모델 학습 (약 5~10분)
python ai/intent_classifier/train.py

# [3단계] 성능 확인
python ai/intent_classifier/evaluate_current_model.py

# [4단계] 백엔드 재시작 (새 모델 반영)
# backend/app/services/intent_classifier.py 모델 경로 수정 후:
.\searchlight\Scripts\python.exe -m uvicorn --app-dir backend app.main:app --host 127.0.0.1 --port 8000

🚀 앞으로 진행할 작업 (Next Steps)

현재 핵심 모듈 통합이 완료되었으며, 최종 발표 전 다음 단계를 수행해야 합니다.

  1. 새로운 라이브러리 설치: 터미널에서 pip install -r requirements.txt를 실행하여 kiwipiepy 등 새 모듈을 설치합니다.
  2. 백엔드 API 연동 확인: backend/app/main.py에서 KoreanTimeParser와 IntentClassifier 서비스가 정상 호출되는지 확인합니다.
  3. 복합 질의 테스트: "어제 야간 상황 어땠어?", "지금 정문에 사람 몇 명이야?" 등 시간과 의도가 결합된 질문을 테스트합니다.
  4. 최종 문서화 및 발표 준비: 체크리스트를 기반으로 누락된 기능이 없는지 확인하고, 강사님 면담 및 발표 시나리오를 점검합니다.
항목 상태
파인튜닝 모델로 "주차장 화면 보여줘" 정상 검색되는지 확인 ✅
검색 결과에 이미지가 실제로 출력되는지 확인 ✅
A 파트 SQLite DB 연동 및 시간 필터 작동 확인 ✅
발표용 Before/After 정확도 비교 화면 캡처 (20% → 90%+) ⬜
팀원 전체 로컬 환경에서 서버 구동 테스트 ⬜

⚡ 빠른 시작 (Quick Start)

# 가상환경 활성화
.\searchlight\Scripts\Activate.ps1

# 백엔드 서버 실행 (루트 폴더에서)
.\searchlight\Scripts\python.exe -m uvicorn --app-dir backend app.main:app --host 127.0.0.1 --port 8000

# 프론트엔드 서버 실행 (새 터미널)
cd frontend
npm run dev
# → http://localhost:3000 접속


# 학습 데이터 증강 (OpenAI 크레딧 필요)
python ai/intent_classifier/data_augmentation.py

# 모델 학습 (데이터 300건 확보 후)
python ai/intent_classifier/train.py

🛠️ 프로젝트 수행 공정 (Development Process)

본 프로젝트는 체계적인 NLP 파이프라인 구축을 위해 다음의 6단계 공정을 거쳐 수행되었습니다.

  1. 문제 정의 및 의도 설계: 보안 도메인 특유의 질의 분석을 위한 5대 의도(Intent) 카테고리 정의
  2. 데이터 수집 및 증강: 초기 데이터셋 부족 해결을 위해 GPT API를 활용한 300건 이상의 데이터 증강 수행
  3. 토큰화 및 임베딩 전략: KoELECTRA 전용 토크나이저와 문장 단위 의미 파악을 위한 SBERT 임베딩 적용
  4. 모델 학습 및 파인튜닝: KoELECTRA-Base 모델 기반의 지도 학습(Supervised Learning) 및 하이퍼파라미터 최적화
  5. 성능 평가 및 분석: 초기 모델 대비 정확도 70%p 향상(20%→90%) 달성 및 혼동 행렬(Confusion Matrix) 분석
  6. 서비스 통합 및 배포: FastAPI 백엔드 내에 시간 파서 및 의도 분류기 서비스 레이어 통합 및 실시간 API 구축

👥 팀 역할 분담

개발자 담당 역할 핵심 기술 스택 주요 결과물
A (Data 엔지니어) 정형 데이터 & 인프라 SQLite, Pandas, FastAPI yolo_events DB, 시간 기반 필터링 모듈
B (AI 엔지니어 - 검색) 비정형 데이터 & RAG FAISS, Sentence-Transformers scene_descriptions 벡터 인덱스, 검색 엔진
C (AI 엔지니어 - NLP) 의도 분류 & 데이터 증강 KoELECTRA, PyTorch, GPT API Intent Dataset, 질문 분류 모델(5종)

🚀 향후 고도화 로드맵 (Future Roadmap)

지능형 보안 관제 시스템의 완성도를 높이기 위한 차기 개발 단계입니다.

  • 1. 대화 문맥 유지 (Multi-turn Dialogue)
    • 내용: 이전 질문의 맥락을 기억하여 연속적인 대화 가능
    • 예시: "주차장의 수상한 사람 누구야?" ➔ (답변 후) ➔ "그 사람 지금 어디 있어?" (지칭어 처리)
    • 기술: LangChain Memory 모듈 및 Conversation Chain 활용
  • 2. 실시간 보안 보고서 생성 (Advanced RAG)
    • 내용: 검색된 파편화된 정보를 종합하여 전문적인 관제 보고서 자동 생성
    • 효과: "어제 상황 요약해줘" ➔ "14시경 거동 수상자 감지 후 보안 요원 출동..." (문서화)
  • 3. 선제적 이상 행동 실시간 알림 (Active Alerting)
    • 내용: 사후 검색을 넘어 실시간으로 위험 상황을 감지하고 즉시 푸시 알림/음성 경고 송출
    • 효과: "사후 검색"에서 "실시간 선제적 방어" 시스템으로 진화
  • 4. 이미지 기반 유사 인물/차량 검색 (Image-to-Image)
    • 내용: 텍스트뿐만 아니라 사진 업로드를 통해 동일 인물이나 차량을 전 채널에서 검색
    • 기술: CLIP(Contrastive Language-Image Pre-training) 및 벡터 유사도 비교
  • 5. 일상 질의 예외 처리 (Out-of-Distribution Handling)
    • 내용: "안녕", "밥 먹었어?" 등 보안과 무관한 일상적인 질문에 대해 "보안 관련 질문을 해주세요"라고 친절하게 응대하는 필터링 로직 구현
  • 6. STT/TTS 사용자 경험(UX) 최적화
    • 내용: 음성 인식 후 서버 응답 대기 시간 동안 실시간 로딩 애니메이션 등을 시각화하여 대기 체감 시간 단축 및 피드백 강화
  • 7. 검색 데이터셋 및 이미지 다양화
    • 내용: 현재 70장의 이미지를 다양한 시간대(눈, 비, 야간), 다양한 각도로 확장하여 검색의 정밀도 및 풍부함 보완
  • 8. JSON 데이터를 Supabase Vector DB로 이관 (Cloud Native RAG)
    • 내용: 로컬 JSON 파일과 FAISS 인덱스를 Supabase의 pgvector로 이관하여 클라우드 기반의 통합 데이터 관리 체계 구축

🔍 시스템 고증 및 고도화 체크리스트 (Fixing Contextual Inconsistencies)

실제 보안 관제 현장의 현실성을 반영하기 위한 고도화 작업 목록입니다.

  • 1. "지금" 시간 범위의 현실화
    • 내용: ±5분 범위를 현재 시각 - 1분 ~ 현재 시각으로 조정하여 미래 시간 검색을 배제하고 실시간성을 강화합니다.
    • 파일: backend/app/services/korean_time_parser.py
  • 2. 실시간 위치(Localization) 처리 로직 고도화
    • 내용: LOCALIZATION 의도의 경우 벡터 검색(RAG) 대신 SQLite/Supabase의 최신 상태 로그를 직접 조회하여 정확한 위치를 반환합니다.
    • 파일: backend/app/main.py, backend/app/services/database.py
  • 3. 대화 맥락 내 인물/객체 특징(Feature) 유지
    • 내용: "빨간 옷 입은 사람"과 같은 외형 특징을 대화 메모리에 저장하고, 이어지는 지칭어("그 사람") 질의 시 검색 쿼리에 자동으로 포함합니다.
    • 파일: backend/app/main.py, SESSION_MEMORY 구조 개선
  • 4. 주관적 시간 표현("아까" 등)의 유연성 확보
    • 내용: "아까"를 고정된 1시간이 아닌, 가장 최근에 발생했던 유의미한 이벤트 시점으로 동적 할당하거나 범위를 최적화합니다.
    • 파일: backend/app/services/korean_time_parser.py
  • 5. 보안 도메인 특화 시간대 경계 재정의
    • 내용: 야간(Sunset to Sunrise), 교대 시간 등 보안 현장에서의 실제 시간 개념을 반영하여 파싱 로직을 정교화합니다.
    • 파일: backend/app/services/korean_time_parser.py
  • 6. 검색 결과의 정밀도 향상 (Filtering Irrelevant Results)
    • 내용: 질문과 관련 없는 영상이나 분석 결과가 포함되지 않도록 검색 임계값(Threshold) 조정 및 필터링 로직을 강화합니다.
    • 일정: 내일(2026-04-29) 해결 예정

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages