# Qwen-Image-Layered 클라우드 전환 (3/10): Hugging Face Inference API 실전 테스트

## 직접 확인하기

v2에서 Vertex AI를 선택하기로 했지만, 학습 차원에서 **Hugging Face Inference API를 먼저 시도**해본다.

**목표**:
1. Qwen-Image-Layered가 Hugging Face Inference API에서 지원되는지 확인
2. 지원된다면 성능과 비용 측정
3. 지원되지 않는다면 Inference Endpoints 배포 방법 파악

## Hugging Face API 토큰 발급

### 1. 계정 생성

[Hugging Face](https://huggingface.co) 회원 가입 (무료)

### 2. API 토큰 생성

```
Settings → Access Tokens → New token

권한 선택:
- Read: 모델 정보 조회
- Write: 모델 업로드 (불필요)
- Inference: API 호출 (필수)

생성된 토큰:
hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**보안 주의**:
```bash
# 환경 변수로 저장
export HF_API_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# .env 파일 (절대 Git에 커밋하지 말 것)
echo "HF_API_TOKEN=hf_xxxxx" >> .env
```

## Serverless Inference API 테스트

### 모델 정보 확인

먼저 Qwen-Image-Layered 모델 페이지를 확인한다.

[https://huggingface.co/Qwen/Qwen-Image-Layered](https://huggingface.co/Qwen/Qwen-Image-Layered)

**모델 카드 확인 사항**:
```
Library: diffusers
Pipeline tag: text-to-image (또는 image-segmentation)
License: Apache 2.0
Model size: ~15GB

Inference API 위젯:
- ❌ "API not available for this model" 표시
```

**결과**: 예상대로 **Serverless Inference API 미지원**

### 왜 지원되지 않는가?

Hugging Face Serverless Inference API는 다음 조건의 모델만 지원:
1. 인기 많은 모델 (다운로드 수 기준)
2. 표준 파이프라인 (`text-generation`, `text-to-image` 등)
3. 경량 모델 (서버리스 환경에서 빠른 로딩)

Qwen-Image-Layered는:
- ✅ Apache 2.0 라이선스
- ❌ 최신 모델 (2024-12-21 공개)
- ❌ 비표준 파이프라인 (`QwenImageLayeredPipeline`)
- ❌ 15GB로 비교적 무거움

→ **Inference Endpoints를 사용해야 함**

## Inference Endpoints 배포

### 설정

Hugging Face 콘솔에서:

```
1. Model 페이지 → Deploy → Inference Endpoints
2. Endpoint 설정:
   - Region: us-east-1 (가장 저렴)
   - Instance Type: GPU [small] - 1x NVIDIA T4
   - Scaling:
     - Min replicas: 0 (자동 종료)
     - Max replicas: 1
   - Advanced:
     - Custom Container: No (기본 diffusers 이미지 사용)
     - Environment variables:
       MODEL_ID=Qwen/Qwen-Image-Layered

3. 비용 확인:
   - $0.60/hr
   - 월 예상: $432 (24시간 운영 시)

4. Create Endpoint 클릭
```

### 배포 과정

```
[00:00] Creating endpoint...
[00:30] Provisioning GPU instance...
[02:00] Downloading model (15GB)...
[08:00] Loading model into GPU...
[10:00] Endpoint ready!

Status: Running
URL: https://xxxxx.us-east-1.aws.endpoints.huggingface.cloud
```

**총 소요 시간**: ~10분

### API 호출 테스트

```python
import requests
import base64
from PIL import Image
import io

# 1. 이미지를 Base64로 인코딩
def image_to_base64(image_path):
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode()

# 2. API 요청
API_URL = "https://xxxxx.us-east-1.aws.endpoints.huggingface.cloud"
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

image_base64 = image_to_base64("test_poster.jpg")

payload = {
    "inputs": image_base64,
    "parameters": {
        "layers": 5,
        "resolution": 1024,
        "num_inference_steps": 50
    }
}

response = requests.post(API_URL, headers=headers, json=payload)

# 3. 응답 처리
if response.status_code == 200:
    result = response.json()
    # 레이어 이미지들이 Base64로 반환됨
    layers = result["layers"]

    for i, layer_b64 in enumerate(layers):
        layer_bytes = base64.b64decode(layer_b64)
        layer_image = Image.open(io.BytesIO(layer_bytes))
        layer_image.save(f"layer_{i}.png")

    print(f"✅ {len(layers)} 레이어 생성 완료")
else:
    print(f"❌ 에러: {response.status_code}")
    print(response.text)
```

### 실행 결과

```bash
$ python test_hf_inference.py

❌ 에러: 503
{
  "error": "Model Qwen/Qwen-Image-Layered is not supported in this endpoint"
}
```

**문제**: Hugging Face의 기본 컨테이너가 `QwenImageLayeredPipeline`을 지원하지 않음

### 커스텀 컨테이너 필요

**해결책**: 커스텀 Docker 이미지를 만들어야 함

```dockerfile
# Dockerfile
FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime

# Dependencies
RUN pip install transformers>=4.51.3 diffusers accelerate

# 커스텀 추론 서버
COPY inference_server.py /app/
WORKDIR /app

# 모델 다운로드 (빌드 시간에 미리)
RUN python -c "from diffusers import QwenImageLayeredPipeline; \
    QwenImageLayeredPipeline.from_pretrained('Qwen/Qwen-Image-Layered')"

CMD ["python", "inference_server.py"]
```

```python
# inference_server.py
from flask import Flask, request, jsonify
from diffusers import QwenImageLayeredPipeline
import torch
import base64
from PIL import Image
import io

app = Flask(__name__)

# 모델 로드 (서버 시작 시 1회)
pipeline = QwenImageLayeredPipeline.from_pretrained("Qwen/Qwen-Image-Layered")
pipeline = pipeline.to("cuda", torch.bfloat16)

@app.route("/predict", methods=["POST"])
def predict():
    data = request.json

    # Base64 디코딩
    image_b64 = data["inputs"]
    image_bytes = base64.b64decode(image_b64)
    image = Image.open(io.BytesIO(image_bytes))

    # 추론
    layers = pipeline(
        image=image,
        layers=data.get("parameters", {}).get("layers", 5),
        resolution=data.get("parameters", {}).get("resolution", 1024)
    )

    # 레이어를 Base64로 인코딩
    layers_b64 = []
    for layer in layers:
        buffer = io.BytesIO()
        layer.save(buffer, format="PNG")
        layer_b64 = base64.b64encode(buffer.getvalue()).decode()
        layers_b64.append(layer_b64)

    return jsonify({"layers": layers_b64})

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)
```

**문제점**:
1. Docker 이미지 빌드 및 푸시 필요 (복잡도 증가)
2. Hugging Face Container Registry에 업로드 필요
3. 이미지 크기 대형 (~20GB)
4. 여전히 $0.60/hr 비용

## 비용 현실

### 테스트 1시간 비용 계산

```
배포 시간: 10분
테스트 시간: 20분
총 가동: 30분

