HF_UPLOAD_GUIDE.md

Hugging Face Spaces 업로드 가이드

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

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

1. Hugging Face Spaces 생성

1. Hugging Face 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을 사용하여 클론:

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

3. 필요한 파일 복사

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

# 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 커밋 및 푸시

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)

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

# 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/)가 업로드되었는지 확인