AI Engineeringfastapi

Train, Serve, and Deploy a Scikit-learn Model with FastAPI

P&C

Prompt & Circuit Editorial

May 26, 2026 · 12 Min Read

Train, Serve, and Deploy a Scikit-learn Model with FastAPI

TL;DR

  • Project: sklearn-fastapi-app, with app/ for the API and artifacts/ for the saved model.
  • Model: a random forest trained on scikit-learn's built-in breast cancer dataset, saved with joblib.
  • API: GET /health and POST /predict, which takes a JSON payload and returns a class and probabilities.
  • Run locally: fastapi dev, then open http://127.0.0.1:8000/docs.
  • Deploy: fastapi login and fastapi deploy push the app to FastAPI Cloud, which is in public beta. The same app runs anywhere you can run fastapi run.

The code below was run against scikit-learn 1.9.1, FastAPI 0.159.1, Pydantic 2.14.1, joblib 1.6.0 and NumPy 2.5.4 on Python 3.13.

Project layout and setup

mkdir sklearn-fastapi-app && cd sklearn-fastapi-app
mkdir app artifacts
touch app/__init__.py

Final tree:

sklearn-fastapi-app/
├── app/
│   ├── __init__.py
│   └── main.py
├── artifacts/
│   └── breast_cancer_model.joblib   (created by train.py)
├── train.py
└── pyproject.toml

pyproject.toml:

[project]
name = "sklearn-fastapi-app"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "fastapi[standard]==0.159.1",
    "scikit-learn==1.9.1",
    "joblib==1.6.0",
    "numpy==2.5.4",
]

Install the dependencies into a virtual environment:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install "fastapi[standard]==0.159.1" "scikit-learn==1.9.1" "joblib==1.6.0" "numpy==2.5.4"

Pinning exact versions is more than good hygiene here. The scikit-learn documentation states that there is no supported way to load a model trained with a different scikit-learn version, and that doing so can give different results or crash the process. Train and serve with the same pinned versions.

Training the model

train.py:

from pathlib import Path

import joblib
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score
from sklearn.model_selection import train_test_split


def main() -> None:
    data = load_breast_cancer()
    X, y = data.data, data.target

    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42, stratify=y
    )

    model = RandomForestClassifier(n_estimators=200, random_state=42)
    model.fit(X_train, y_train)

    acc = accuracy_score(y_test, model.predict(X_test))
    artifact = {
        "model": model,
        "target_names": data.target_names.tolist(),
        "feature_names": data.feature_names.tolist(),
    }

    out = Path("artifacts/breast_cancer_model.joblib")
    out.parent.mkdir(parents=True, exist_ok=True)
    joblib.dump(artifact, out)

    print(f"Model saved to: {out}")
    print(f"Test accuracy: {acc:.4f}")


if __name__ == "__main__":
    main()

Running python train.py with the versions above printed:

Model saved to: artifacts/breast_cancer_model.joblib
Test accuracy: 0.9561

That is 109 of 114 held-out samples correct. Treat it as a single split on a small, clean benchmark dataset, not as evidence of how the model would perform clinically. In this dataset, class 0 is malignant and class 1 is benign.

A random forest is a reasonable default for tabular data, but it is worth checking whether a simpler model such as logistic regression meets the same accuracy with a smaller artifact and lower latency.

Building the FastAPI inference server

app/main.py:

from contextlib import asynccontextmanager
from pathlib import Path

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

ARTIFACT_PATH = Path(__file__).resolve().parent.parent / "artifacts" / "breast_cancer_model.joblib"

FEATURE_ORDER = [
    "mean_radius", "mean_texture", "mean_perimeter", "mean_area",
    "mean_smoothness", "mean_compactness", "mean_concavity",
    "mean_concave_points", "mean_symmetry", "mean_fractal_dimension",
    "radius_error", "texture_error", "perimeter_error", "area_error",
    "smoothness_error", "compactness_error", "concavity_error",
    "concave_points_error", "symmetry_error", "fractal_dimension_error",
    "worst_radius", "worst_texture", "worst_perimeter", "worst_area",
    "worst_smoothness", "worst_compactness", "worst_concavity",
    "worst_concave_points", "worst_symmetry", "worst_fractal_dimension",
]

ml = {}


@asynccontextmanager
async def lifespan(app: FastAPI):
    if not ARTIFACT_PATH.exists():
        raise RuntimeError(
            f"Model file not found at {ARTIFACT_PATH}. Run `python train.py` first."
        )
    artifact = joblib.load(ARTIFACT_PATH)
    ml["model"] = artifact["model"]
    ml["target_names"] = artifact["target_names"]
    yield
    ml.clear()


app = FastAPI(
    title="Breast Cancer Prediction API",
    version="1.0.0",
    description="FastAPI server for a scikit-learn breast cancer classifier",
    lifespan=lifespan,
)


class PredictionRequest(BaseModel):
    mean_radius: float
    mean_texture: float
    mean_perimeter: float
    mean_area: float
    mean_smoothness: float
    mean_compactness: float
    mean_concavity: float
    mean_concave_points: float
    mean_symmetry: float
    mean_fractal_dimension: float
    radius_error: float
    texture_error: float
    perimeter_error: float
    area_error: float
    smoothness_error: float
    compactness_error: float
    concavity_error: float
    concave_points_error: float
    symmetry_error: float
    fractal_dimension_error: float
    worst_radius: float
    worst_texture: float
    worst_perimeter: float
    worst_area: float
    worst_smoothness: float
    worst_compactness: float
    worst_concavity: float
    worst_concave_points: float
    worst_symmetry: float
    worst_fractal_dimension: float


