deployment_guide.md

# 🚀 허깅페이스 Spaces 배포 가이드

## 📋 배포 준비사항

### 1. 필수 파일 확인
- `app.py` (메인 애플리케이션)
- `stt_processor.py` (STT 처리 모듈)
- `requirements.txt` (의존성)
- `README.md` (허깅페이스용 설명)

### 2. Google AI API 키 준비
1. [Google AI Studio](https://aistudio.google.com/app/apikey) 접속
2. Google 계정으로 로그인
3. "Create API Key" 클릭
4. 생성된 API 키 복사 (나중에 Hugging Face에서 사용)

## 🔧 허깅페이스 Spaces 배포 단계

### 1단계: Hugging Face 계정 생성
1. [Hugging Face](https://huggingface.co/) 접속
2. 계정 생성 또는 로그인

### 2단계: 새 Space 생성
1. 프로필 페이지에서 "Spaces" 탭 클릭
2. "Create new Space" 버튼 클릭
3. 설정:
   - **Space name**: `stt-speaker-separation` (또는 원하는 이름)
   - **License**: MIT
   - **SDK**: Gradio
   - **Hardware**: CPU basic (무료)
   - **Visibility**: Public

### 3단계: 코드 업로드
다음 방법 중 하나 선택:

#### 방법 A: 웹 인터페이스 사용
1. Space 페이지에서 "Files" 탭 클릭
2. "Upload files" 클릭
3. 다음 파일들을 업로드:
   - `app.py`
   - `stt_processor.py`
   - `requirements.txt`
   - `README.md`

#### 방법 B: Git 사용
```bash
# Space 복제
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# 파일 복사
copy app.py .
copy stt_processor.py .
copy requirements.txt .
copy README.md .

# 커밋 및 푸시
git add .
git commit -m "Initial upload of STT speaker separation app"
git push
```

### 4단계: 환경 변수 설정
1. Space 페이지에서 "Settings" 탭 클릭
2. "Repository secrets" 섹션 찾기
3. "New secret" 클릭
4. 다음 입력:
   - **Name**: `GOOGLE_API_KEY`
   - **Value**: 앞서 복사한 Google AI API 키
5. "Add secret" 클릭

### 5단계: 앱 빌드 및 실행 확인
1. Space가 자동으로 빌드 시작됨
2. 빌드 로그에서 오류 확인
3. 빌드 완료 후 앱 인터페이스 확인

## 🔍 빌드 로그 확인 포인트

### 정상 빌드 시 나타나는 로그:
```
Installing dependencies from requirements.txt...
✓ torch
✓ torchaudio
✓ openai-whisper
✓ google-generativeai
✓ gradio
✓ spaces
```

### 주의해야 할 오류:
- **ModuleNotFoundError**: requirements.txt 확인
- **API Key Error**: 환경 변수 설정 확인
- **CUDA/GPU 오류**: CPU 빌드 환경이므로 정상

## 📊 성능 최적화

### CPU 환경 최적화:
1. Whisper 모델을 "base"로 유지 (더 작은 모델 사용)
2. 배치 처리 대신 단일 파일 처리 사용
3. 메모리 사용량 모니터링

### 사용자 경험 개선:
1. 파일 크기 제한 안내
2. 처리 시간 예상 안내
3. 에러 메시지 명확화

## 🌐 배포 후 공유

### Space URL:
`https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`

### 임베드 코드:
```html
<iframe
    src="https://your-username-your-space-name.hf.space"
    frameborder="0"
    width="850"
    height="450"
></iframe>
```

## 🛠 문제 해결

### 자주 발생하는 문제:

#### 1. API 키 인식 불가
- Settings → Repository secrets에서 `GOOGLE_API_KEY` 확인
- 키에 특수문자나 공백이 없는지 확인

#### 2. 모델 로딩 시간 초과
- Whisper 모델 크기 조정 (`base` → `tiny`)
- 타임아웃 설정 증가

#### 3. 메모리 부족
- 동시 처리 요청 수 제한
- 파일 크기 제한 설정

#### 4. 빌드 실패
- requirements.txt의 패키지 버전 호환성 확인
- Python 버전 호환성 확인

## 📞 지원

- [Hugging Face 포럼](https://discuss.huggingface.co/)
- [Gradio 문서](https://gradio.app/docs/)
- [OpenAI Whisper GitHub](https://github.com/openai/whisper)

## 🎉 배포 완료!

배포가 성공적으로 완료되면:
1. 공개 URL을 통해 누구나 접근 가능
2. 자동으로 SSL 인증서 적용
3. CDN을 통한 전세계 접근 가능
4. 사용량 통계 확인 가능