# AI_Auto_Blur 실습 Lab: 실행 · 배포 · 모델 출처

## 로컬 실행

저장소 루트에서 아래 명령으로 실행한다.

```powershell
# 사진을 전송받는 API 없이 정적 파일만 제공하는 로컬 서버
python -m http.server 5173 --bind 127.0.0.1 --directory 2026-09-13-auto-blur-site
```

브라우저에서 http://127.0.0.1:5173 접속. HTML 파일 더블클릭 방식(file://)은 ES 모듈·모델 로딩·카메라 보안 조건을 만족하지 않으므로 사용하지 않는다. 현재 구현은 npm 설치나 빌드 과정이 필요 없다.

## GitHub → Vercel

1. GitHub 저장소에 `2026-09-13-auto-blur-site` 폴더 및 README를 추가한다. 개인 사진은 포함하지 않는다.
2. Vercel에서 해당 GitHub 저장소를 Import한다.
3. Root Directory: `2026-09-13-auto-blur-site`.
4. Framework Preset: **Other**. Build Command는 비움. Output Directory는 **.** (Root Directory 자체). Install Command는 비움.
5. 배포 후 HTTPS 주소에서 업로드, 실제 모델 탐지, 권한 허용·거부, 촬영 후 카메라 종료, PNG 저장을 확인한다.
6. 연결한 브랜치의 변경 사항을 푸시하면 Vercel이 새 배포를 수행한다.

사이트 폴더의 내용만 저장소 루트에 올린 경우 Root Directory는 저장소 루트로 설정한다. 런타임과 모델은 함께 올려야 한다. `index.html`은 정적 호스팅의 진입 파일명이고, 나머지 직접 작성 파일은 날짜 접두사를 사용한다.

소스 저장소는 https://github.com/roughkyo/Ai_Auto_blur 이며, Vercel 계정 연결·배포는 별도 단계다. 정적 HTML은 별도 빌드 단계 없이 배포할 수 있다. [Vercel 공식 빌드 문서](https://vercel.com/docs/builds), [설정 문서](https://vercel.com/docs/builds/configure-a-build).

## 모델 계약과 출처