class PredictionResponse(BaseModel):
    prediction_id: int
    prediction_label: str
    probabilities: dict[str, float]


@app.get("/health")
def health():
    return {"status": "ok"}


@app.post("/predict", response_model=PredictionResponse)
def predict(req: PredictionRequest):
    values = req.model_dump()
    features = np.array([[values[name] for name in FEATURE_ORDER]])

    model = ml["model"]
    names = ml["target_names"]
    pred_id = int(model.predict(features)[0])
    probs = model.predict_proba(features)[0]

    return PredictionResponse(
        prediction_id=pred_id,
        prediction_label=names[pred_id],
        probabilities={names[i]: round(float(p), 4) for i, p in enumerate(probs)},
    )

What this does

  • Loads the model once. The lifespan context manager runs before the app accepts requests, so the model is not re-read on every call. The older @app.on_event("startup") hook is deprecated in the FastAPI docs in favour of lifespan.
  • Resolves the artifact path from the file location, so the server finds the model whatever the working directory is.
  • Validates input. Pydantic rejects missing or non-numeric fields with an HTTP 422 response before the model is called, so there is no need to wrap the handler in a catch-all try/except that turns every error into a 500.
  • Keeps feature order explicit. FEATURE_ORDER matches the column order of load_breast_cancer().feature_names. A mismatch here would silently produce wrong predictions, which is one of the easiest serving bugs to introduce.
  • Declares the response model, so the output schema appears in the generated OpenAPI docs.

Local testing

Start the development server from the project root:

fastapi dev app/main.py

Open the interactive docs at http://127.0.0.1:8000/docs, or call the endpoint with curl. The payload below is the first row of the dataset:

curl -X POST "http://127.0.0.1:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "mean_radius": 17.99, "mean_texture": 10.38, "mean_perimeter": 122.8,
    "mean_area": 1001.0, "mean_smoothness": 0.1184, "mean_compactness": 0.2776,
    "mean_concavity": 0.3001, "mean_concave_points": 0.1471, "mean_symmetry": 0.2419,
    "mean_fractal_dimension": 0.07871, "radius_error": 1.095, "texture_error": 0.9053,
    "perimeter_error": 8.589, "area_error": 153.4, "smoothness_error": 0.006399,
    "compactness_error": 0.04904, "concavity_error": 0.05373,
    "concave_points_error": 0.01587, "symmetry_error": 0.03003,
    "fractal_dimension_error": 0.006193, "worst_radius": 25.38, "worst_texture": 17.33,
    "worst_perimeter": 184.6, "worst_area": 2019.0, "worst_smoothness": 0.1622,
    "worst_compactness": 0.6656, "worst_concavity": 0.7119,
    "worst_concave_points": 0.2654, "worst_symmetry": 0.4601,
    "worst_fractal_dimension": 0.1189
  }'

Response from our test run:

{
  "prediction_id": 0,
  "prediction_label": "malignant",
  "probabilities": {"malignant": 0.95, "benign": 0.05}
}

The same checks can run as an automated test with FastAPI's TestClient. Using it as a context manager triggers the lifespan handler, so the model loads:

from fastapi.testclient import TestClient
from sklearn.datasets import load_breast_cancer

from app.main import FEATURE_ORDER, app

row = dict(zip(FEATURE_ORDER, load_breast_cancer().data[0].tolist()))

with TestClient(app) as client:
    assert client.get("/health").json() == {"status": "ok"}
    assert client.post("/predict", json=row).json()["prediction_label"] == "malignant"
    assert client.post("/predict", json={"mean_radius": "abc"}).status_code == 422

Deploying to FastAPI Cloud

FastAPI Cloud is a hosting service from the team behind FastAPI and is currently in public beta, with a free Hobby plan and a paid Pro plan. The deploy commands ship with fastapi[standard]:

fastapi login     # opens a browser to authenticate
fastapi deploy    # deploys the project in the current directory

fastapi deploy takes the directory containing your pyproject.toml (the current directory by default). It warns about files larger than 10 MB, which matters for model artifacts; the model in this tutorial is about 650 KB. Larger models are better stored outside the source tree and downloaded at startup.

The FastAPI docs show the deploy finishing with a URL of the form https://myapp.fastapicloud.dev. Open <your-url>/docs to check the live endpoints.

FastAPI Cloud is optional. The same app runs on any container platform or VM with:

fastapi run app/main.py

Production checklist

  • Pin library versions and use the same ones for training and serving.
  • Store the training script, the data snapshot reference, library versions and the evaluation score alongside the model, as the scikit-learn persistence guide recommends.
  • Only load joblib or pickle files from trusted sources: loading them can execute arbitrary code. scikit-learn's guide points to skops.io for cases where that matters.
  • Keep large artifacts out of the deploy bundle.
  • Add tests that cover feature order and invalid input.

Sources

Tags:fastapiscikit-learnpythonmlopsmodel deployment
Share Article

Responses (0)

Sign in to join the conversation and share your thoughts.

P&C

Prompt & Circuit Editorial

Contributing Editor

Articles on AI infrastructure for cloud architects, written from official vendor sources and checked claim by claim before publishing.