Model Versioning
Intermediate 14 min read Model Versioning

Binaries and Signatures

Schema for the model's front door

A model signature is the input/output contract a serving endpoint enforces: feature names, types, shapes, and output space. Binaries + signatures turn a model into an API with a schema.

model signatureinput schemaoutput contractinput validationserving contract
Prerequisites: Why Version Models
Before we start

What you will learn

  • Define a model signature and its components
  • Enforce input validation before inference
  • Use signatures to prevent silent serving bugs
Introduction

What is this?

A model signature is the declared contract of the model API: expected input feature names, dtypes, shapes, and the structure of outputs. Serving layers validate incoming requests against it, and training records it, so malformed input gets a clear 400 instead of a silent, wrong prediction.

Motivation

Why do you need it?

  • Runtime feature mismatches (renamed column, wrong dtype) are common and silent killers in serving.
  • A contract makes clients and the model independent — schema is the API.
  • Validation up front turns 'inscrutable NaN output' into a readable error.
  • Signatures travel in the artifact, so every deployment enforces the same contract.
Think about it

Mental model

Imagine

An entrance questionnaire at a doctor's office

Think of

Model signature validation

Name, age, blood type must be filled correctly before the doctor (model) can work. Ask the wrong questions or receive typos and misdiagnosis follows. The signature form ensures the right, well-formed inputs arrive.

Mechanics

How it works

  • During training, the model's input and output schema is extracted (feature names, types, shapes, categorical vocabulary).
  • The signature is serialized with the artifact (MLflow signature blocks, ONNX input dict).
  • The serving layer validates request columns/dtypes against the signature before scoring.
  • Rejections return explicit 4xx errors and log the mismatch reason.
  • Schema checks also run in batch pipelines so neither path serves junk silently.

Signature enforcement between request and inference.

Client request
Schema check
Valid
Invalid
Hands-on

Examples

Enforcing a signature at serving time

Enforcing a signature at serving time
from pydantic import BaseModel
class LoanInput(BaseModel):
    age: int
    income: float
    region: Literal["eu", "us", "ap"]
 
@app.post("/predict")
def predict(req: LoanInput):
    payload = [req.age, req.income, {"eu": 0, "us": 1, "ap": 2}[req.region]]
    return {"score": model.predict([payload])[0]}

Pydantic (or an ML-serving signature block) enforces names, types and allowed enums before the model runs — a wrong region typo gets a 422, not a silent misprediction.

Real world

In production

  • MLflow serves models with input_example and signature blocks, validating on every request.
  • A batch scoring job reads a signature and rejects a column-renamed export before scoring.
  • An API gateway logs signature violations as data-quality incidents, paging the data owner.
Guidelines

Best practices

  • Record the signature in the artifact at training time — never 'reverse engineer' at serving.
  • Validate both batch and real-time inputs against the same signature.
  • Include categorical vocabularies and value ranges where enums/limits exist.
  • Return actionable errors: which column, which type, which expected value.
Watch out

Common mistakes

  • Serving models with no signature, so type drifts pass silently.
  • Signatures drifting from the training features ('trust me, it matches').
  • Reaching into raw inputs with hardcoded indexes instead of schema-aware routing.
  • Only validating shape and forgetting dtypes and categorical constraints.
When things break

Debugging tips

  • 'Model returns NaN for everything' — run the inputs through the signature checker first.
  • Batch job succeeds but numbers are wrong — the export's column order changed; the signature catches it.
  • 400s spike? Clients need the new signature — version your client contract too.
Interviews

Interview checkpoint

Practice

Hands-on lab

Wrap a Model with an Enforced Signature
25 min · intermediate
In progress
Objectives
  • Define a JSON signature for a small model
  • Enforce the signature with a request validator
  • Observe valid vs invalid requests

Wrap a Model with an Enforced Signature

25 min · intermediate

0/3 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/2
1

Which is the best description of a model signature?

2

Serving a model without a signature makes malformed inputs fail silently.

Go deeper

Official documentation

MLflow model signatures
docs