0Pricing
Machine Learning Academy · 강의

FastAPI 엔드포인트로 예측 제공하기

학습자는 joblib 모델을 JSON 페이로드를 받아 예측을 반환하는 FastAPI POST 경로로 감싸고, curl 요청으로 테스트합니다.

FastAPI 엔드포인트로 예측 제공하기은(는) CoddyKit의 무료 Machine Learning Academy 강의입니다. 이것은 4개 중 3번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Machine Learning Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Machine Learning Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

이 강의의 일부는 아직 번역되지 않았으며 영어로 표시됩니다.

From Notebook to Production API

A Jupyter notebook is a great development environment but a terrible production serving system. The standard path from notebook to production is: train and save a model with joblib, wrap it in a REST API, and deploy that API as a containerised service. The API accepts raw feature values as JSON, preprocesses them through the fitted pipeline, and returns predictions in milliseconds.

Why FastAPI for ML Serving?

FastAPI is a modern Python web framework built on Pydantic and Starlette. It generates automatic interactive documentation (Swagger UI), validates request bodies with type hints, and handles async I/O efficiently. For ML serving, FastAPI is popular because it requires very little boilerplate, supports concurrent requests via async workers, and integrates naturally with Python data types used in sklearn and pandas.

Installing FastAPI and Uvicorn

FastAPI requires uvicorn as the ASGI server to run it. Install both with a single command. uvicorn is a high-performance async server that handles HTTP connections and passes requests to the FastAPI application. In production, you would typically run uvicorn behind an nginx reverse proxy with multiple worker processes.

# pip install fastapi uvicorn[standard]

# Verify installation
from fastapi import FastAPI
from pydantic import BaseModel
import uvicorn

print('FastAPI ready')

Defining the Request Schema with Pydantic

Pydantic BaseModel classes define the structure of incoming requests. FastAPI uses these models to automatically validate JSON bodies — if a required field is missing or has the wrong type, FastAPI returns a clear 422 error before your code even runs. Each field in the Pydantic model corresponds to one input feature for the model.

from pydantic import BaseModel
from typing import Optional

class IrisFeatures(BaseModel):
    sepal_length: float
    sepal_width: float
    petal_length: float
    petal_width: float

class PredictionResponse(BaseModel):
    predicted_class: int
    class_name: str
    confidence: float

# Example input (FastAPI will validate this automatically)
input_data = IrisFeatures(sepal_length=5.1, sepal_width=3.5,
                           petal_length=1.4, petal_width=0.2)
print('Input:', input_data)

Loading the Model at Startup

Load the model once at startup, not on every request. Loading a joblib file on every prediction would add hundreds of milliseconds of latency per request. Use a module-level variable or a FastAPI lifespan event handler to load the model when the server starts and keep it in memory for all subsequent requests.

import joblib
from contextlib import asynccontextmanager
from fastapi import FastAPI

ml_models = {}

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup: load model once
    ml_models['iris'] = joblib.load('/tmp/iris_pipeline.joblib')
    print('Model loaded at startup')
    yield
    # Shutdown: cleanup if needed
    ml_models.clear()

app = FastAPI(title='Iris Predictor API', lifespan=lifespan)

Creating the Prediction Endpoint

Define a POST route that accepts the Pydantic input model, converts it to a NumPy array, calls pipeline.predict and predict_proba, and returns the prediction as a structured JSON response. FastAPI serialises Pydantic response models automatically.

import numpy as np
from fastapi import FastAPI
from pydantic import BaseModel
import joblib

app = FastAPI()
model = None

@app.on_event('startup')
def load_model():
    global model
    model = joblib.load('/tmp/iris_pipeline.joblib')

CLASS_NAMES = ['setosa', 'versicolor', 'virginica']

@app.post('/predict')
def predict(features: IrisFeatures):
    X = np.array([[features.sepal_length, features.sepal_width,
                   features.petal_length, features.petal_width]])
    pred = int(model.predict(X)[0])
    proba = float(model.predict_proba(X)[0].max())
    return {
        'predicted_class': pred,
        'class_name': CLASS_NAMES[pred],
        'confidence': round(proba, 4)
    }

Adding a Health Check Endpoint

A /health or /ping endpoint is essential for production services. Load balancers and orchestration systems (Kubernetes, ECS) call this endpoint periodically to confirm the service is alive. A healthy response means the server is running AND the model is loaded. Return 503 if the model failed to load.

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get('/health')
def health():
    if model is None:
        return JSONResponse(status_code=503,
                            content={'status': 'unhealthy', 'reason': 'model not loaded'})
    return {'status': 'ok', 'model': 'iris_pipeline', 'version': '1.0.0'}

@app.get('/')
def root():
    return {'message': 'Iris Predictor API — POST /predict to get a classification'}

