DEPLOYMENT_GUIDE.md

# Lily LLM API - Hugging Face Spaces 배포 가이드

## 🚀 배포 단계별 가이드

### 1. 사전 준비

#### 1.1 Hugging Face 계정 및 토큰
1. [Hugging Face](https://huggingface.co) 계정 생성
2. [Settings > Access Tokens](https://huggingface.co/settings/tokens)에서 Write 권한 토큰 생성
3. 토큰을 안전한 곳에 저장

#### 1.2 필요한 파일들 확인
- `Dockerfile.huggingface` - Docker 설정
- `app_huggingface.py` - 진입점
- `requirements_full.txt` - 의존성 패키지
- `README_huggingface.md` - 프로젝트 설명
- `.dockerignore` - Docker 빌드 제외 파일

### 2. Hugging Face Spaces 생성

#### 2.1 Space 생성
1. [Hugging Face Spaces](https://huggingface.co/spaces) 접속
2. "Create new Space" 클릭
3. 다음 설정으로 Space 생성:
   - **Owner**: 본인 계정
   - **Space name**: `lily-llm-api`
   - **License**: `MIT`
   - **Select the Space SDK**: `Docker`
   - **Space hardware**: `CPU basic` (무료) 또는 `CPU upgrade` (유료, 더 빠름)
   - **Visibility**: `Public` 또는 `Private`

#### 2.2 Space 설정
Space 생성 후 Settings에서:
- **Variables**: 필요한 환경 변수 설정
- **Secrets**: API 키 등 민감한 정보 설정

### 3. 코드 배포

#### 3.1 Git 방식 (권장)

```bash
# 1. Space 저장소 클론
git clone https://huggingface.co/spaces/YOUR_USERNAME/lily-llm-api
cd lily-llm-api

# 2. 필요한 파일들 복사
cp /path/to/lily_generate_package/Dockerfile.huggingface ./Dockerfile
cp /path/to/lily_generate_package/app_huggingface.py ./
cp /path/to/lily_generate_package/requirements_full.txt ./requirements.txt
cp /path/to/lily_generate_package/README_huggingface.md ./README.md
cp /path/to/lily_generate_package/.dockerignore ./

# 3. 프로젝트 소스 코드 복사
cp -r /path/to/lily_generate_package/lily_llm_api ./
cp -r /path/to/lily_generate_package/lily_llm_core ./
cp -r /path/to/lily_generate_package/lily_llm_utils ./

# 4. Git 커밋 및 푸시
git add .
git commit -m "Initial deployment of Lily LLM API"
git push
```

#### 3.2 웹 인터페이스 방식

1. Hugging Face Space 페이지에서 "Files" 탭 클릭
2. "Add file" > "Upload files" 클릭
3. 필요한 파일들을 드래그 앤 드롭으로 업로드
4. 커밋 메시지 작성 후 "Commit changes" 클릭

### 4. 환경 변수 설정

Space Settings > Variables에서 다음 환경 변수들 설정:

```bash
# 서버 설정
HOST=0.0.0.0
PORT=7860
PYTHONPATH=/app
PYTHONUNBUFFERED=1

# 모델 설정
DEFAULT_MODEL=kanana-1.5-v-3b-instruct
MAX_NEW_TOKENS=256
TEMPERATURE=0.7

# 캐시 설정
TRANSFORMERS_CACHE=/app/cache/transformers
HF_HOME=/app/cache/huggingface
TORCH_HOME=/app/cache/torch
TOKENIZERS_PARALLELISM=false

# 성능 최적화
OMP_NUM_THREADS=1
MKL_NUM_THREADS=1
```

### 5. 배포 확인

#### 5.1 빌드 로그 확인
1. Space 페이지에서 "Logs" 탭 클릭
2. Docker 빌드 및 실행 로그 확인
3. 오류 발생 시 로그를 통해 문제 해결

#### 5.2 API 테스트

배포 완료 후 다음과 같이 테스트:

```python
import requests

# Health check
response = requests.get("https://YOUR_USERNAME-lily-llm-api.hf.space/health")
print(response.json())

# 텍스트 생성 테스트
response = requests.post(
    "https://YOUR_USERNAME-lily-llm-api.hf.space/generate",
    data={"prompt": "안녕하세요! 테스트 메시지입니다."}
)
print(response.json())
```

### 6. 성능 최적화

#### 6.1 하드웨어 업그레이드
- 무료 CPU basic: 제한적 성능
- 유료 CPU upgrade: 더 빠른 처리
- GPU 옵션: 대용량 모델 처리 시 필요

#### 6.2 모델 최적화
```python
# app_huggingface.py에서 모델 로딩 최적화
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,  # 메모리 사용량 감소
    device_map="auto",          # 자동 디바이스 배치
    low_cpu_mem_usage=True      # CPU 메모리 최적화
)
```

### 7. 문제 해결

#### 7.1 일반적인 오류

**메모리 부족 오류**
```bash
# requirements.txt에서 불필요한 패키지 제거
# 모델 크기 축소 또는 양자화 적용
```

**빌드 시간 초과**
```bash
# .dockerignore 파일로 불필요한 파일 제외
# multi-stage build 사용으로 빌드 최적화
```

**모듈 import 오류**
```bash
# PYTHONPATH 환경 변수 확인
# requirements.txt 의존성 확인
```

#### 7.2 로그 분석
```bash
# 빌드 로그에서 오류 찾기
grep -i error build.log

# 런타임 로그에서 문제 확인
tail -f app.log
```

### 8. Railway Hearth Chat 연동 준비

배포된 Hugging Face Space URL을 기록해두세요:
```
https://YOUR_USERNAME-lily-llm-api.hf.space
```

이 URL을 Hearth Chat의 AI 설정에서 Lily LLM API URL로 사용하게 됩니다.

### 9. 유지보수

#### 9.1 업데이트 배포
```bash
# 코드 수정 후
git add .
git commit -m "Update: description of changes"
git push
```

#### 9.2 모니터링
- Space 대시보드에서 사용량 모니터링
- 로그를 통한 오류 추적
- 성능 메트릭 확인

---

## 📞 지원

배포 중 문제가 발생하면:
1. Hugging Face 공식 문서 참조
2. Community 포럼에서 도움 요청
3. GitHub Issues를 통한 기술 지원