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](https://huggingface.co/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](https://supabase.com/), [Neon](https://neon.tech/), [Railway](https://railway.app/)
  - **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를 작성하세요:

```markdown
---
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 문서](https://huggingface.co/docs/hub/spaces)
- [Docker 배포 가이드](https://huggingface.co/docs/hub/spaces-sdks-docker)