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 접속
• "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

curl https://YOUR_USERNAME-lily-llm-api.hf.space/health

• 모델 목록: GET /models

curl https://YOUR_USERNAME-lily-llm-api.hf.space/models

• 텍스트 생성: POST /generate

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를 참조하여 Railway Hearth Chat과 연동을 진행하세요.

---

📞 지원

배포 중 문제가 발생하면:

1. 로그 확인 및 분석
2. DEPLOYMENT_GUIDE.md 상세 가이드 참조
3. Hugging Face Community 포럼 활용
4. GitHub Issues를 통한 기술 지원