# YouTube 요약 파이프라인 서버 구현

## 배경
- task-1094.1: Whisper GPU 서비스에 `/v1/youtube-transcribe` 엔드포인트 추가 + InnerTube API 업데이트 완료 (머지 완료)
- task-1095.1: 에이전트 미팅에서 아키텍처 합의 완료
- 합의 핵심: Cloud Functions 폐기 → 서버 Python 파이프라인으로 전환

## 미팅 합의 요약 (task-1095.1)
- 미팅 기록 상세: `/home/jay/workspace/memory/meetings/2026-03-26-youtube-knowledge-pipeline.md`
- 보고서: `/home/jay/workspace/memory/reports/task-1095.1.md`

## 구현 범위

### 1. 서버 Python 파이프라인 메인 스크립트
**경로**: `/home/jay/projects/insuwiki/scripts/youtube-pipeline/`

**파이프라인 흐름**:
```
크론 6시간 → YouTube Data API v3로 등록 채널의 신규 영상 체크
→ 전사 3-tier:
  1순위: YouTube 공식 자막 (InnerTube WEB→TVHTML5 fallback, task-1094.1 구현 참조)
  2순위: Whisper STT (localhost:8200/v1/youtube-transcribe, yt-dlp 기반)
  3순위: 제목+설명 fallback (이 경우 요약 생성 금지)
→ Gemini 2.5 Flash 요약 (B+C 조합)
  - B: 구조화된 요약 (1000~2000자): 주제 / 핵심 포인트 3~5개 / 언급된 상품·제도 / 결론
  - C: 전사 원문도 Drive에 별도 보관
  - ★ 제목+설명만인 영상(3순위 fallback)은 요약 생성 금지
→ Google Drive 업로드 (전사 파일 + 요약 파일)
→ Firestore youtube_knowledge 메타데이터 저장
→ insurance_chunks에 sourceType: 'youtube'로 직접 저장 (승인 큐 없음)
→ Telegram 처리 결과 보고
```

### 2. 핵심 설계 원칙

**승인 큐 없음**: InsuWiki에 이미 4단계 출처 신뢰 체계가 구현돼 있음
- policy(1순위) > newsletter(2순위) > wiki(3순위) > youtube(4순위)
- 유튜브는 단독 인용 금지, 약관 상충 시 경고 배너
- 따라서 파이프라인 처리 완료 즉시 insurance_chunks에 저장

**요약 수준 (B+C 조합)**:
- 구조화된 요약 (insurance_chunks + Drive 요약 파일): 주제, 핵심 포인트 3~5개, 언급 상품/제도, 결론
- 전사 원문 (Drive 전사 파일): 원문 보관용, 나중에 더 깊이 활용 시 사용
- ★ 제목+설명만인 영상은 insurance_chunks 저장 금지, Drive에만 메타 기록

### 3. Firestore 연동
- Python firebase-admin SDK 사용
- 서비스 계정 키: InsuWiki 프로젝트 firebase-adminsdk 키 사용
- InsuWiki .env.local에서 필요한 환경변수 참조: `/home/jay/projects/insuwiki/.env.local`
- 컬렉션: youtube_knowledge, insurance_chunks
- insurance_chunks 스키마 참조: `/home/jay/projects/insuwiki/nextapp/src/types/firestore.ts` line 295-308

### 4. Google Drive 연동
- Python google-api-python-client
- OAuth 인증: InsuWiki .env.local의 DRIVE_CLIENT_ID, DRIVE_CLIENT_SECRET, DRIVE_REFRESH_TOKEN 사용
- 기존 폴더 구조 유지: `04_유튜브요약/` 하위에 채널별 폴더
- 전사 파일: `04_유튜브요약/<채널명>/<영상제목>_전사.md`
- 요약 파일: `04_유튜브요약/<채널명>/<영상제목>_요약.md` (기존과 동일)
- 처리 로그: `04_유튜브요약/_처리로그/YYYY-MM-DD_크롤링로그.md`

### 5. 채널 목록 관리
- 기존 crawlYoutubeChannels.ts에서 채널 목록 추출
- Firestore youtube_channels 컬렉션 또는 로컬 config 파일로 관리
- 기존 채널 확인: `/home/jay/projects/insuwiki/functions/src/crawlYoutubeChannels.ts`에서 채널 ID 목록 추출

### 6. Gemini 2.5 Flash 호출
- Google AI SDK (google-generativeai) 사용
- API 키: InsuWiki .env.local의 GOOGLE_AI_API_KEY 또는 GEMINI_API_KEY 참조
- 모델: gemini-2.5-flash
- 요약 프롬프트: 보험 전문가가 읽기 좋은 구조화된 요약 생성

### 7. 임베딩 생성 (insurance_chunks 저장용)
- Gemini Text Embedding API 사용 (768차원)
- 기존 pdfIndexing.ts와 동일한 임베딩 모델 사용
- 모델명 확인: `/home/jay/projects/insuwiki/functions/src/pdfIndexing.ts`에서 embedding 모델 확인

### 8. Whisper 서비스 연동
- URL: `http://localhost:8200/v1/youtube-transcribe`
- POST, JSON body: `{"video_id": "...", "language": "ko"}`
- 응답: `{"text": "...", "source": "whisper_local_ytdlp", "duration": ...}`
- Health check: `GET http://localhost:8200/health` (파이프라인 시작 전 확인)

### 9. Telegram 보고
- 파이프라인 완료 후 처리 결과를 Telegram으로 전송
- cokacdir 명령어 사용: `"/usr/local/bin/cokacdir" --sendfile <로그파일> --chat 6937032012 --key c119085addb0f8b7`
- 또는 처리 결과를 간략히 출력 (채널별 처리 건수, 성공/실패)

### 10. 크론 등록
- 파이프라인 스크립트 완성 후 6시간 간격 크론 등록
- `crontab -e`로 등록 또는 systemd timer

## 파일 구조
```
/home/jay/projects/insuwiki/scripts/youtube-pipeline/
├── __init__.py
├── main.py              # 메인 파이프라인 오케스트레이터
├── youtube_api.py        # YouTube Data API v3 연동
├── transcriber.py        # 3-tier 전사 (자막→Whisper→fallback)
├── summarizer.py         # Gemini 2.5 Flash 요약
├── drive_uploader.py     # Google Drive 업로드
├── firestore_writer.py   # Firestore 저장 (youtube_knowledge + insurance_chunks)
├── config.py             # 환경변수, 채널 목록
├── requirements.txt      # 의존성
└── tests/
    ├── test_transcriber.py
    ├── test_summarizer.py
    └── test_drive_uploader.py
```

## 검증
1. 단위 테스트 전체 통과
2. 실제 영상 1개로 end-to-end 테스트 (공개 영상)
3. Drive 업로드 확인 (전사 + 요약 + 처리 로그)
4. Firestore 저장 확인 (youtube_knowledge + insurance_chunks)
5. Whisper 서비스 health check 정상
6. pyright 에러 0건

## 참조 코드
- Whisper 서비스: `/home/jay/workspace/services/whisper-gpu/server.py`
- 기존 파이프라인 (참고용, 대체 대상): `/home/jay/projects/insuwiki/functions/src/crawlYoutubeChannels.ts`
- whisperStt: `/home/jay/projects/insuwiki/functions/src/whisperStt.ts`
- Firestore 타입: `/home/jay/projects/insuwiki/nextapp/src/types/firestore.ts`
- 기존 요약 업로드 스크립트: `/home/jay/projects/insuwiki/scripts/youtube-upload-summary.ts`