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. 배포 실행

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

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

3. 서비스 확인

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

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

📦 Docker 컨테이너

주요 서비스

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

환경 변수

# 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

🔧 배포 스크립트

사용 가능한 명령어

# 전체 배포
./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 배포 테스트

python scripts/test_docker_deployment.py

수동 테스트

# 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 모니터링

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

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

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

🔒 보안

환경 변수 관리

# .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

방화벽 설정

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

📈 성능 최적화

리소스 제한

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

캐시 설정

# 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. 메모리 부족

# 메모리 사용량 확인
docker stats

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

2. API 응답 없음

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

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

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

3. Redis 연결 실패

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

# Redis 재시작
docker-compose restart redis

로그 분석

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

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

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

🔄 업데이트

코드 업데이트

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

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

모델 업데이트

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

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

📚 추가 문서

• API 문서
• 성능 가이드
• 보안 가이드
• 모니터링 가이드

🤝 지원

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

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

📝 변경 로그

v1.0.0 (2025-08-04)

• 초기 Docker 배포 설정
• CI/CD 파이프라인 구축
• 모니터링 시스템 추가
• 보안 설정 강화