HUGGINGFACE_CLOUD_GUIDE.md

☁️ Hugging Face 클라우드 GPU 배포 가이드

📋 개요

이 가이드는 로컬 PC에서 Hugging Face 클라우드 GPU 환경을 설정하고, AI 모델을 배포한 후 Railway에서 실행 중인 Hearth Chat과 연동하는 방법을 설명합니다.

🎯 목표

1. Hugging Face 클라우드 GPU 환경 설정
2. AI 모델을 Hugging Face Hub에 업로드
3. Inference Endpoints 생성
4. Railway Hearth Chat과 연동

🚀 1단계: Hugging Face 계정 설정

1.1 Hugging Face 계정 생성

1. Hugging Face 웹사이트 방문: https://huggingface.co
2. 회원가입: 이메일로 계정 생성
3. 프로필 설정: 사용자명 설정 (예: your-username)

1.2 Access Token 생성

1. Settings > Access Tokens: https://huggingface.co/settings/tokens
2. New Token 생성:
   • Name: lily-math-rag-token
   • Role: Write
3. 토큰 복사: 생성된 토큰을 안전한 곳에 저장

1.3 로컬 환경 설정

# Hugging Face CLI 설치
pip install huggingface_hub

# 로그인
huggingface-cli login
# 토큰 입력 프롬프트에서 위에서 생성한 토큰 입력

🔧 2단계: 모델 준비 및 업로드

2.1 로컬 모델 확인

cd C:\Project\lily_generate_project\lily_generate_package
ls hearth_llm_model/

2.2 모델을 Hugging Face Hub에 업로드

# 모델 업로드
huggingface-cli upload your-username/lily-math-model hearth_llm_model/

# 또는 Python 스크립트 사용
python huggingface_cloud_setup.py

2.3 모델 카드 생성

# 모델 카드 예시 (README.md)
---
language: ko
tags:
- math
- rag
- korean
license: mit
---

# Lily Math RAG Model

수학 문제 해결을 위한 한국어 RAG 모델입니다.

## 사용법

```python
from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("your-username/lily-math-model")
model = AutoModelForCausalLM.from_pretrained("your-username/lily-math-model")

## ☁️ 3단계: Hugging Face Inference Endpoints 설정

### 3.1 Inference Endpoints 생성
1. **Hugging Face 웹사이트 방문**: https://huggingface.co/inference-endpoints
2. **New Endpoint 클릭**
3. **설정 입력**:
   - **Repository**: `your-username/lily-math-model`
   - **Framework**: `PyTorch`
   - **Region**: `us-east-1` (가장 빠름)
   - **Instance Type**: `gpu.t4.medium` (시작용)
   - **Accelerator**: `GPU`

### 3.2 엔드포인트 설정
```json
{
  "repository": "your-username/lily-math-model",
  "framework": "pytorch",
  "accelerator": "gpu",
  "instance_type": "gpu.t4.medium",
  "region": "us-east-1",
  "vendor": "aws"
}

3.3 엔드포인트 URL 확인

• 생성된 엔드포인트의 URL을 복사
• 예: https://your-endpoint-id.us-east-1.aws.endpoints.huggingface.cloud

🔗 4단계: Railway Hearth Chat 연동

4.1 환경 변수 설정

# 환경 변수 설정
export RAILWAY_HEARTH_CHAT_URL="https://hearth-chat-production.up.railway.app"
export HF_ENDPOINT_URL="https://your-endpoint-id.us-east-1.aws.endpoints.huggingface.cloud"
export HF_TOKEN="your-huggingface-token"

4.2 연동 테스트

# 연동 테스트 실행
python railway_hearth_chat_integration.py

4.3 Hearth Chat API 수정 (필요시)

Railway Hearth Chat에서 Hugging Face 엔드포인트를 호출하도록 API를 수정:

// Hearth Chat API 예시
async function callHuggingFaceAPI(message) {
  const response = await fetch(process.env.HF_ENDPOINT_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HF_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      inputs: message,
      parameters: {
        max_length: 200,
        temperature: 0.7
      }
    })
  });
  
  const result = await response.json();
  return result.generated_text;
}

🧪 5단계: 테스트 및 검증

5.1 Hugging Face 엔드포인트 테스트

# 엔드포인트 테스트
curl -X POST https://your-endpoint-id.us-east-1.aws.endpoints.huggingface.cloud \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": "안녕하세요! 수학 문제를 도와주세요.",
    "parameters": {
      "max_length": 100,
      "temperature": 0.7
    }
  }'

5.2 Railway 연동 테스트

# 전체 연동 테스트
python test_railway_huggingface_integration.py

📊 6단계: 모니터링 및 최적화

6.1 Hugging Face 모니터링

• Inference Endpoints 대시보드: https://huggingface.co/inference-endpoints
• 사용량 확인: GPU 사용량, 요청 수, 응답 시간
• 비용 모니터링: 월별 사용량 및 비용

6.2 Railway 모니터링

• Railway 대시보드: https://railway.app/dashboard
• 로그 확인: 애플리케이션 로그 및 오류
• 성능 모니터링: 응답 시간, 메모리 사용량

🔧 문제 해결

Hugging Face 관련 문제

1. 토큰 인증 오류: 토큰 재생성 및 확인
2. 모델 업로드 실패: 파일 크기 및 형식 확인
3. 엔드포인트 생성 실패: GPU 할당량 확인

Railway 연동 문제

1. 연결 실패: URL 및 네트워크 확인
2. API 오류: 엔드포인트 및 헤더 확인
3. 응답 지연: 타임아웃 설정 조정

💰 비용 최적화

Hugging Face 비용

• gpu.t4.medium: $0.60/시간 (시작용)
• gpu.t4.large: $1.20/시간 (성능 향상)
• gpu.a10g: $2.40/시간 (고성능)

비용 절약 팁

1. 자동 스케일링: 사용하지 않을 때 엔드포인트 중지
2. 캐싱: 동일한 요청에 대한 응답 캐싱
3. 배치 처리: 여러 요청을 한 번에 처리

🚀 배포 체크리스트

• Hugging Face 계정 생성 및 토큰 설정
• 로컬 모델 확인 및 업로드
• Inference Endpoints 생성
• 엔드포인트 URL 및 토큰 확인
• Railway Hearth Chat URL 확인
• 환경 변수 설정
• 연동 테스트 실행
• 모니터링 설정
• 비용 최적화 설정

📞 지원

유용한 링크

• Hugging Face 문서: https://huggingface.co/docs
• Inference Endpoints 가이드: https://huggingface.co/docs/inference-endpoints
• Railway 문서: https://docs.railway.app

문제 해결

1. Hugging Face 지원: https://huggingface.co/support
2. Railway 지원: https://railway.app/support
3. 커뮤니티: GitHub Issues 및 Discord

🎉 성공 확인

모든 설정이 완료되면 다음을 확인할 수 있습니다:

• ✅ Hugging Face 엔드포인트: GPU에서 AI 모델 실행
• ✅ Railway Hearth Chat: 웹 인터페이스에서 채팅 가능
• ✅ 연동: 사용자 메시지 → Hugging Face → AI 응답 → Hearth Chat
• ✅ 모니터링: 실시간 사용량 및 성능 확인