DEPLOYMENT_CHECKLIST.md

# 🚀 Lily LLM API - Hugging Face Spaces 배포 체크리스트

## ✅ 배포 전 체크리스트

### 📋 필수 파일 확인
- [ ] `Dockerfile.huggingface` - Docker 설정 파일
- [ ] `app_huggingface.py` - Hugging Face Spaces 진입점
- [ ] `requirements_full.txt` - 완전한 의존성 패키지 목록
- [ ] `README_huggingface.md` - 프로젝트 설명 문서
- [ ] `.dockerignore` - Docker 빌드 제외 파일 목록

### 🔧 프로젝트 구조 확인
- [ ] `lily_llm_api/` - FastAPI 서버 코드
- [ ] `lily_llm_core/` - 핵심 RAG 및 AI 로직
- [ ] `lily_llm_utils/` - 유틸리티 함수들
- [ ] 모델 파일들이 올바른 경로에 위치

### 🌐 Hugging Face 계정 준비
- [ ] Hugging Face 계정 생성 완료
- [ ] Write 권한이 있는 Access Token 생성
- [ ] 토큰을 안전한 곳에 저장

## 🚀 배포 단계

### 1단계: Hugging Face Space 생성
- [ ] [Hugging Face Spaces](https://huggingface.co/spaces) 접속
- [ ] "Create new Space" 클릭
- [ ] 다음 설정으로 생성:
  - [ ] **Space name**: `lily-llm-api` (또는 원하는 이름)
  - [ ] **SDK**: `Docker` 선택
  - [ ] **Hardware**: `CPU basic` (무료) 또는 `CPU upgrade` (유료)
  - [ ] **Visibility**: `Public` 또는 `Private`

### 2단계: 파일 업로드
- [ ] Space 저장소 클론 또는 웹 인터페이스 사용
- [ ] 필수 파일들을 올바른 이름으로 복사:
  - [ ] `Dockerfile.huggingface` → `Dockerfile`
  - [ ] `requirements_full.txt` → `requirements.txt`
  - [ ] `README_huggingface.md` → `README.md`
- [ ] 소스 코드 디렉토리들 복사
- [ ] Git commit 및 push (Git 방식 사용 시)

### 3단계: 환경 변수 설정
Space Settings > Variables에서 설정:
- [ ] `HOST=0.0.0.0`
- [ ] `PORT=7860`
- [ ] `PYTHONPATH=/app`
- [ ] `PYTHONUNBUFFERED=1`
- [ ] `TOKENIZERS_PARALLELISM=false`
- [ ] `OMP_NUM_THREADS=1`
- [ ] `MKL_NUM_THREADS=1`

### 4단계: 빌드 및 배포 확인
- [ ] Space 페이지에서 빌드 로그 확인
- [ ] 오류 발생 시 로그 분석 및 수정
- [ ] 빌드 완료 후 앱 실행 확인

## 🧪 테스트 체크리스트

### API 기본 테스트
- [ ] Health Check: `GET /health`
```bash
curl https://YOUR_USERNAME-lily-llm-api.hf.space/health
```

- [ ] 모델 목록: `GET /models`
```bash
curl https://YOUR_USERNAME-lily-llm-api.hf.space/models
```

- [ ] 텍스트 생성: `POST /generate`
```bash
curl -X POST https://YOUR_USERNAME-lily-llm-api.hf.space/generate \
  -F "prompt=안녕하세요! 테스트 메시지입니다."
```

### 고급 기능 테스트
- [ ] 이미지 처리 테스트
- [ ] RAG 시스템 테스트 (문서 업로드 및 질의)
- [ ] 멀티모달 기능 테스트

### 성능 테스트
- [ ] 응답 시간 측정
- [ ] 동시 요청 처리 확인
- [ ] 메모리 사용량 모니터링

## 🔗 Hearth Chat 연동 준비

### URL 기록
배포 완료 후 다음 URL 기록:
- [ ] Hugging Face Space URL: `https://YOUR_USERNAME-lily-llm-api.hf.space`
- [ ] API 문서 URL: `https://YOUR_USERNAME-lily-llm-api.hf.space/docs`

### Hearth Chat 설정 업데이트
- [ ] AI 설정 모달에 Lily LLM 옵션 추가
- [ ] 백엔드 consumers.py에 Hugging Face API 호출 로직 추가
- [ ] 환경 변수에 Lily LLM API URL 설정

## ❌ 문제 해결

### 일반적인 오류와 해결책

**빌드 실패**
- [ ] `requirements.txt` 의존성 확인
- [ ] `Dockerfile` 문법 오류 확인
- [ ] `.dockerignore` 파일 확인

**메모리 부족**
- [ ] 불필요한 패키지 제거
- [ ] 모델 크기 최적화
- [ ] Hardware 업그레이드 고려

**모듈 Import 오류**
- [ ] `PYTHONPATH` 환경 변수 확인
- [ ] 파일 경로 및 구조 확인
- [ ] 의존성 패키지 버전 확인

**API 응답 없음**
- [ ] 포트 설정 확인 (7860)
- [ ] 방화벽 설정 확인
- [ ] 로그에서 오류 메시지 확인

## 📊 모니터링 설정

### 배포 후 모니터링
- [ ] Space 대시보드에서 사용량 확인
- [ ] 로그 정기적 확인
- [ ] 성능 메트릭 모니터링
- [ ] 사용자 피드백 수집

### 유지보수 계획
- [ ] 정기적 업데이트 계획 수립
- [ ] 백업 전략 수립
- [ ] 장애 대응 계획 수립

---

## 🎉 배포 완료!

모든 체크리스트 항목을 완료하면 Lily LLM API가 Hugging Face Spaces에서 성공적으로 실행됩니다.

**다음 단계**: [HEARTH_CHAT_INTEGRATION.md](./HEARTH_CHAT_INTEGRATION.md)를 참조하여 Railway Hearth Chat과 연동을 진행하세요.

---

## 📞 지원

배포 중 문제가 발생하면:
1. 로그 확인 및 분석
2. [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) 상세 가이드 참조
3. Hugging Face Community 포럼 활용
4. GitHub Issues를 통한 기술 지원