Model Serialization & Registries
One artifact, versioned, with metadata that travels
A model artifact must round-trip: save weights + schema + metadata in one auditable bundle, stored in a registry where 'the model' means a versioned, promoted artifact — not a pickle in a repo.
What you will learn
- Serialize models with correct tooling and schema metadata
- Store artifacts with versioning and promotion states
- Guard against untrusted-deserialization risks
What is this?
Serialization turns a trained model into a loadable artifact (joblib/pickle for sklearn, torch.save, ONNX for portable graphs). A registry elevates this into governance: each registered version carries metadata (metrics, git commit, schema, data hash) and moves through states — staging → production, with rollback and ACLs. The artifact plus its metadata is what actually deploys; the training notebook is not the model.
Why do you need it?
- Registries make 'which model is live?' a query, not an argument.
- Schema + metadata on the artifact prevents 'wrong shape at 3am' incidents.
- Rollback is one promotion command, not a code archaeology dig.
- ONNX/portable formats resist framework-version rot that plain pickles suffer.
Mental model
A pharmacy dispensing only voucher-controlled medication
A model registry
Every pill has a batch number (version), a leaflet (metadata/schema), and a signed release (promotion). You never pocket raw compounds from a lab bench; you pull the registered batch with its paperwork — and you can recall any batch by number.
How it works
- Serialization: joblib (sklearn), torch.save (state_dict), ONNX export (portable graphs).
- Bundle: artifact + manifest (schema, feature list, pre/postprocessors, model version, deps).
- Register: push to registry with unique version; record git commit, metrics, data hash.
- Promote: staging → production through a gate (tests + metrics + approval).
- Consume: deployments pull pinned versions; rollback = repoint to previous version.
Train → package → register → promote.
In production
- CI promotes only artifacts that pass eval gates into the registry's production state.
- Shadow deploys pin the same registry version, diffed before full cutover.
- Audits: every serving instance reports its artifact version for lineage.
Best practices
- Version the artifact, always; never overwrite a registered version.
- Record the input/output schema in the manifest — validating at serve time catches skew early.
- Prefer portable formats (ONNX) when deploying across runtimes.
- Test the ARTIFACT (load → predict), not the training code, before promotion.
Common mistakes
- Pickling with framework-versioned classes then upgrading the framework mid-fleet.
- Storing the artifact in the git repo (huge, unversioned-by-content).
- Promoting on 'it loaded' without schema/metric gates.
- Untrusted pickle loading — arbitrary code execution from a poisoned artifact.
Common issues
Artifact fails to load after framework bumpPickled class version mismatch
Standardize on portable formats (ONNX) or pin runtime versions in the image.
Wrong schema accepted silentlyNo manifest validation at load
Validate input schema against the manifest before serving the first request.
Two deployables claim the same versionRegistry allows overwrite
Make versions immutable; add unique hashes to artifact names.
Debugging tips
- Load the artifact in a fresh process and predict one row before any promotion.
- Compare artifact-level predictions to training-time predictions (they should match exactly).
- Check manifest fields on load; a missing feature column fails loudly, not silently.
- Roll forward, then roll back, in staging at least once per release cycle.
Interview checkpoint
Hands-on lab
- Serialize + reload a model with schema metadata
- Write a manifest bundle
- Guard the load path against version drift
Package a Model Artifact
30 min · intermediate
Quick quiz
A model registry's core value over a file folder is:
Loading an untrusted pickle is safe if you only use the model for predictions.