HF_UPLOAD_GUIDE.md

# Hugging Face Spaces 업로드 가이드

이 가이드는 Hugging Face Spaces에 파일을 업로드하는 방법을 설명합니다.

## 방법 1: Git을 사용한 업로드 (권장)

### 1. Hugging Face Spaces 생성

1. [Hugging Face Spaces](https://huggingface.co/spaces) 접속
2. "Create new Space" 클릭
3. 설정:
   - **Space name**: 원하는 이름
   - **SDK**: Docker
   - **Docker template**: Blank
   - **Hardware**: CPU Basic (또는 필요에 따라)
   - **Visibility**: Public 또는 Private

### 2. Git 저장소 클론

Spaces 생성 후, Hugging Face에서 제공하는 Git URL을 사용하여 클론:

```bash
# Hugging Face에서 제공하는 Git URL 사용
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME
```

### 3. 필요한 파일 복사

로컬 프로젝트에서 필요한 파일들을 복사:

```bash
# Windows PowerShell에서 실행
# 프로젝트 루트 디렉토리에서 실행

# 필수 파일 복사
Copy-Item ..\app.py .
Copy-Item ..\Dockerfile .
Copy-Item ..\requirements.txt .
Copy-Item ..\README_HF.md README.md

# 디렉토리 복사
Copy-Item -Recurse ..\app .
Copy-Item -Recurse ..\templates .
Copy-Item -Recurse ..\static .
```

### 4. Git 커밋 및 푸시

```bash
git add .
git commit -m "Initial deployment"
git push
```

## 방법 2: 웹 인터페이스를 사용한 업로드

1. Hugging Face Spaces 페이지 접속
2. "Files and versions" 탭 클릭
3. "Add file" > "Upload files" 클릭
4. 다음 파일들을 드래그 앤 드롭으로 업로드:

### 필수 파일 목록

#### 루트 디렉토리 파일
- `app.py`
- `Dockerfile`
- `requirements.txt`
- `README.md` (README_HF.md의 내용 사용)

#### 디렉토리 (폴더 전체 업로드)
- `app/` (전체 디렉토리)
- `templates/` (전체 디렉토리)
- `static/` (전체 디렉토리)

## 업로드하지 말아야 할 파일/폴더

다음 항목은 `.gitignore`에 포함되어 있으므로 업로드하지 마세요:

- `venv/` - 가상 환경
- `instance/` - 데이터베이스 파일
- `uploads/` - 업로드된 파일
- `vector_db/` - 벡터 데이터베이스
- `logs/` - 로그 파일
- `*.pyc`, `__pycache__/` - Python 캐시
- `.env` - 환경 변수 파일 (민감 정보)
- `.git/` - Git 저장소

## 환경 변수 설정

파일 업로드 후, Settings > Repository secrets에서 환경 변수 설정:

### 필수
```
SECRET_KEY=your-random-secret-key-here
```

### 선택사항
```
GEMINI_API_KEY=your-gemini-api-key
DATABASE_URL=sqlite:///instance/finance_analysis.db
```

## 배포 확인

1. Spaces 페이지에서 "Logs" 탭 확인
2. 빌드가 완료되면 애플리케이션 접속 테스트
3. 오류가 있으면 로그 확인

## 빠른 업로드 스크립트 (Windows PowerShell)

프로젝트 루트 디렉토리에서 실행:

```powershell
# Hugging Face Spaces 디렉토리 경로 설정
$HF_SPACE_DIR = "C:\path\to\huggingface\space"

# 필수 파일 복사
Copy-Item app.py $HF_SPACE_DIR\
Copy-Item Dockerfile $HF_SPACE_DIR\
Copy-Item requirements.txt $HF_SPACE_DIR\
Copy-Item README_HF.md "$HF_SPACE_DIR\README.md"

# 디렉토리 복사
Copy-Item -Recurse app "$HF_SPACE_DIR\app"
Copy-Item -Recurse templates "$HF_SPACE_DIR\templates"
Copy-Item -Recurse static "$HF_SPACE_DIR\static"

Write-Host "파일 복사 완료!"
```

## 문제 해결

### 빌드 실패
- `requirements.txt`의 패키지 버전 확인
- 로그에서 오류 메시지 확인

### 런타임 오류
- 환경 변수가 올바르게 설정되었는지 확인
- `app.py`가 올바른 포트를 사용하는지 확인 (7860)

### 파일 누락
- 모든 필수 디렉토리(`app/`, `templates/`, `static/`)가 업로드되었는지 확인