Skip to main content

Model Artifacts and Safe Serialization

A model artifact crosses a trust boundary. It contains learned state and often executable or interpreter-dependent structure. Format choice must consider prediction needs, compatibility, validation, and security—not only file size or convenience.

Prerequisites​

Complete Reproducible Training Pipelines. Know the difference between training a model and loading a trained representation.

Learning goals​

  • explain why pickle-based formats require trusted provenance.
  • distinguish a reconstructable teaching artifact from a general estimator serializer.
  • bind model bytes to environment, data, code, and evaluation evidence.

Never load an untrusted pickle​

Python's pickle can execute arbitrary code during deserialization. joblib and cloudpickle use pickle-compatible mechanisms and inherit that risk. Never load an untrusted pickle/joblib/cloudpickle model. A file extension, checksum from the same untrusted source, antivirus scan, or successful load does not establish trust.

Verify provenance and integrity before any deserialization, restrict who can publish artifacts, sign or attest the supply path where appropriate, and load risky formats only inside a tightly controlled environment. Matching a digest to a trusted registry record detects tampering; it does not make a maliciously approved object safe.

Worked example​

Study Sprint publishes an inert, schema-versioned JSON representation rather than a Python object:

{
  "format": "datasciencebase.linear-logit.v1",
  "source_features": ["prior_score", "practice_minutes", "learning_track"],
  "feature_names": ["numeric__x0", "numeric__x1", "categorical__x2_advanced", "categorical__x2_foundations"],
  "numeric_means": [64.28125, 38.5625],
  "numeric_scales": [13.8185, 13.6792],
  "categories": [["advanced", "foundations"]],
  "coefficients": ["<four finite numbers>"],
  "intercept": ["<one finite number>"],
  "prediction_threshold": 0.5
}

The real file contains numeric arrays sufficient to reconstruct this narrow linear-logit calculation. It is not a general scikit-learn persistence format, and this ticket does not ship a serving loader. Any future loader must validate the schema, dimensions, finite numeric values, allowed operations, size limits, and supported version before calculation.

Other choices have different boundaries. ONNX can separate serving from Python but supports only convertible models and still requires resource controls. skops.io provides inspection and a safer trust workflow for supported scikit-learn objects, but unknown types still require a decision. Native pickle/joblib requires the same trusted environment and compatible dependencies; scikit-learn does not support arbitrary cross-version loading.

Artifact completeness​

Model bytes alone are not enough. Preserve the training recipe, immutable training-data reference, code version, dependency versions, feature schema/order, class mapping, threshold, metrics, and intended use. Include a checksum in the run record and registry. If preprocessing is required for predictions, serialize it with the model contract rather than relying on a separate undocumented notebook.

Common mistakes​

  • Downloading a .pkl file and loading it to “see what is inside.”
  • Trusting an artifact because its SHA-256 matches a digest delivered beside it by the same unknown party.
  • Loading a model under different library versions because no exception appeared.
  • Serializing the classifier while omitting learned preprocessing and feature order.
  • Calling JSON automatically safe without schema, size, and numeric validation.

Practice​

Create a threat model for moving Study Sprint's model from training to serving. Identify the producer, storage, reviewer, transport, verifier, loader, and rollback owner. Mark where integrity, authenticity, authorization, and compatibility are checked.

Next steps​

Model Registry and Lineage adds governed identity, review state, and promotion history around immutable artifacts.

Primary sources​

Checked 2026-10-15: Python pickle security warning, scikit-learn model persistence guidance, ONNX security guidance, and SLSA provenance.