# Qwen-Image-Layered 클라우드 전환 프로젝트

## 프로젝트 개요

기존 로컬 GPU 기반 Qwen-Image-Layered 시스템을 Google Cloud Vertex AI 기반 클라우드 아키텍처로 전환하는 전체 여정을 기록한 10부작 블로그 시리즈입니다.

**핵심 성과**:
- ✅ 하드웨어 독립성 달성 (로컬 GPU 불필요)
- ✅ 무한 확장성 확보 (자동 스케일링)
- ✅ 비용 95% 절감 (로컬 GPU $80/월 → 클라우드 $4-9/월)
- ✅ 운영 복잡도 대폭 감소

## 시리즈 구성

### [v1: 프로젝트 업그레이드 배경](./update-qwen-image-layered-project-v1.md)
**주제**: 로컬 GPU에서 벗어나기

**다루는 내용**:
- 로컬 GPU의 4가지 한계 (하드웨어 접근성, 확장성, 비용, 유지보수)
- 클라우드 전환의 필요성
- Hugging Face API vs Vertex AI 옵션 소개
- 예상 비용 분석

**핵심 결론**: 월 1,000회 미만 사용 시 클라우드가 압도적으로 유리

---

### [v2: Hugging Face vs Vertex AI 심층 비교](./update-qwen-image-layered-project-v2.md)
**주제**: 두 플랫폼의 장단점 분석

**비교 항목**:
- Serverless Inference API vs Inference Endpoints
- Vertex AI Model Garden
- 가격 구조 차이
- 오토 스케일링 지원
- 사용 사례별 추천

**핵심 결론**: Vertex AI 선택 (비용 효율 + 자동 스케일링 + GCP 생태계 통합)

---

### [v3: Hugging Face Inference API 실전 테스트](./update-qwen-image-layered-project-v3.md)
**주제**: 직접 해보고 한계 확인하기

**테스트 결과**:
- Serverless API: Qwen-Image-Layered 미지원 ❌
- Inference Endpoints: 커스텀 컨테이너 필요, 비용 15배 비쌈
- Auto-pause 기능: Cold Start 3-4분 (UX 치명적)

**핵심 결론**: Vertex AI로 전환 확정

---

### [v4: Vertex AI Model Garden 배포 실전](./update-qwen-image-layered-project-v4.md)
**주제**: 실제 배포 과정

**단계별 가이드**:
1. GCP 프로젝트 생성 및 API 활성화
2. 서비스 계정 생성
3. Docker 이미지 빌드 (모델 포함)
4. Container Registry 푸시
5. Vertex AI 엔드포인트 배포
6. API 호출 테스트

**핵심 결과**: 배포 15분, Cold Start 2-3분, 추론 34초

---

### [v5: API 엔드포인트 재설계](./update-qwen-image-layered-project-v5.md)
**주제**: 기존 FastAPI 백엔드 클라우드 통합

**변경 사항**:
- `QwenDecomposer` → `VertexAIClient`로 교체
- 동기 → 비동기 API 호출
- Worker 재시도 로직 추가
- 비용 추적 로깅
- 에러 핸들링 강화

**핵심 코드**: 추상화 레이어로 로컬/클라우드 전환 용이

---

### [v6: 비용 최적화 전략](./update-qwen-image-layered-project-v6.md)
**주제**: 비용 95% 절감 방법

**최적화 전략**:
1. **시간대별 스케일링** (62% 절감)
   - 업무 시간: 최소 1대
   - 야간: 최소 0대

2. **예측 기반 Warm-up** (Cold Start 제거)
   - 피크 시간 10분 전 인스턴스 시작

3. **결과 캐싱** (20% 절감)
   - 동일 이미지 요청 재사용

4. **Spot Instances** (70% 할인)
   - Preemptible GPU 활용

5. **배치 처리** (50% 절감)
   - 여러 요청 동시 처리

**최종 결과**: $37.50/월 → $1.80/월 (95% 절감)