- 모델: Ultralytics YOLOv8n, COCO 객체 탐지.
- 배포본: [webml/yolov8n](https://huggingface.co/webml/yolov8n/tree/85bc8d7ab30d4065a41909d756c42819b67b4388).
- 저장소 고정 커밋: `85bc8d7ab30d4065a41909d756c42819b67b4388`.
- 원래 파일: `onnx/yolov8n.onnx`.
- 로컬 파일: `2026-09-13-yolov8n.onnx`, 12,823,574 bytes.
- SHA-256: `190ba5f1e61411a001683e349d6b2cdb0804c0dc67a5e34cd8ff6fd00ee54b4d`.
- 모델 안 메타데이터: Ultralytics 8.2.66, task=detect, imgsz=[640,640], names의 0='person', license=AGPL-3.0.
- 입력: `images`, float32 [1,3,640,640]. RGB / 255, CHW, 비율 유지 letterbox, 여백 114.
- 출력: `output0`, [1,84,8400]. 첫 4채널 중심 x/y/폭/높이, 뒤 80채널 클래스 점수. 사람은 채널 4.
- 후처리: 사람 점수 >= 선택 임계값, 높은 점수 순 NMS, IoU > 선택 기준이면 억제. 유효 면적이 없는 상자는 제외.
- 신뢰도 필터 전에 모든 유효 사람 후보를 보존한다. 표시만 상위 60개 제한하며 NMS 계산에 이 제한을 적용하지 않는다.

이 파일은 Ultralytics 공식 배포 저장소가 아닌 WebML의 ONNX 변환 배포본이다. 파일 해시와 내장 메타데이터, 실제 브라우저 출력 형식을 확인했다. 가중치의 학습 이력을 독립적으로 재현한 것은 아니다.

## 라이선스

YOLOv8의 모델·소프트웨어 사용 조건은 [Ultralytics 라이선스 안내](https://www.ultralytics.com/license) 및 [YOLOv8 공식 문서](https://docs.ultralytics.com/models/yolov8/)를 따른다. 로컬 모델도 AGPL-3.0 메타데이터를 포함한다. 교육용이라는 이유만으로 면제되지 않는다. 원격 배포 전에 프로젝트 소스 제공과 적용 라이선스를 확정해야 한다. 이번 작업에서는 사용자가 작성한 전체 프로젝트에 임의의 라이선스를 지정하지 않았다.

실행 라이브러리: ONNX Runtime Web **1.20.1**, [npm 원본 배포](https://www.npmjs.com/package/onnxruntime-web/v/1.20.1), MIT. `2026-09-13-runtime/2026-09-13-LICENSE.txt`에 라이선스를 보존했다. 내부 참조가 있는 배포 파일의 이름은 그대로 유지했다.

## 사진과 카메라

- 사용자 사진·촬영 이미지를 외부 AI API나 서버로 전송하는 코드는 없다. 서버는 모델·런타임·소스 정적 파일을 제공한다.
- 업로드 이미지는 메모리에서만 처리. 긴 변 1600px까지, 입력 파일 15MB 이하, 디코드 후 2천만 픽셀 이하.
- 카메라 사용은 명시적인 버튼 클릭과 브라우저 권한 허용이 필요하다. 마이크는 요청하지 않는다.
- 촬영·닫기·사진 교체·페이지 이탈 시 카메라 트랙을 종료한다.
- 카메라 사용에는 HTTPS 또는 localhost가 필요하다. [MDN getUserMedia 문서](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia).
- 저장된 결과는 작업 해상도 PNG이며 탐지선은 포함하지 않는다. 원본 비교는 화면 관찰 기능이다.

## 교육용 데이터

기본 샘플은 사용자가 제공한 을사오적.jpg의 복사본이다. 탐지 실행 버튼을 눌러 실제 YOLO와 얼굴 모델 결과를 얻는다. 기존 색상 시험판과 임의 점수는 제거했다.

사이트 외부의 `2026-09-13-검증용-bus.jpg`는 [Ultralytics 저장소 예제](https://github.com/ultralytics/ultralytics/blob/main/ultralytics/assets/bus.jpg)에서 내려받은 로컬 검증 자료다. 사이트 배포 폴더에는 포함하지 않았다. 이를 사용자 사진이나 자체 제작 사진으로 표시하지 않는다.

## 현재 범위

포함: 단계별 진행, 사진 업로드·촬영, 실제 사람 상자 및 얼굴 탐지, 신뢰도/NMS 조절, 후보별 사유, 블러/모자이크, 수동 보정, PNG 저장, 예측 활동, 개념 문제 4개(5지선다형 3개·주관식 1개).

미포함: 동영상·실시간 추적, 실제 특징 텐서 표시, 슬라이딩 윈도우 고급 비교 실험, 교사 정답 사진 묶음과 저장된 실제 추론 재생. 샘플 사진은 로컬 파일로 제공되지만 실제 추론 오프라인 재방문 캐시는 구현하지 않았다.


## v3 얼굴 모델 추가

- MediaPipe Tasks Vision 0.10.22-rc.20250304, Apache-2.0 런타임. 라이선스는 2026-09-13-face-runtime/2026-09-13-LICENSE.txt에 보존.
- Google BlazeFace short-range float16 version 1. 공식 파일: https://storage.googleapis.com/mediapipe-models/face_detector/blaze_face_short_range/float16/1/blaze_face_short_range.tflite
- SHA-256: b4578f35940bf5a1a655214a1cce5cab13eba73c1297cd78e1a04c2380b0152f
- 공식 사용 안내: https://ai.google.dev/edge/mediapipe/solutions/vision/face_detector/web_js
- 얼굴 점수 기준 0.50. 전체 사진 및 느슨한 사람 후보 영역을 분석하고, 최종 사람 상자에 중심이 포함되는 얼굴을 가린다.
- 전체 단계 자동 재생은 제거. 후보 예측 단계의 느린 관찰은 계산된 결과를 펼쳐 보는 설명이며 실제 모델 내부 계산의 시간 순서가 아니다.