본 프로젝트는 영구자석 동기 모터(PMSM) 10 Hz 시계열 데이터를 기반으로 EV 구동계 이상 진단, 설명, 운전자 안내까지 전 주기를 다루는 엔드-투-엔드 파이프라인입니다. 데이터 전처리 → 모델 학습/튜닝 → 성능 보정 → XAI → LLM 피드백 → 실시간 시뮬레이터까지 모든 구성 요소를 코드로 재현할 수 있도록 설계했습니다.
- 윈도우링 및 라벨링:
src/features/build_features.py는 입력 CSV를 10 Hz로 리샘플링하고, 100스텝 윈도우(=10 초)·1스텝 슬라이드로 분할합니다. 라벨 전략은any_positive로 구현되어 윈도우 내 어느 시점이든 고장 라벨이 존재하면 해당 고장으로 레이블링됩니다(build_features.py:93). - 클리핑 & 스케일링: IQR 아웃라이어 제거, 훈련 세트 기반
StandardScaler학습 후 train/val/test에 일관되게 적용합니다(build_features.py:152). 학습 시 쓰이는 스케일러는data/processed/scaler_train.joblib로 저장됩니다. - 라벨 인코더 유지:
LabelEncoder를data/processed/label_encoder.joblib로 저장하여 학습·평가·시뮬레이터에서 동일 라벨 순서를 사용합니다(build_features.py:160). - 데이터셋 클래스:
src/data/pmsm_dataset.py의PMSMWindowDataset은.npz에서[N, C, L]형태 텐서를 반환하고,create_dataloaders가 train/val/test DataLoader를 한 번에 구성합니다.
재현 절차
- CSV 준비 →
notebooks/02_BuildFeatures_PMSM_10Hz.ipynb실행data/processed/pmsm_win100_step1.npz생성 (라벨·스케일러·Encoder 포함)
- 모델 구조:
src/models/model_1dcnn.py에 정의된 1D-CNN을 사용합니다. 하이퍼파라미터는experiments/cnn_*.yaml로 관리되며,hidden_channels,kernel_sizes, dilations, dropout 등을 설정할 수 있습니다. - 학습 루프:
src/train/train_cnn.py는 class-weighted CrossEntropy, Label Smoothing, Grad Clip, ReduceLROnPlateau 스케줄러를 지원합니다. - CLI 진입점:
실행 시
python scripts/train.py --config experiments/cnn_best_config.yaml
experiments/results/<run>.pt와metrics.json이 생성됩니다. - 재현성 보장:
- 시드 고정(
fix_seed) - 상대경로를 절대경로로 해석하는 유틸 (
src/utils/paths.py) - 모든 학습 결과를
experiments/results/하위에 기록
- 시드 고정(
| 체크포인트 | Test Accuracy | Macro F1 | Weighted F1 | 비고 |
|---|---|---|---|---|
experiments/results/cnn_relabel_baseline.pt |
0.905 | 0.892 | 0.910 | 라벨 전략 any_positive 적용 후 재학습 |
experiments/results/cnn_001_afcccc54.pt |
0.903 | 0.887 | 0.908 | Stage4 검색 최적 모델 |
- 결과 요약은
notebooks/04_Model_Analysis_PMSM_10Hz.ipynb에서 자동으로 생성됩니다. - 스윕 기록은
experiments/cnn_sweep_summary.json에 정리되어 있으며, 베스트 런(cnn_023_1074d7a4)이 Macro F1≈0.868을 달성했습니다.
- 성능 평가:
scripts/eval.py --checkpoint <path>는 혼동행렬, 정밀도/재현율/F1, 샘플별 예측 로그를 출력합니다. - Temperature Scaling:
src/calibration/temperature.py는 validation 기반T를 학습하고, 테스트셋에서 보정 후 NLL/ECE를 계산합니다. - Grad-CAM / Saliency:
src/eval/analysis.py:129에서 1D Grad-CAM(src/xai/cam1d.py)을 실행하고,compute_channel_saliency로 채널별 중요도를 집계합니다.src/ui/sim/analysis.py:79는 학습 모델과 Grad-CAM 러너를 캐시해 실시간 시각화 성능을 확보했습니다.
- 노트북 시각화:
notebooks/04_Model_Analysis_PMSM_10Hz.ipynb는 요약 DF → 베스트 모델 선택 → 혼동행렬 → 보정 전후 비교 → 채널 중요도 → Grad-CAM 오버레이까지 순차 실행합니다.
- 프롬프트 설계:
src/feedback/gpt_prompter.py는 센서 요약·Grad-CAM 근거·보정 확률을 JSON으로 묶어 전달하는 컨텍스트 리치 프롬프트를 정의합니다. 운전자에게 코드명(F0 등)이나 센서 변수명을 직접 노출하지 않도록 시스템 프롬프트에서 강하게 제약합니다. - Fallback 전략:
- API가 없거나 실패 시
DEFAULT_FALLBACK_MESSAGES를 반환 - GPT 응답이 JSON 형식이 아닐 경우
source="gpt_raw"로 표시하고,src/ui/app_streamlit.py:300에서 rule 기반 템플릿(build_model_fallback_feedback)으로 대체합니다.
- API가 없거나 실패 시
- CRITICAL 레벨 안전 장치: GPT가
CRITICAL을 내리더라도 무조건 rule 기반 템플릿(build_rule_feedback)으로 덮어써 운전자 안전 지침을 통제합니다.
streamlit run src/ui/app_streamlit.py --server.headless true --server.port 8501- 모듈 분리:
src/ui/sim/config.py: 채널/색상/시나리오/로그 경로 정의src/ui/sim/analysis.py: 보정 확률, 히스테리시스, Grad-CAM 캐시src/ui/sim/views.py: 운전자/연구자 뷰 UI 컴포넌트src/ui/sim/logging_utils.py: 시나리오 실행 로그(JSON) 저장
- 운전자 뷰:
- 상태 카드(
render_status_indicator)가 진단 레벨을 색상 카드로 표시 - 보정/원본 확률 카드, 행동 지침 체크리스트, 서비스 메모, TTS (gTTS 설치 시 자동 합성)
- 긴급 단계에서
📞 긴급 지원 요청버튼 제공
- 상태 카드(
- 연구자 뷰:
- 혼동행렬, 지표 테이블, Temperature Scaling 비교
- 채널 saliency 바차트, Grad-CAM × 센서 오버레이 그래프
- 시나리오 엔진:
- 시나리오 정의(
SCENARIO_LIBRARY)별로 단계/샘플/지속시간을 지정 - 단계 전환 간격
SIM_REFRESH_INTERVAL=0.3s로 실시간 피드백 - 실행 로그는
reports/logs/<scenario>_YYYYMMDD_HHMMSS.json으로 저장
- 시나리오 정의(
ev-fault-gpt/
├── data/ # raw / processed (npz, scaler, label encoder)
├── experiments/ # 학습 설정(YAML) 및 체크포인트(.pt)
├── notebooks/ # EDA 및 분석 노트북
├── reports/ # 로그, 도큐먼트 산출물
├── scripts/ # CLI 엔트리포인트 (train/eval/export)
├── src/
│ ├── features/ # build_features.py 등 전처리 로직
│ ├── data/ # PMSMWindowDataset
│ ├── train/ # 1D-CNN 학습 코드
│ ├── eval/ # 평가/Grad-CAM/Saliency
│ ├── xai/ # GradCAM1D 구현
│ ├── feedback/ # GPT 프롬프트 및 클라이언트
│ ├── calibration/ # Temperature Scaling
│ ├── ui/ # Streamlit 앱 및 시뮬레이션 모듈
│ └── utils/ # 공통 유틸(path, seed 등)
└── README.md
- 데이터 가공
notebooks/02_BuildFeatures_PMSM_10Hz.ipynb실행 →data/processed/업데이트
- 학습
python scripts/train.py --config experiments/cnn_best_config.yaml
- 평가/보정
python scripts/eval.py --checkpoint experiments/results/<run>.pt- 산출물: NLL/ECE, 혼동행렬, json 로그
- 설명/시각화
notebooks/04_Model_Analysis_PMSM_10Hz.ipynb재실행으로 Figure/Table 갱신
- 시뮬레이션 데모
- Streamlit 실행 → 운전자/연구자 뷰 확인
- 시뮬레이션 로그(
reports/logs/)를 보고서 부록으로 활용
- Temperature Scaling 전후 (Validation/Test):
- NLL: 0.393 → 0.273 / 0.456 → 0.347
- ECE: 0.156 → 0.047 / 0.154 → 0.051
- Grad-CAM 분석: 모터 권선 단락 사례에서
모터 상전류 B,인버터 출력 전압채널이 집중적으로 활성화됨을 확인했습니다. - GPT 피드백: 센서 요약·추세·Grad-CAM 근거를 포함한 Prompt를 사용하여 운전자에게 고장 원인·행동 지침·TTS를 동시에 제공합니다. CRITICAL 단계는 rule 기반 템플릿으로 즉시 정차 지시를 내려 안전 기준을 만족합니다.
- 모델 정교화: Warning/Attention 구간 라벨 품질 검증 및 히스테리시스 파라미터 튜닝, 다중 모델 앙상블 도입.
- 온도 보정 심화: 구간별(채널/시간) 교정, Bayesian Calibration 검토.
- UI/UX 확장: 모바일·차량 HMI에 적용 가능한 모듈화(
src/ui분리)를 기반으로 실제 긴급 호출 API 연동, 시뮬레이션 로그 기반 자동 리포트 도구 개발. - 규제 준수: ISO 26262 등 안전 표준 관점에서 CRITICAL 템플릿 추적성 강화.
- 윈도우 라벨링:
src/features/build_features.py:93 - 데이터셋/로더:
src/data/pmsm_dataset.py:20 - 학습 루프:
src/train/train_cnn.py:71 - Grad-CAM:
src/xai/cam1d.py - GPT 프롬프트:
src/feedback/gpt_prompter.py:19 - Streamlit 운전자 뷰:
src/ui/app_streamlit.py:291 - 시나리오 정의:
src/ui/sim/config.py:32
이 README는 프로젝트 재현·논문 작성·데모 준비를 위한 기술적 근거와 절차를 모두 포함하도록 작성되었습니다. 필요 시 reports/logs/의 시뮬레이션 로그와 notebooks/04_*의 분석 결과를 참고하여 보고서/논문 본문에 Figure·Table·기술적 설명을 추가하십시오.