본문으로 건너뛰기
Machine Learning Mastery

FastAPI를 활용한 머신러닝 모델 배포 실무 가이드

scikit-learn으로 학습한 모델을 FastAPI와 Pydantic을 사용하여 검증 가능한 HTTP API로 패키징하고 로컬에서 테스트하는 전 과정을 단계별로 제시한다.

섹션별 상세

01
scikit-learn의 Pipeline과 StandardScaler를 사용하여 전처리와 모델 학습 과정을 하나로 묶고, joblib 라이브러리를 통해 학습된 객체를 파일로 저장한다. 이는 배포 환경에서 학습 시와 동일한 전처리가 수행되도록 보장하여 데이터 일관성 문제를 방지한다.
python
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LinearRegression
import joblib

# Pipeline = preprocessing + model
pipeline = Pipeline([
    ("scaler", StandardScaler()),
    ("model", LinearRegression())
])
pipeline.fit(X, y)

# Save the entire pipeline
joblib.dump(pipeline, "house_price_model.joblib")

scikit-learn 파이프라인을 사용하여 전처리와 모델을 결합하고 학습된 결과를 파일로 저장하는 예시

머신러닝 모델이 FastAPI를 거쳐 예측 결과를 생성하는 전체 흐름도
Diagram학습된 모델이 API 뒤에 배치되어 외부 요청을 받고 주택 가격 예측($235K)을 반환하는 개념적 워크플로우를 보여준다. 모델 학습부터 실제 예측까지의 연결 과정을 시각화한다.
02
FastAPI 애플리케이션을 생성할 때 서버 시작 시점에 모델을 한 번만 로드하여 메모리에 유지함으로써 추론 요청 시마다 발생하는 파일 읽기 오버헤드를 제거한다. 이 방식은 대규모 트래픽 환경에서도 빠른 응답 속도를 유지하는 데 필수적이다.
python
from fastapi import FastAPI
from pydantic import BaseModel
import joblib

app = FastAPI(title="House Price Prediction API")

# Load model once at startup
model = joblib.load("house_price_model.joblib")

FastAPI 앱을 생성하고 서버 시작 시 학습된 모델을 메모리에 로드하는 코드

03
Pydantic의 BaseModel을 상속받은 클래스를 정의하여 API가 받는 JSON 데이터의 타입과 구조를 엄격하게 제한한다. 이는 잘못된 데이터 입력 시 모델이 충돌하는 것을 방지하며, 동시에 API 문서를 자동으로 생성하는 기반이 된다.
python
class HouseInput(BaseModel):
    rooms: int
    age: float
    distance: float

Pydantic을 사용하여 API 입력 데이터의 구조와 타입을 정의하는 클래스

04
POST 메서드를 사용하는 /predict 엔드포인트를 생성하여 입력 데이터를 모델의 피처 형식으로 변환하고 예측 결과를 반환하는 로직을 구현한다. 예측값은 소수점 둘째 자리까지 반올림하여 사용자 친화적인 JSON 형식으로 응답한다.
python
@app.post("/predict")
def predict_price(data: HouseInput):
    features = [[ data.rooms, data.age, data.distance ]]
    prediction = model.predict(features)
    return {
        "predicted_price": round(prediction[0], 2)
    }

입력 데이터를 받아 모델 예측을 수행하고 결과를 반환하는 POST 엔드포인트 구현

05
Uvicorn 서버를 실행하고 FastAPI가 기본 제공하는 /docs 경로의 Swagger UI를 활용해 실제 데이터를 입력하고 예측 결과를 즉시 확인한다. 별도의 프론트엔드나 클라이언트 코드 없이도 API의 동작 유효성을 검증할 수 있다.
bash
uvicorn main:app --reload

Uvicorn을 사용하여 FastAPI 애플리케이션을 로컬 서버에서 실행하는 명령어

FastAPI의 자동 생성 Swagger UI 문서 화면
Screenshot로컬 서버에서 실행 중인 'House Price Prediction API'의 Swagger UI 화면을 보여준다. 정의된 /predict 엔드포인트와 데이터 스키마(HouseInput)가 자동으로 문서화된 모습을 확인할 수 있다.
Swagger UI에서 실제 데이터를 입력하고 Execute 버튼을 누르는 테스트 과정
Screenshot방 개수, 연식, 거리 데이터를 JSON 형식으로 입력하고 실행하여 API 응답을 확인하는 단계를 보여준다. 코드 작성 없이도 모델의 추론 결과를 즉시 검증할 수 있음을 시연한다.
06
운영 환경의 안정성을 위해 API의 상태를 확인하는 /health 엔드포인트를 추가하고, requirements.txt를 통해 프로젝트의 라이브러리 의존성을 명확히 관리한다. 이러한 작은 실무적 조치들이 배포 환경에서의 시간 낭비를 줄여준다.

용어 해설

파이단틱(Pydantic)
— 파이썬 타입 힌트를 사용하여 데이터 검증과 설정을 관리하는 라이브러리이다. API로 들어오는 입력 데이터가 정의된 구조와 타입에 맞는지 런타임에 확인하여 시스템의 안정성을 높이는 역할을 수행한다.
스웨거 UI(Swagger UI)
— OpenAPI 사양을 기반으로 API의 구조를 시각화하고 브라우저에서 직접 테스트할 수 있게 해주는 도구이다. FastAPI는 이를 기본 내장하여 별도 설정 없이도 대화형 API 문서를 생성한다.
유비콘(Uvicorn)
— 파이썬을 위한 초고속 ASGI(Asynchronous Server Gateway Interface) 서버 구현체이다. FastAPI 애플리케이션을 실행하기 위한 웹 서버 엔진으로 사용되며 비동기 처리에 최적화되어 있다.
잡립(joblib)
— 파이썬 객체를 디스크에 저장하고 불러오는 직렬화 라이브러리이다. 특히 대규모 넘파이 배열을 포함하는 머신러닝 모델을 효율적으로 처리하도록 설계되어 scikit-learn 모델 저장에 자주 쓰인다.
파이프라인(Pipeline)
— 데이터 전처리와 모델 학습 단계를 하나의 객체로 묶어 관리하는 기법이다. 학습 시 적용한 스케일링 등의 변환 과정을 추론 시에도 동일하게 적용하도록 보장하여 데이터 일관성을 유지한다.

기술

  • FastAPI
  • Pydantic
  • scikit-learn
  • joblib
  • uvicorn
  • pandas

활용 사례

  • 주택 가격 예측 API
  • 실시간 추론 서비스 구축
  • ML 모델 프로토타이핑

언급된 리소스

AI 분석 전체 내용 보기

AI 요약 · 북마크 · 개인 피드 설정 — 무료

출처 · 인용 안내

원문 발행 2026. 01. 20.수집 2026. 02. 21.출처 타입 RSS

인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.