---

### [v7: 성능 벤치마크](./update-qwen-image-layered-project-v7.md)
**주제**: 로컬 GPU vs Vertex AI 정량적 비교

**벤치마크 결과**:

| 항목 | 로컬 GPU (RTX 3090) | Vertex AI (T4) |
|------|---------------------|----------------|
| 추론 속도 (1024px) | 28.7s | 34.2s |
| Cold Start | N/A | 204s |
| 동시 10개 처리 | 285s (순차) | 42s (병렬) |
| 월 비용 (10,000회) | $80 | $9 |

**핵심 결론**: 동시 처리와 비용에서 클라우드가 압도적 우위

---

### [v8: 하이브리드 아키텍처 구현](./update-qwen-image-layered-project-v8.md)
**주제**: 복원력 확보를 위한 폴백 체인

**폴백 전략**:
```
1차: Vertex AI (Primary)
  ↓ 실패 시
2차: Hugging Face (Secondary)
  ↓ 실패 시
3차: 로컬 GPU (Tertiary)
```

**핵심 패턴**:
- 추상화 레이어 (`BaseDecomposer`)
- Circuit Breaker 패턴
- 자동 폴백 오케스트레이터
- 비용 기반 라우팅

**결과**: 단일 장애점 제거, 99.9% 가용성

---

### [v9: 비용 모니터링 대시보드](./update-qwen-image-layered-project-v9.md)
**주제**: 실시간 비용 추적 및 알림

**구축 스택**:
- **Cost Tracker**: Redis 기반 비용 기록
- **Prometheus**: 메트릭 수집
- **Grafana**: 시각화 대시보드
- **Slack**: 예산 초과 알림

**주요 기능**:
- 일일/월간 비용 조회
- 백엔드별 비용 분석
- 비용 최적화 제안 자동 생성
- 예산 초과 시 Slack 알림

**API 엔드포인트**:
- `GET /api/cost/today`
- `GET /api/cost/month`
- `GET /api/cost/breakdown`
- `GET /api/cost/suggestions`

---

### [v10: 운영 가이드 및 여정 회고](./update-qwen-image-layered-project-v10.md)
**주제**: 프로덕션 배포 및 프로젝트 총정리

**내용**:
1. **프로덕션 배포 체크리스트**
   - 인프라 준비
   - 애플리케이션 배포
   - 모니터링 설정
   - 테스트

2. **Docker Compose 전체 스택**
   - API, Worker, Redis, Prometheus, Grafana, Nginx

3. **일반적인 문제 해결**
   - Quota exceeded
   - Cold Start
   - Redis timeout
   - High costs

4. **운영 루틴**
   - 일일 체크
   - 주간 리뷰
   - 월간 작업

5. **프로젝트 회고**
   - 무엇이 잘 되었나
   - 어려웠던 점
   - 배운 교훈
   - 향후 개선 방향

---

## 기술 스택

### 클라우드 인프라
- **Google Cloud Platform**
  - Vertex AI (Hugging Face 모델 배포)
  - Container Registry
  - Cloud Storage
  - Cloud Monitoring

### 백엔드
- **Python 3.11**
  - FastAPI (REST API)
  - Pydantic (데이터 검증)
  - google-cloud-aiplatform (Vertex AI 클라이언트)

### 데이터 저장
- **Redis** (작업 큐, 캐시, 비용 추적)
- **Cloud Storage** (결과 파일)

### 모니터링
- **Prometheus** (메트릭 수집)
- **Grafana** (시각화)
- **Slack** (알림)

### 배포
- **Docker** & **Docker Compose**
- **Nginx** (리버스 프록시, SSL)

## 최종 아키텍처

```
[User Browser]
      ↓ HTTPS
   [Nginx]
      ↓
  [FastAPI] ←→ [Redis]
      ↓
  [Worker]
      ↓
[Orchestrator]
  ↙   ↓   ↘
[Vertex] [HF] [Local]
```