비용: $0.60 × 0.5 = $0.30

추론 횟수: 5회
1회당 비용: $0.06 (약 ₩80)
```

**문제**: Vertex AI는 1회당 ~$0.004 (₩5)인데 Hugging Face는 **15배 비싸다**

왜? → **Always On 방식**이기 때문

```
Hugging Face Inference Endpoints:
- 요청 없어도 GPU 가동 중
- 최소 과금: 1시간

Vertex AI:
- 최소 인스턴스 0 설정 시
- 추론 시간만 과금 (30초 → $0.004)
```

### Auto-pause 기능 테스트

Hugging Face Inference Endpoints의 **Auto-pause** 설정:

```
Settings → Scaling:
- Scale to zero after: 15 minutes idle

효과:
- 15분간 요청 없으면 인스턴스 종료
- 다음 요청 시 자동 재시작 (2-3분 소요)
```

**테스트 결과**:

```bash
# 첫 요청 (Cold Start)
$ time python test_hf_inference.py
...
real    3m42s  # 모델 로딩 포함

# 즉시 두 번째 요청 (Warm)
$ time python test_hf_inference.py
...
real    0m35s  # 추론만

# 20분 후 요청 (다시 Cold Start)
$ time python test_hf_inference.py
...
real    3m28s
```

**결론**:
- ✅ Auto-pause로 유휴 비용 절감 가능
- ❌ Cold Start 3-4분은 UX 측면에서 치명적
- ❌ 여전히 최소 과금 단위가 크다

## Hugging Face의 한계

| 항목 | Hugging Face | Vertex AI |
|------|-------------|----------|
| 커스텀 모델 지원 | ❌ 복잡 (Docker 필요) | ✅ 원클릭 |
| 비용 (1,000회/월) | ~$60 (Always On 가정) | ~$4 (사용량 기반) |
| Cold Start | 2-3분 | 2-3분 (동일) |
| 최소 과금 | 1시간 | 1초 |
| 오토 스케일링 | 0-1 인스턴스만 | 0-무한대 |

**결정적 이유**:

Qwen-Image-Layered는 **비표준 모델**이므로:
- Hugging Face: 커스텀 컨테이너 빌드 필요 (복잡도 높음)
- Vertex AI: Hugging Face 모델을 그대로 배포 가능 (간단)

## 최종 결정: Vertex AI로 전환

다음 이유로 Hugging Face Inference Endpoints를 **포기**한다:

### 1. 비용 효율성
- Vertex AI가 15배 저렴 (사용량 기반)

### 2. 배포 복잡도
- 커스텀 Docker 이미지 불필요

### 3. 확장성
- Vertex AI는 무한 스케일링 가능

### 4. Google Cloud 생태계
- 기존 인프라와 통합 용이

### 학습 가치

이 시도를 통해 얻은 것:
1. Hugging Face Inference API의 한계 이해
2. 커스텀 모델 배포의 복잡성 경험
3. 비용 구조의 차이 실감
4. "항상 검증하고 선택하라"는 교훈

## 다음 단계

v4에서는 **Vertex AI Model Garden에서 Qwen-Image-Layered 배포**를 실제로 진행한다:
1. GCP 프로젝트 설정
2. Vertex AI API 활성화
3. Model Garden에서 Hugging Face 모델 검색
4. GPU 인스턴스 선택 및 배포
5. 첫 API 호출 성공

이제 진짜 시작이다.

---

**이전 글**: [Hugging Face vs Vertex AI 비교 (2/10)](./update-qwen-image-layered-project-v2.md)

**다음 글**: [Vertex AI Model Garden 배포 실전 (4/10)](./update-qwen-image-layered-project-v4.md)

**참고 자료**:
- [Hugging Face Inference Endpoints Docs](https://huggingface.co/docs/inference-endpoints)
- [Custom Containers on HF Endpoints](https://huggingface.co/docs/inference-endpoints/guides/custom_container)