HUGGINGFACE_DEPLOY.md

Hugging Face Spaces 배포 가이드

이 가이드는 SOY NV AI 애플리케이션을 Hugging Face Spaces에 배포하는 방법을 설명합니다.

사전 준비

1. Hugging Face 계정 생성 및 로그인
2. Hugging Face Spaces 생성

배포 단계

1. Hugging Face Spaces 생성

1. Hugging Face Spaces에 접속
2. "Create new Space" 클릭
3. 다음 정보 입력:
   • Space name: 원하는 이름 (예: soy-nv-ai)
   • SDK: Docker 선택
   • Docker template: Blank 선택 (또는 비워두기) ✅
     • 이미 Dockerfile을 생성했으므로 blank 템플릿을 선택하세요
   • Hardware: 필요에 따라 선택 (CPU 기본, GPU 필요 시 선택)
   • Visibility: Public 또는 Private 선택

2. 파일 업로드

다음 파일들을 Hugging Face Spaces에 업로드해야 합니다:

필수 파일

• app.py - Hugging Face Spaces 진입점
• requirements.txt - Python 패키지 의존성
• README.md - 프로젝트 설명
• app/ - 애플리케이션 코드 디렉토리
• templates/ - HTML 템플릿 디렉토리
• static/ - 정적 파일 디렉토리

선택적 파일

• .gitignore - Git 무시 파일
• .env.example - 환경 변수 예제 (실제 .env는 업로드하지 않음)

3. 환경 변수 설정

Hugging Face Spaces의 Settings > Repository secrets에서 다음 환경 변수를 설정하세요:

필수 환경 변수

• SECRET_KEY: Flask 시크릿 키 (랜덤 문자열 생성)

데이터베이스 환경 변수 (권장: 외부 데이터베이스)

• DATABASE_URL: 데이터베이스 연결 URL
  • PostgreSQL (권장): postgresql://user:password@host:port/database
    • 무료 PostgreSQL 제공 서비스: Supabase, Neon, Railway
  • SQLite (기본값): 설정하지 않으면 자동으로 SQLite 사용
    • ⚠️ 주의: Hugging Face Spaces는 컨테이너 기반이므로 SQLite 사용 시 재시작 시 데이터가 사라집니다.
    • 영구 저장이 필요하면 반드시 외부 PostgreSQL을 사용하세요.

선택적 환경 변수

• GEMINI_API_KEY: Google Gemini API 키 (Gemini 사용 시)
• OLLAMA_BASE_URL: Ollama 서버 URL (기본값: http://localhost:11434)
• EMBEDDING_MODEL_NAME: 임베딩 모델 이름
• RERANKER_MODEL_NAME: 리랭커 모델 이름

4. Dockerfile 확인

✅ 이미 생성됨: 프로젝트 루트에 Dockerfile이 이미 생성되어 있습니다.

필요한 경우 Dockerfile을 확인하거나 수정할 수 있습니다.

5. README.md 작성

Hugging Face Spaces용 README.md를 작성하세요:

---
title: SOY NV AI
emoji: 📚
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
---

# SOY NV AI - 웹소설 작품 개발 어시스턴트

AI를 활용한 웹소설 작품 개발을 지원하는 어시스턴트입니다.

## 기능

- 웹소설 파일 업로드 및 분석
- AI 기반 작품 분석 및 요약
- 캐릭터 관계 그래프 추출
- 회차별 분석

## 사용 방법

1. 로그인 또는 회원가입
2. 웹소설 파일 업로드
3. AI 분석 실행
4. 결과 확인

## 환경 변수

다음 환경 변수를 설정해야 합니다:

- `SECRET_KEY`: Flask 시크릿 키
- `GEMINI_API_KEY`: Google Gemini API 키 (선택사항)

주의사항

1. 데이터베이스

• Hugging Face Spaces는 임시 저장소이므로, 데이터베이스는 영구 저장소가 아닙니다.
• 중요한 데이터는 외부 데이터베이스(PostgreSQL, MySQL 등)를 사용하거나 정기적으로 백업하세요.

2. 파일 업로드

• 업로드된 파일은 Spaces 재시작 시 삭제될 수 있습니다.
• 영구 저장이 필요한 경우 외부 스토리지(S3, Google Cloud Storage 등)를 사용하세요.

3. 리소스 제한

• Hugging Face Spaces는 무료 티어에서 리소스 제한이 있습니다.
• 대용량 파일 처리나 긴 작업은 타임아웃될 수 있습니다.

4. Ollama 사용

• Ollama는 로컬 서버이므로 Hugging Face Spaces에서 직접 사용할 수 없습니다.
• 외부 Ollama 서버를 사용하거나, Hugging Face의 모델 API를 사용하세요.

배포 후 확인

1. Spaces 페이지에서 "Logs" 탭을 확인하여 오류가 없는지 확인
2. 애플리케이션이 정상적으로 로드되는지 확인
3. 로그인 및 기본 기능 테스트

문제 해결

빌드 실패

• requirements.txt의 패키지 버전 확인
• 로그에서 오류 메시지 확인

런타임 오류

• 환경 변수가 올바르게 설정되었는지 확인
• 데이터베이스 경로 및 권한 확인

성능 문제

• 더 높은 하드웨어 티어로 업그레이드 고려
• 불필요한 의존성 제거

추가 리소스

• Hugging Face Spaces 문서
• Docker 배포 가이드