## 실행 방법

### 1. 환경 설정

```bash
# 저장소 클론
git clone https://github.com/your-org/poster-decomposer.git
cd poster-decomposer

# 환경 변수 설정
cp .env.example .env
nano .env  # 값 입력
```

### 2. Vertex AI 배포

```bash
# Docker 이미지 빌드
cd vertex-ai
docker build -t qwen-image-layered:v1 .

# GCR 푸시
docker tag qwen-image-layered:v1 gcr.io/PROJECT_ID/qwen:v1
docker push gcr.io/PROJECT_ID/qwen:v1

# Vertex AI 배포
python deploy.py
```

### 3. 애플리케이션 실행

```bash
# Docker Compose로 전체 스택 실행
docker-compose up -d

# 헬스 체크
curl http://localhost:8000/health
```

### 4. 모니터링 접속

- **API**: http://localhost:8000
- **Prometheus**: http://localhost:9090
- **Grafana**: http://localhost:3000 (admin/admin)

## 비용 분석

### 시나리오별 월간 비용

| 사용량 | 로컬 GPU | 클라우드 (최적화 전) | 클라우드 (최적화 후) |
|--------|----------|---------------------|---------------------|
| 100회 | $80 | $3.75 | $0.90 |
| 1,000회 | $80 | $37.50 | $9.00 |
| 10,000회 | $80 | $375.00 | $18.00 |
| 50,000회 | $80 | $1,875.00 | $90.00 |

**손익 분기점**: 월 26,000회 이상이면 로컬 GPU가 유리

## 핵심 학습 포인트

1. **클라우드 전환 의사결정**
   - 사용량 패턴 분석
   - 비용 vs UX 트레이드오프
   - 플랫폼 비교 방법론

2. **비용 최적화 기법**
   - 자동 스케일링
   - 캐싱 전략
   - Spot Instances
   - 시간대별 조정

3. **시스템 설계 패턴**
   - 추상화 레이어
   - Circuit Breaker
   - 폴백 체인
   - 비용 기반 라우팅

4. **운영 베스트 프랙티스**
   - 모니터링 우선
   - 점진적 최적화
   - 알림 자동화
   - 문제 해결 루틴

## 프로젝트 타임라인

- **Day 1-2**: 조사 및 비교 분석 (v1-v2)
- **Day 3-4**: 실험 및 배포 (v3-v4)
- **Day 5-6**: 통합 및 기본 최적화 (v5-v6)
- **Day 7-8**: 벤치마크 및 고급 기능 (v7-v8)
- **Day 9-10**: 모니터링 및 문서화 (v9-v10)

**총 소요 기간**: 약 2주

## 기여자

- **Author**: [Your Name]
- **Project**: Poster Layer Decomposer
- **Date**: 2025-12-23

## 라이선스

이 블로그 시리즈는 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 라이선스를 따릅니다.

코드는 [MIT License](LICENSE)를 따릅니다.

## 참고 자료

### 공식 문서
- [Vertex AI Documentation](https://cloud.google.com/vertex-ai/docs)
- [Hugging Face Documentation](https://huggingface.co/docs)
- [Qwen-Image-Layered Model Card](https://huggingface.co/Qwen/Qwen-Image-Layered)

### 관련 프로젝트
- [기존 프로젝트: 20251221-qwen-image-layered](../20251221-qwen-image-layered/)
- [참고 프로젝트: 20251130-post-money-forward-vertex-ai](../20251130-post-money-forward-vertex-ai/)

## 피드백

질문이나 피드백은 다음으로 연락해주세요:
- **GitHub Issues**: [프로젝트 이슈](https://github.com/your-org/poster-decomposer/issues)
- **Email**: your.email@example.com

---

**시리즈 시작**: [v1: 프로젝트 업그레이드 배경](./update-qwen-image-layered-project-v1.md)

**마지막 업데이트**: 2025-12-23