# Quick Training (Teachable Machine-like) — 구현 로드맵

**작성일:** 2026-04-14
**작성자:** finetheAi Platform Team

## 목표
Edge 단말(일반 사용자)에서 **이미지 업로드 → 라벨링 → 학습 → 모델 다운로드** 전 과정을 웹 UI만으로 수행 가능한 "빠른 학습" 플랫폼 구축. Google Teachable Machine과 유사한 경험을 제공하되, YOLO 기반 객체 검출로 확장.

## 아키텍처

```
┌─────────────────────────────────────────────────────────┐
│  Edge 사용자 (브라우저)                                   │
│  1. 이미지 업로드 (드래그&드롭)                             │
│  2. 브라우저에서 바운딩박스 그리기                          │
│  3. "학습 시작" 클릭                                       │
│  4. 실시간 학습 진행률 (WebSocket)                         │
│  5. 학습 완료 → .pt / ONNX / TFJS 다운로드                  │
└─────────────────────────────────────────────────────────┘
                         ↕ HTTP/WS
┌─────────────────────────────────────────────────────────┐
│  Platform Server                                          │
│  - QuickTrain Session (세션별 격리 데이터)                  │
│  - 백그라운드 학습 큐 (GPU 가용 시 처리)                    │
│  - 학습 완료 모델 24h 보존 후 자동 삭제                     │
└─────────────────────────────────────────────────────────┘
```

## 데이터 구조

```
server/data/quick_train/
  ├── {session_id}/
  │   ├── images/        # 업로드된 원본 이미지
  │   │   ├── img1.jpg
  │   │   └── ...
  │   ├── labels/        # YOLO txt 포맷 라벨
  │   │   ├── img1.txt   # class_id cx cy w h (normalized)
  │   │   └── ...
  │   ├── classes.json   # 클래스 정의
  │   ├── data.yaml      # YOLO 학습 설정
  │   ├── runs/          # 학습 결과
  │   │   └── train/
  │   │       └── weights/best.pt
  │   ├── session.json   # 세션 메타
  │   └── status.json    # 학습 상태
```

## Phase 1 — 백엔드 (1주)

### 서비스: `server/services/quick_train_service.py`

```python
class QuickTrainService:
    - create_session(user_id: Optional[str]) -> session_id
    - upload_image(session_id, file) -> image_id
    - delete_image(session_id, image_id)
    - save_labels(session_id, image_id, labels: list) -> None
    - add_class(session_id, name) -> class_id
    - list_classes(session_id)
    - start_training(session_id, config)
    - get_status(session_id) -> progress/metrics
    - cancel_training(session_id)
    - get_model_path(session_id) -> Path
    - cleanup_old_sessions(hours=24)
```

### 라우터: `server/routers/quick_train.py`

| 메서드 | 경로 | 설명 |
|--------|------|------|
| POST | `/api/quick-train/session` | 새 세션 생성 |
| GET | `/api/quick-train/{sid}` | 세션 정보 |
| DELETE | `/api/quick-train/{sid}` | 세션 삭제 |
| POST | `/api/quick-train/{sid}/images` | 이미지 업로드 (multipart) |
| DELETE | `/api/quick-train/{sid}/images/{img_id}` | 이미지 삭제 |
| GET | `/api/quick-train/{sid}/images/{img_id}` | 이미지 서빙 |
| POST | `/api/quick-train/{sid}/classes` | 클래스 추가 |
| GET | `/api/quick-train/{sid}/classes` | 클래스 목록 |
| POST | `/api/quick-train/{sid}/labels/{img_id}` | 라벨 저장 |
| GET | `/api/quick-train/{sid}/labels/{img_id}` | 라벨 조회 |
| POST | `/api/quick-train/{sid}/train` | 학습 시작 |
| GET | `/api/quick-train/{sid}/status` | 진행률 |
| POST | `/api/quick-train/{sid}/stop` | 학습 중지 |
| GET | `/api/quick-train/{sid}/download/{format}` | pt/onnx/tfjs 다운로드 |
| WS | `/ws/quick-train/{sid}` | 실시간 진행률 |

## Phase 2 — UI (1주)

### 페이지: `/quick-train`
- 사이드바: DATA 섹션에 "Quick Training" 메뉴 추가
- Vue 컴포넌트: `server/static/js/components/quick-train.js`