Running the Server Locally

Save the FastAPI app to main.py and start it with uvicorn main:app --reload. The --reload flag auto-restarts on file changes (development only). Navigate to http://localhost:8000/docs to see the auto-generated Swagger UI where you can test predictions interactively.

# Save to main.py then run:
# uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Test with curl:
# curl -X POST http://localhost:8000/predict \
#   -H 'Content-Type: application/json' \
#   -d '{"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2}'
#
# Expected response:
# {"predicted_class": 0, "class_name": "setosa", "confidence": 0.9981}

print('Command to start: uvicorn main:app --reload --port 8000')

Testing the Endpoint with the requests Library

In a test script or notebook, use requests.post to call your running API. This is also how client applications (mobile apps, dashboards, other microservices) consume the prediction API. The same request format works from any language — curl, JavaScript fetch, Go's http.Client.

import requests

url = 'http://localhost:8000/predict'
payload = {
    'sepal_length': 6.3,
    'sepal_width': 3.3,
    'petal_length': 6.0,
    'petal_width': 2.5
}

response = requests.post(url, json=payload)
if response.status_code == 200:
    result = response.json()
    print('Predicted class:', result['class_name'])
    print('Confidence:', result['confidence'])
else:
    print('Error:', response.status_code, response.text)

Input Validation and Error Handling

FastAPI's Pydantic validation catches type errors automatically, but you should also handle model-level errors (e.g., unexpected NaN values, out-of-range inputs). Use try/except inside the route function and return a 400 or 500 with a meaningful error message. Avoid leaking internal error details (stack traces) to API callers in production.

from fastapi import FastAPI, HTTPException
import numpy as np

app = FastAPI()

@app.post('/predict')
def predict(features: IrisFeatures):
    try:
        X = np.array([[features.sepal_length, features.sepal_width,
                       features.petal_length, features.petal_width]])
        if np.any(np.isnan(X)) or np.any(X < 0):
            raise HTTPException(status_code=400,
                                detail='Input contains invalid values (NaN or negative)')
        pred = int(model.predict(X)[0])
        proba = float(model.predict_proba(X)[0].max())
        return {'predicted_class': pred, 'confidence': round(proba, 4)}
    except HTTPException:
        raise
    except Exception as e:
        raise HTTPException(status_code=500, detail='Internal prediction error')

Batch Prediction Endpoint

For high-throughput use cases, add a batch endpoint that accepts a list of feature sets and returns a list of predictions in one API call. Batching reduces network overhead and allows the model to vectorise predictions efficiently (sklearn predict handles matrices).

from typing import List
from pydantic import BaseModel
import numpy as np

class BatchRequest(BaseModel):
    instances: List[IrisFeatures]

@app.post('/predict/batch')
def predict_batch(batch: BatchRequest):
    X = np.array([[f.sepal_length, f.sepal_width, f.petal_length, f.petal_width]
                  for f in batch.instances])
    preds = model.predict(X).tolist()
    probas = model.predict_proba(X).max(axis=1).tolist()
    return {'predictions': [{'class': p, 'confidence': round(c, 4)}
                            for p, c in zip(preds, probas)]}

Quick Check

Test your understanding of serving ML predictions with FastAPI from this lesson.

Lesson Recap

In this lesson you learned: FastAPI wraps a joblib-loaded pipeline into a typed REST endpoint with automatic JSON validation and Swagger documentation, load the model once at startup to avoid per-request disk I/O latency, and always include a /health endpoint so load balancers and orchestrators can verify the service is alive. Next up we add prediction logging to the API and discuss data drift and model retraining triggers.

자주 묻는 질문

“FastAPI 엔드포인트로 예측 제공하기” 강의는 무료인가요?

네 — “FastAPI 엔드포인트로 예측 제공하기” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Machine Learning Academy 강의 전체를 잠금 해제할 수 있습니다. Machine Learning Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“FastAPI 엔드포인트로 예측 제공하기”에서 뭘 배우나요?

학습자는 joblib 모델을 JSON 페이로드를 받아 예측을 반환하는 FastAPI POST 경로로 감싸고, curl 요청으로 테스트합니다. 브라우저에서 직접 실행하는 실습 코드로 Machine Learning Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Machine Learning Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Machine Learning Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 3번째 강의입니다.

“FastAPI 엔드포인트로 예측 제공하기” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Machine Learning Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Machine Learning Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

  1. joblib와 pickle을 이용한 모델 저장
  2. 모델 버전 관리: 파일 이름과 메타데이터가 중요한 이유
  3. FastAPI 엔드포인트로 예측 제공하기
  4. 예측 모니터링: 입력과 출력 기록하기
← Machine Learning Academy(으)로 돌아가기