# task-932.3: 로컬 Whisper GPU 서비스 구축 + InsuWiki 유튜브 파이프라인 통합 (한정위임)

## 배경
- task-932.1: faster-whisper로 유튜브 음성→텍스트 파이프라인 검증 완료
- task-932.2: GTX 1060 GPU 벤치마크 완료 → medium+int8+cuda 최적 (CPU 대비 6.3배, 5분 오디오 29초)
- InsuWiki: 현재 OpenAI Whisper API 사용 (유료, 25MB 제한, whisperStt.ts)
- 목표: 로컬 faster-whisper GPU 서비스를 만들고, InsuWiki 포함 모든 유튜브 영상 요약에 자동 적용

## 현재 InsuWiki 유튜브 파이프라인 구조
- **크롤링 함수**: `/home/jay/projects/insuwiki/functions/src/crawlYoutubeChannels.ts`
  - 6시간마다 Cloud Scheduler 실행
  - 2개 채널: 보험명의정닥터(@보험명의정닥터), ins-king(@ins-king)
  - 자막 3단계 fallback: YouTube 자막 → OpenAI Whisper API → 제목+설명
- **Whisper STT**: `/home/jay/projects/insuwiki/functions/src/whisperStt.ts`
  - OpenAI Whisper API 사용 (OPENAI_API_KEY, 25MB 제한)
- **요약 모델**: Gemini 2.5 Flash

## 작업 범위

### Step 1: 로컬 Whisper GPU HTTP 서비스 구축
- **위치**: `/home/jay/workspace/services/whisper-gpu/`
- **기술**: Python FastAPI + uvicorn
- **핵심 엔드포인트**:
  ```
  POST /v1/transcribe
    - body: multipart/form-data (audio file) 또는 JSON (audio_url)
    - params: language (default: ko), model (default: medium), format (text|json|srt|vtt)
    - response: { text: string, segments: [{start, end, text}], language: string, duration: float }

  GET /v1/health
    - response: { status: ok, model: medium, device: cuda, gpu_memory_used_mb: int }
  ```
- **모델 설정**:
  - 기본: medium + int8 + cuda (최적 조합, VRAM 878MB)
  - 영상 길이별 자동 모델 선택:
    - 30분 미만: small (12초/5분, VRAM 366MB)
    - 30분~2시간: medium (29초/5분, VRAM 878MB)
    - 2시간 이상: medium (동일, 청크 분할 처리)
- **모델 프리로딩**: 서버 시작 시 medium 모델 미리 로드 (첫 요청 지연 방지)
- **동시 요청 처리**: asyncio + Lock (GPU 1개이므로 순차 처리)
- **포트**: 8200

### Step 2: 서비스 시작/관리 스크립트
- **시작 스크립트**: `/home/jay/workspace/scripts/start-whisper-gpu.sh`
  ```bash
  #!/bin/bash
  cd /home/jay/workspace/services/whisper-gpu
  # CLAUDECODE 환경변수 제거 (중요!)
  env -u CLAUDECODE python3 -m uvicorn server:app --host 0.0.0.0 --port 8200
  ```
- **systemd 서비스** (선택): `/etc/systemd/system/whisper-gpu.service`

### Step 3: 범용 유튜브 음성 추출 CLI 스크립트
- **위치**: `/home/jay/workspace/scripts/youtube-transcribe.py`
- **기능**:
  1. yt-dlp로 오디오 다운로드 (WAV 변환)
  2. 로컬 Whisper GPU 서비스 호출 (http://localhost:8200)
  3. 결과 출력 (text/json/srt)
- **사용법**:
  ```bash
  python3 scripts/youtube-transcribe.py --url "https://youtube.com/watch?v=..." [--format text] [--output /path/to/output.txt]
  python3 scripts/youtube-transcribe.py --url "..." --format json  # 타임스탬프 포함
  ```
- **fallback**: 로컬 서비스 불가 시 OpenAI API fallback (경고 로그)

### Step 4: InsuWiki 통합 — whisperStt.ts 수정
- **파일**: `/home/jay/projects/insuwiki/functions/src/whisperStt.ts`
- **변경 내용**:
  - 기존 OpenAI Whisper API 호출 전에 **로컬 Whisper GPU 서비스 호출 시도**
  - 로컬 서비스 URL: `http://localhost:8200/v1/transcribe` (또는 Tailscale IP)
  - fallback 순서 변경:
    1. YouTube 자막 (기존 유지)
    2. **로컬 Whisper GPU** (신규 — 무료, 25MB 제한 없음, GPU 가속)
    3. OpenAI Whisper API (기존 — 최종 fallback)
    4. 제목+설명 (기존 유지)
  - 25MB 파일 크기 제한 제거 (로컬은 제한 없음)
  - 타임아웃: 로컬 서비스 300초 (긴 영상 대응)

### Step 5: InsuWiki crawlYoutubeChannels.ts 확인
- **파일**: `/home/jay/projects/insuwiki/functions/src/crawlYoutubeChannels.ts`
- whisperStt 호출 부분이 수정된 whisperStt.ts를 자동으로 사용하는지 확인
- 추가 수정 필요 시 반영

### Step 6: 테스트 검증
- Whisper GPU 서비스 단독 테스트 (health check + 샘플 오디오)
- youtube-transcribe.py CLI 테스트 (실제 유튜브 영상)
- InsuWiki whisperStt.ts 통합 테스트 (자막 없는 영상)
- 기존 자막 있는 영상이 기존대로 처리되는지 회귀 테스트

## 참조 자료
- task-932.1 보고서: `memory/reports/task-932.1.md` (파이프라인 검증)
- task-932.2 보고서: `memory/reports/task-932.2.md` (GPU 벤치마크)
- 벤치마크 스크립트: `/home/jay/workspace/teams/dev4/task-932.2/benchmark.py`
- InsuWiki whisperStt: `/home/jay/projects/insuwiki/functions/src/whisperStt.ts`
- InsuWiki 크롤러: `/home/jay/projects/insuwiki/functions/src/crawlYoutubeChannels.ts`

## 주의사항
- CLAUDECODE 환경변수 필터링 필수 (subprocess 호출 시)
- InsuWiki Cloud Functions에서 localhost:8200 접근 가능 여부 확인 (같은 서버인지, 아니면 Tailscale IP 사용)
- 기존 OpenAI Whisper API 로직은 삭제하지 말고 fallback으로 유지
- 기존 YouTube 자막 추출 로직 절대 수정 금지 (1순위 그대로)
- faster-whisper, yt-dlp, ffmpeg은 이미 설치되어 있음

## 산출물
- Whisper GPU HTTP 서비스 (`services/whisper-gpu/`)
- 서비스 시작 스크립트 (`scripts/start-whisper-gpu.sh`)
- 유튜브 음성 추출 CLI (`scripts/youtube-transcribe.py`)
- InsuWiki whisperStt.ts 수정 (로컬 Whisper 우선 호출)
- 테스트 결과 보고서