README_DEPLOYMENT.md

# Lily LLM API 배포 가이드

## 📋 개요

이 문서는 Lily LLM API 서버의 Docker 기반 배포 방법을 설명합니다.

## 🏗️ 아키텍처

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Lily LLM API  │    │     Redis       │    │   Celery Worker │
│   (FastAPI)     │◄──►│   (Message      │◄──►│   (Background   │
│   Port: 8001    │    │    Broker)      │    │    Tasks)       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Flower        │    │   Celery Beat   │    │   Database      │
│   (Monitoring)  │    │   (Scheduler)   │    │   (SQLite)      │
│   Port: 5555    │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 🚀 빠른 시작

### 1. 사전 요구사항

- Docker
- Docker Compose
- 최소 4GB RAM
- 최소 10GB 디스크 공간

### 2. 배포 실행

```bash
# 저장소 클론
git clone <repository-url>
cd lily_generate_package

# 배포 스크립트 실행
chmod +x scripts/deploy.sh
./scripts/deploy.sh deploy
```

### 3. 서비스 확인

```bash
# 서비스 상태 확인
./scripts/deploy.sh status

# 로그 확인
./scripts/deploy.sh logs
```

## 📦 Docker 컨테이너

### 주요 서비스

| 서비스 | 포트 | 설명 |
|--------|------|------|
| lily-llm-api | 8001 | FastAPI 메인 서버 |
| redis | 6379 | 메시지 브로커 및 캐시 |
| celery-worker | - | 백그라운드 작업 처리 |
| celery-beat | - | 스케줄러 |
| flower | 5555 | Celery 모니터링 |

### 환경 변수

```yaml
# API 서버
REDIS_URL: redis://redis:6379
DATABASE_URL: sqlite:///app/data/lily_llm.db
LOG_LEVEL: INFO
CELERY_BROKER_URL: redis://redis:6379/0
CELERY_RESULT_BACKEND: redis://redis:6379/0
```

## 🔧 배포 스크립트

### 사용 가능한 명령어

```bash
# 전체 배포
./scripts/deploy.sh deploy

# 서비스 시작
./scripts/deploy.sh start

# 서비스 중지
./scripts/deploy.sh stop

# 서비스 재시작
./scripts/deploy.sh restart

# 배포 업데이트
./scripts/deploy.sh update

# 로그 확인
./scripts/deploy.sh logs

# 상태 확인
./scripts/deploy.sh status

# 정리
./scripts/deploy.sh cleanup

# 이미지 빌드
./scripts/deploy.sh build
```

## 🧪 테스트

### Docker 배포 테스트

```bash
python scripts/test_docker_deployment.py
```

### 수동 테스트

```bash
# API 상태 확인
curl http://localhost:8001/health

# 모델 목록 확인
curl http://localhost:8001/models

# 텍스트 생성 테스트
curl -X POST http://localhost:8001/generate \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "prompt=안녕하세요&model_id=polyglot-ko-1.3b-chat&max_length=50"
```

## 📊 모니터링

### Flower (Celery 모니터링)

- URL: http://localhost:5555
- 작업 상태, 워커 상태, 성능 메트릭 확인

### API 모니터링

```bash
# 성능 모니터링 시작
curl -X POST http://localhost:8001/monitoring/start

# 성능 상태 확인
curl http://localhost:8001/monitoring/status

# 시스템 건강 상태
curl http://localhost:8001/monitoring/health
```

## 🔒 보안

### 환경 변수 관리

```bash
# .env 파일 생성
cat > .env << EOF
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key
DATABASE_URL=sqlite:///app/data/lily_llm.db
REDIS_URL=redis://redis:6379
EOF
```

### 방화벽 설정

```bash
# 필요한 포트만 열기
sudo ufw allow 8001  # API 서버
sudo ufw allow 5555  # Flower 모니터링
```

## 📈 성능 최적화

### 리소스 제한

```yaml
# docker-compose.yml에 추가
services:
  lily-llm-api:
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2.0'
        reservations:
          memory: 2G
          cpus: '1.0'
```

### 캐시 설정

```python
# Redis 캐시 활용
import redis
from functools import lru_cache

redis_client = redis.Redis(host='redis', port=6379, db=0)

@lru_cache(maxsize=128)
def cached_model_response(prompt, model_id):
    # 캐시된 응답 반환
    pass
```

## 🚨 문제 해결

### 일반적인 문제

#### 1. 메모리 부족

```bash
# 메모리 사용량 확인
docker stats

# 불필요한 컨테이너 정리
docker system prune -f
```

#### 2. API 응답 없음

```bash
# 컨테이너 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs lily-llm-api

# 컨테이너 재시작
docker-compose restart lily-llm-api
```

#### 3. Redis 연결 실패

```bash
# Redis 컨테이너 상태 확인
docker-compose logs redis

# Redis 재시작
docker-compose restart redis
```

### 로그 분석

```bash
# 실시간 로그 확인
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f lily-llm-api

# 오류 로그만 확인
docker-compose logs | grep ERROR
```

## 🔄 업데이트

### 코드 업데이트

```bash
# 최신 코드 가져오기
git pull origin main

# 배포 업데이트
./scripts/deploy.sh update
```

### 모델 업데이트

```bash
# 모델 파일 교체
cp new_model.safetensors ./models/

# 서비스 재시작
docker-compose restart lily-llm-api
```

## 📚 추가 문서

- [API 문서](http://localhost:8001/docs)
- [성능 가이드](./PERFORMANCE.md)
- [보안 가이드](./SECURITY.md)
- [모니터링 가이드](./MONITORING.md)

## 🤝 지원

문제가 발생하면 다음을 확인하세요:

1. 로그 파일 확인
2. 시스템 리소스 확인
3. 네트워크 연결 확인
4. 환경 변수 설정 확인

## 📝 변경 로그

### v1.0.0 (2025-08-04)
- 초기 Docker 배포 설정
- CI/CD 파이프라인 구축
- 모니터링 시스템 추가
- 보안 설정 강화