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 로컬 환경 설정
```bash
# Hugging Face CLI 설치
pip install huggingface_hub

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

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

### 2.1 로컬 모델 확인
```bash
cd C:\Project\lily_generate_project\lily_generate_package
ls hearth_llm_model/
```

### 2.2 모델을 Hugging Face Hub에 업로드
```bash
# 모델 업로드
huggingface-cli upload your-username/lily-math-model hearth_llm_model/

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

### 2.3 모델 카드 생성
```markdown
# 모델 카드 예시 (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 환경 변수 설정
```bash
# 환경 변수 설정
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 연동 테스트
```bash
# 연동 테스트 실행
python railway_hearth_chat_integration.py
```

### 4.3 Hearth Chat API 수정 (필요시)
Railway Hearth Chat에서 Hugging Face 엔드포인트를 호출하도록 API를 수정:

```javascript
// 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 엔드포인트 테스트
```bash
# 엔드포인트 테스트
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 연동 테스트
```bash
# 전체 연동 테스트
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
- ✅ **모니터링**: 실시간 사용량 및 성능 확인