DEPLOY.md

Hugging Face Spaces 배포 가이드

1단계: Hugging Face 계정 생성

1. https://huggingface.co/ 접속
2. 회원가입 (GitHub 계정으로 가능)
3. 무료 계정으로 충분!

2단계: Space 생성

1. https://huggingface.co/new-space
2. 설정:
   • Space name: chatbia-api (원하는 이름)
   • License: MIT
   • Space SDK: Docker
   • Space hardware: CPU basic (무료)
   • Visibility: Public

3단계: Git 설정

로컬에서 Git 초기화

cd ChatBIA-Server

# Git 초기화
git init
git lfs install
git lfs track "*.gguf"

# Hugging Face 리모트 추가
git remote add origin https://huggingface.co/spaces/YOUR-USERNAME/chatbia-api

# 파일 추가
git add .
git commit -m "Initial commit"

4단계: 모델 파일 추가

중요: 모델 파일은 Git LFS로 업로드해야 합니다!

# models 폴더에 GGUF 파일 복사
cp ../ChatBIA-Windows/models/*.gguf .

# Git LFS로 추가
git add Qwen2.5-3B-Instruct-Q4_K_M.gguf
git add ChatBIA-3B-v0.1-Q4_K_M.gguf

git commit -m "Add model files"

5단계: Push

# Hugging Face 토큰 설정 (최초 1회)
# https://huggingface.co/settings/tokens 에서 토큰 생성

git push origin main

참고: 모델 파일이 크므로 업로드에 시간이 걸립니다 (~10-20분)

6단계: 배포 확인

1. Space 페이지에서 "Building" 상태 확인
2. 빌드 완료 후 "Running" 상태 확인
3. API 테스트:

curl https://YOUR-USERNAME-chatbia-api.hf.space/

7단계: API URL 확인

배포 완료 후 Space URL:

https://YOUR-USERNAME-chatbia-api.hf.space

이 URL을 안드로이드 앱에서 사용하면 됩니다!

문제 해결

빌드 실패

• Logs 탭에서 에러 확인
• 주로 requirements.txt 문제

모델 로드 실패

• Git LFS가 제대로 설정되었는지 확인
• 모델 파일이 정상적으로 업로드되었는지 확인

느린 응답

• CPU basic은 무료지만 느립니다
• 유료 GPU로 업그레이드 가능 (~$0.60/hour)

대안: 로컬 테스트 먼저

# Docker로 로컬 테스트
docker build -t chatbia-api .
docker run -p 7860:7860 chatbia-api

# 테스트
curl http://localhost:7860/

비용

• CPU basic: 무료 ✅
• CPU upgrade: $0.03/hour
• GPU T4: $0.60/hour
• GPU A10G: $3.15/hour

무료 CPU로 시작하세요!