Train, Serve, and Deploy a Scikit-learn Model with FastAPI
Prompt & Circuit Editorial
May 26, 2026 · 12 Min Read

TL;DR
- Project:
sklearn-fastapi-app, withapp/for the API andartifacts/for the saved model. - Model: a random forest trained on scikit-learn's built-in breast cancer dataset, saved with joblib.
- API:
GET /healthandPOST /predict, which takes a JSON payload and returns a class and probabilities. - Run locally:
fastapi dev, then openhttp://127.0.0.1:8000/docs. - Deploy:
fastapi loginandfastapi deploypush the app to FastAPI Cloud, which is in public beta. The same app runs anywhere you can runfastapi 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
lifespancontext 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 oflifespan. - 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/exceptthat turns every error into a 500. - Keeps feature order explicit.
FEATURE_ORDERmatches the column order ofload_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.iofor cases where that matters. - Keep large artifacts out of the deploy bundle.
- Add tests that cover feature order and invalid input.
Sources
Responses (0)
Sign in to join the conversation and share your thoughts.

Prompt & Circuit Editorial
Contributing Editor
Articles on AI infrastructure for cloud architects, written from official vendor sources and checked claim by claim before publishing.
Continue Reading

Implementing Hybrid Semantic and Lexical Search for RAG with BM25 and Reciprocal Rank Fusion
Dense embeddings miss exact identifiers and BM25 misses paraphrases. This walk-through combines both in Python with rank_bm25, sentence-transformers and Reciprocal Rank Fusion, and explains the trade-offs before you move it to a search engine.

Demystifying LangChain Models: From LLMs to Embeddings in Plain English
A plain-English guide to LangChain's model layer: chat models, legacy text-completion LLMs, embedding models, invoke(), key parameters, and how embeddings power semantic search, with code for the current LangChain 1.x APIs.

Building Human-in-the-Loop Agentic Workflows with LangGraph
How to pause a LangGraph workflow for human approval with interrupt(), resume it with Command, and design review steps that hold up in production.