본문으로 건너뛰기

Hugging Face 모델을 FastAPI로 API 서버 배포하기

이 문서는 이전 실습에서 사용한 Hugging Face 모델을 기반으로,
FastAPI 웹 프레임워크와 연동하여 API 서버 형태로 배포하는 방법을 안내합니다.

이를 통해 단순한 모델 테스트를 넘어, ECI GPU/CPU VM을 실제 운영 서버처럼 활용하는 방법을 확인할 수 있습니다.

실습 목표​

이 문서를 완료하면 다음을 할 수 있습니다.

  • Hugging Face 모델을 서버 프로세스로 로딩
  • FastAPI 기반 추론 API 구현
  • 외부에서 HTTP 요청으로 모델 추론 결과 확인
  • 실제 서비스와 유사한 API 서버 구조 이해

전체 구조 개요​


Client (curl / Browser)
|
v
FastAPI API Server
|
v
Hugging Face Transformers
|
v
CPU / GPU (ECI VM)

사전 준비 사항​

Step 1. 기존 실습 환경 확인​

이전 가이드에서 생성한 프로젝트 디렉토리로 이동합니다.

cd hf-text-cls
source .venv/bin/activate

라이브러리 설치 상태를 확인합니다.

pip list | grep transformers

Step 2. FastAPI 및 웹 서버 라이브러리 설치​

API 서버 구성을 위해 FastAPI와 ASGI 서버(Uvicorn)를 설치합니다.

pip install fastapi uvicorn

Step 3. API 서버 코드 작성​

1️⃣ 프로젝트 구조​

hf-text-cls/
 ├─ app.py
 └─ text_cls_infer.py

2️⃣ FastAPI + Hugging Face 코드 작성​

nano app.py
from fastapi import FastAPI
from pydantic import BaseModel
from transformers import pipeline

# FastAPI 앱 생성
app = FastAPI()

# Hugging Face sentiment-analysis 파이프라인 로딩
# 서버 시작 시 한 번만 로딩됨
clf = pipeline(
    "sentiment-analysis",
    model="distilbert-base-uncased-finetuned-sst-2-english"
)

# 요청 스키마 정의
class TextRequest(BaseModel):
    text: str

# 헬스 체크 엔드포인트
@app.get("/")
def health_check():
    return {"status": "ok"}

# 감정 분석 API
@app.post("/predict")
def predict(req: TextRequest):
    result = clf(req.text)[0]
    return {
        "text": req.text,
        "label": result["label"],
        "score": result["score"],
    }

Step 4. API 서버 실행​

uvicorn app:app --host 0.0.0.0 --port 8000

Step 5. API 동작 확인​

1️⃣ 서버 상태 확인​

curl http://<VM_PUBLIC_IP>:8000/

응답 예시:

{"status":"ok"}

2️⃣ 추론 API 호출​

curl -X POST http://<VM_PUBLIC_IP>:8000/predict \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I really like this product!"
  }'

응답 예시:

{
  "text": "I really like this product!",
  "label": "POSITIVE",
  "score": 0.9998123049736023
}

🎉 Hugging Face 모델이 API 서버 형태로 정상 배포되었습니다.

현재 구조의 의미​

이 구성은 다음을 의미합니다.

  • Hugging Face 모델을 서버 프로세스로 상시 로딩
  • API 요청마다 모델을 재로딩하지 않음
  • ECI VM을 실제 서비스 서버처럼 활용 가능
  • CPU / GPU 환경 모두 동일한 방식 적용 가능

문제 해결 (Troubleshooting)​

모델 로딩이 느린 경우​

  • 서버 시작 시 한 번만 로딩되는 것이 정상
  • 워커 수 증가 시 메모리 사용량 주의

외부 접속이 안 되는 경우​

  • Public IP 설정 여부 확인
  • 보안 그룹 / 방화벽 규칙 확인

다음 단계​

  • GPU VM에서 대형 LLM API 서버 배포
  • vLLM 기반 OpenAI 호환 API 서버
  • FastAPI + LLM 기반 서비스 아키텍처
  • ECI 멀티 GPU / 멀티 노드 서빙 구성

관련 문서​