DEPLOYMENT_GUIDE.md

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

🚀 배포 단계별 가이드

1. 사전 준비

1.1 Hugging Face 계정 및 토큰

1. Hugging Face 계정 생성
2. Settings > Access 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 접속
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 방식 (권장)

# 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에서 다음 환경 변수들 설정:

# 서버 설정
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 테스트

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

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 모델 최적화

# 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 일반적인 오류

메모리 부족 오류

# requirements.txt에서 불필요한 패키지 제거
# 모델 크기 축소 또는 양자화 적용

빌드 시간 초과

# .dockerignore 파일로 불필요한 파일 제외
# multi-stage build 사용으로 빌드 최적화

모듈 import 오류

# PYTHONPATH 환경 변수 확인
# requirements.txt 의존성 확인

7.2 로그 분석

# 빌드 로그에서 오류 찾기
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 업데이트 배포

# 코드 수정 후
git add .
git commit -m "Update: description of changes"
git push

9.2 모니터링

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

---

📞 지원

배포 중 문제가 발생하면:

1. Hugging Face 공식 문서 참조
2. Community 포럼에서 도움 요청
3. GitHub Issues를 통한 기술 지원