tracking-model-versions

Model Versioning Tracker

Overview

Track and manage AI/ML model versions using MLflow, DVC, or Weights & Biases. Log model metadata (hyperparameters, training data hash, framework version), record evaluation metrics (accuracy, F1, latency), manage model registry transitions (Staging, Production, Archived), and generate model cards documenting lineage and performance.

Prerequisites

• MLflow tracking server running locally or remotely (mlflow server or managed MLflow)
• Python 3.9+ with mlflow, pandas, and the relevant ML framework installed
• Model artifacts accessible on the local filesystem or cloud storage (S3, GCS)
• Write access to the MLflow tracking URI and artifact store

Instructions

1. Connect to the MLflow tracking server by setting MLFLOW_TRACKING_URI and verify connectivity with mlflow experiments list.
2. Create or select an MLflow experiment for the model project using mlflow experiments create --experiment-name <name>.
3. Log a new model version: start an MLflow run, log parameters (learning rate, epochs, batch size), log metrics (accuracy, loss, F1 score), and log the model artifact with mlflow.<flavor>.log_model().
4. Register the model in the MLflow Model Registry using mlflow.register_model() with the run URI and a descriptive model name.
5. Transition the model version through stages: None -> Staging -> Production using client.transition_model_version_stage(). Archive previous production versions.
6. Compare model versions by querying metrics across runs with mlflow.search_runs() and generating comparison tables showing metric improvements between versions.
7. Generate a model card from the registered model metadata, including training data description, evaluation metrics, intended use, limitations, and ethical considerations. See ${CLAUDE_SKILL_DIR}/assets/model_card_template.md.
8. Set up automated alerts for model performance degradation by comparing production metrics against baseline thresholds stored in the model registry.

See ${CLAUDE_SKILL_DIR}/assets/example_mlflow_workflow.yaml for a complete workflow configuration.

Examples

Tracking a new image classification model version: Log a ResNet-50 fine-tuned on a custom dataset. Record hyperparameters (lr=0.001, epochs=50, optimizer=Adam), metrics (val_accuracy=0.94, val_loss=0.18, inference_latency_ms=12), and the serialized model artifact. Register as version 3 in the model registry and transition to Staging for validation.

Comparing model versions before production promotion: Query MLflow for all versions of the sentiment-analysis model. Generate a comparison table showing accuracy improved from 0.87 (v2) to 0.91 (v3) while inference latency increased from 8ms to 15ms. Recommend promoting v3 to Production only if latency is acceptable for the use case.

Generating a model card for compliance review: Extract metadata from MLflow model registry version 5: training dataset (100K customer reviews), evaluation results (F1=0.89 on held-out test set), known limitations (struggles with sarcasm and multilingual input), and intended use (customer feedback classification). Output a structured Markdown model card.

Output

• MLflow run with logged parameters, metrics, and model artifact
• Model registry entry with version number and stage assignment
• Version comparison table with metric deltas across runs
• Model card in Markdown format documenting lineage, performance, and limitations

Error Handling

Error	Cause	Solution
MLflow connection refused	Tracking server not running or wrong URI	Verify MLFLOW_TRACKING_URI is correct; start server with mlflow server --host 0.0.0.0 --port 5000
Artifact upload failed	Insufficient permissions on artifact store	Check S3/GCS bucket permissions; verify IAM role has write access to the artifact path
Model registration conflict	Model name already exists with incompatible schema	Use a versioned model name or delete the conflicting registry entry
Metrics not logged	MLflow run ended before logging completed	Ensure all log_metric() calls happen within the active run context (with mlflow.start_run():)
Stage transition denied	Model version already in target stage	Archive the existing version in that stage first, then retry the transition

Resources

• MLflow documentation: https://mlflow.org/docs/latest/index.html
• MLflow Model Registry: https://mlflow.org/docs/latest/model-registry.html
• DVC (Data Version Control): https://dvc.org/doc
• Weights & Biases Model Registry: https://docs.wandb.ai/guides/model-registry
• ML Model Cards: https://modelcards.withgoogle.com/about