LChecker

영상 조건 체크 SaaS — 다중 영상에 대해 사용자 정의 조건의 충족 여부를 Gemini로 검증하고 "확신" / "직접 점검 필요" / "처리 불가" 로 분류. 1차 use case: 임베디드 강의 영상 과제 채점 보조.

아키텍처

프론트엔드 단독 (서버리스) — 브라우저에서 직접 Gemini API 호출. 별도 백엔드 없음.

브라우저
  ├─ 영상 업로드 → base64 인코딩
  ├─ @google/genai SDK
  └─ Gemini API 직접 호출 → 결과 표시

• 프론트엔드: React 18 + Vite + TypeScript + @google/genai
• 호스팅: Vercel (정적 빌드, free tier 충분)
• API 키: VITE_GEMINI_API_KEY 빌드 시 임베드 (제한된 사용자 풀 가정)

핵심 설계 결정

Gemini 호출 옵션

• fps=3.0 — 미세 동작/색상 변화 인식 향상 (기본 1 FPS의 3배)
• media_resolution — env VITE_MEDIA_RESOLUTION 으로 LOW/MEDIUM/HIGH 선택, 기본 MEDIUM
• temperature=0.0 — 동일 입력 → 동일 출력 (greedy decoding, 채점 reproducibility)
• response_schema — Gemini API 측 JSON 구조 강제

단일 호출 + 조건부 응답

• 영상당 호출 1회. 응답 형식 두 가지:
  • 모든 조건 충족 → {classification: "PASS", failedConditions: [], extras: [...]}
  • 하나라도 미충족 → {classification: "REVIEW", failedConditions: [{condition, reason}, ...], extras: []}
• 비대칭 출력: PASS는 통과 사유 미포함 (확신 케이스는 영상 안 봐도 됨), REVIEW는 미충족 사유만 (점검 가이드)

분류 매핑

• PASS + 안전장치 통과 → 확신 (초록)
• REVIEW 또는 모순 → 직접 점검 필요 (주황)
• 영상 크기 한도 초과 또는 API 에러 → 처리 불가 (빨강)

영상 처리

• FFmpeg 미사용. 브라우저에서 raw 영상을 base64 인코딩하여 Gemini에 inline 전달
• Gemini inline 한도: 요청당 ~20MB. 100MB 등 큰 파일은 Gemini API 자체에서 거부 (현재 처리 불가로 surface). >20MB 지원하려면 Gemini File API 추가 구현 필요
• 캐시 미사용: 채점은 매 회차 다른 영상이라 적중률 0

병렬 처리

• 브라우저 비동기 worker pool (기본 영상 수만큼). 영상별로 독립 호출, 한 영상 실패해도 다른 영상은 계속 처리

토큰/비용 추적

• usageMetadata 에서 input/output 토큰 수집 (실측치)
• 비용 환산은 env 단가/환율 기준 추정치 (콘솔 + UI 표시)

로컬 개발

cd frontend
npm install
Copy-Item .env.example .env  # .env 열어서 VITE_GEMINI_API_KEY 채우기
npm run dev
# http://localhost:5173

배포 (Vercel)

1. Vercel에서 이 GitHub 레포 import
2. Root Directory: frontend
3. Framework Preset: Vite (자동 감지)
4. Environment Variables 추가:
   • VITE_GEMINI_API_KEY (필수, Google AI Studio에서 발급)
   • 기타 옵션은 frontend/.env.example 참조
5. Deploy

환경 변수

키	기본값	필수	용도
VITE_GEMINI_API_KEY	-	✓	Google AI Studio API 키
VITE_GEMINI_MODEL	gemini-3.1-pro-preview		모델 ID
VITE_MEDIA_RESOLUTION	MEDIUM		시각 토큰 해상도 (LOW/MEDIUM/HIGH)
VITE_MAX_VIDEO_SIZE_MB	100		영상 크기 상한 (참고: Gemini inline 한도 ~20MB)
VITE_GEMINI_INPUT_PRICE_USD_PER_1M	1.25		비용 환산용
VITE_GEMINI_OUTPUT_PRICE_USD_PER_1M	10.0		비용 환산용
VITE_USD_TO_KRW	1470		비용 환산용

향후 개선 (TODO)

• Gemini File API 통합: >20MB 영상 지원
• 사용자 BYOK (Bring Your Own Key): 런타임에 사용자가 자신의 API 키 입력 (UI 제공)
• 다중 표본 정확도 검증: 90+ 영상으로 통계적 평가