### 4단계 워크플로우 화면
```
[1. Upload]    →  [2. Label]    →  [3. Train]    →  [4. Download]
 드래그&드롭       캔버스 라벨링     진행률 모니터      모델 파일
```

### 핵심 UI 요소
- **업로드 존**: 드래그&드롭 + 파일 선택, 썸네일 그리드
- **라벨 캔버스**: 클래스 색상, 바운딩박스 그리기/삭제/편집 (기존 label-editor 재사용)
- **클래스 패널**: 색상 팔레트, 이름 편집, 추가/삭제
- **학습 설정**: 에포크/배치 슬라이더, 사전학습 모델 선택
- **진행률**: WebSocket 실시간 epoch/loss/mAP 차트
- **다운로드**: 3포맷 버튼 (pt/onnx/tfjs) + 실시간 테스트 버튼

## Phase 3 — UX 고도화 (1주)

### 3.1 사전 학습 모델 선택
- **빠름**: yolo11n (nano) — Edge 디바이스용
- **균형**: yolo11s (small) — 기본
- **정확도**: yolo11m (medium) — 고성능

### 3.2 다양한 포맷 내보내기 (PyTorch 주력)

| 포맷 | 용도 | 우선순위 |
|------|------|----------|
| **`.pt` (PyTorch)** | 서버/Edge GPU 추론 (주력) | ⭐⭐⭐ 핵심 |
| **`.onnx`** | 범용 (서버 + Edge CPU/GPU, TensorRT 변환 가능) | ⭐⭐⭐ 핵심 |
| **TensorRT `.engine`** | NVIDIA GPU Edge 최대 속도 | ⭐⭐ 추가 |
| **TorchScript `.torchscript`** | PyTorch Mobile (Android/iOS) | ⭐⭐ 추가 |
| **TFLite `.tflite`** | ARM Edge 디바이스 (Raspberry Pi 등) | ⭐ 선택 |

플랫폼 주력은 PyTorch 유지. 브라우저 직접 실행용 TFJS는 대부분 사용처가 없어 우선순위에서 제외.

### 3.3 실시간 프리뷰
- 학습 중간 에포크마다 샘플 이미지로 추론
- UI에 "현재 성능 미리보기" 표시

### 3.4 Edge 직접 배포
- 완료 후 "Edge에 배포" 버튼
- Edge Devices 메뉴와 연동
- OTA 업데이트 자동 트리거

### 3.5 실시간 카메라 테스트
- 브라우저 카메라로 실시간 추론
- TFJS 모델 로드 후 WebRTC stream 분석

## 데이터 보안

- **세션별 독립 디렉토리** — 세션 간 데이터 접근 불가
- **익명 세션**: 24h 후 자동 삭제
- **로그인 사용자**: 영구 보존, Dataset Hub 연동
- **업로드 제한**: 이미지 최대 500장, 파일당 10MB
- **동시 학습 제한**: 세션당 1개, 서버 전체 GPU 큐잉

## 기술 스택

| 항목 | 사용 기술 |
|------|-----------|
| 학습 엔진 | ultralytics YOLO (기존) |
| 프론트엔드 | Vue 3 + Canvas API |
| 실시간 | WebSocket (기존 인프라) |
| 저장 | 로컬 파일 시스템 (세션별 격리) |
| 포맷 변환 | .pt → ONNX (onnx) / TFJS (tensorflowjs_converter) |

## 예상 소요

| 단계 | 범위 | 기간 |
|------|------|------|
| Phase 1 | 백엔드 서비스 + API | 3-4일 |
| Phase 2 | UI (4단계 워크플로우) | 3-4일 |
| Phase 3 | UX 고도화 (TFJS + 프리뷰) | 3-4일 |
| **Total** | **MVP 2주, 완성판 3주** | |

## 향후 확장 (Phase 4)

- [ ] 이미지 분류 모드 (폴더명=클래스, 바운딩박스 없이)
- [ ] 이상 탐지 모드 (PatchCore 연동, 정상 이미지만으로)
- [ ] 모바일 카메라 직접 촬영 업로드
- [ ] 멀티 사용자 협업 라벨링
- [ ] 자동 라벨링 (pre-trained model로 초기 예측 제공)

---

*문서 버전: v1.0 (2026-04-14)*