Principle:Bentoml BentoML Model Cleanup
| Principle Metadata | |
|---|---|
| Principle Name | Model Cleanup |
| Workflow | Model_Store_Management |
| Domain | ML_Serving, Model_Management |
| Related Principle | Principle:Bentoml_BentoML_Model_Versioning, Principle:Bentoml_BentoML_Model_Persistence |
| Implemented By | Implementation:Bentoml_BentoML_Models_Delete |
| Last Updated | 2026-02-13 15:00 GMT |
Overview
Model Cleanup is the principle of removing model artifacts from the local BentoML store to free disk space and maintain a manageable set of model versions. It addresses the practical concern that development and CI environments accumulate many model versions over time.
Core Concept
Removing model artifacts from the local filesystem store to free resources is essential for maintaining healthy development and deployment environments. Without cleanup, the model store grows unboundedly as new versions are saved during iterative development, automated training runs, and CI/CD pipelines.
Theory
Model cleanup removes specific model versions from the local filesystem store. The key design considerations are:
Version-Specific Deletion
Cleanup operates on individual model versions, not entire model names. This allows fine-grained control over which versions to retain (e.g., keep the latest production model but remove older experimental versions).
Latest Symlink Management
The store maintains a "latest" symlink for each model name. When the version currently pointed to by "latest" is deleted, the symlink is updated to point to the next most recent version. If no versions remain, the symlink (and the model name directory) is removed entirely.
Filesystem-Level Removal
Deletion removes the model's directory and all its contents from <bentoml_home>/models/<name>/<version>/. This includes:
- Serialized model artifact files
- The
model.yamldescriptor - Any custom objects stored alongside the model
Irreversibility
Deletion from the local store is permanent. There is no trash or undo mechanism. If the model was previously pushed to BentoCloud or exported to an archive, it can be recovered from those sources. Otherwise, the model must be retrained and re-saved.
Use Cases
Development Cleanup
During iterative development, many experimental model versions accumulate. Periodic cleanup removes versions that are no longer needed:
# List all versions
models = bentoml.models.list("my_model")
# Keep only the 5 most recent, delete the rest
for model in models[5:]:
bentoml.models.delete(model.tag)
CI/CD Pipeline Cleanup
Automated training pipelines may save a new model version on every run. Cleanup steps at the end of pipelines prevent disk exhaustion on build agents.
Disk Space Recovery
Large ML models (especially deep learning models) can consume significant disk space. Cleanup is the primary mechanism for reclaiming this space in the local store.
Design Principles
Explicit Over Implicit
BentoML does not automatically delete old model versions. Cleanup is always an explicit action, preventing accidental data loss. Users must decide which versions to remove.
Safe Deletion
The delete operation validates that the specified model exists before attempting removal. If the model is not found, a NotFound error is raised rather than silently succeeding.
Consistent Store State
After deletion, the store remains in a consistent state. The "latest" symlink is updated, directory structures are clean, and subsequent list/get operations reflect the change immediately.
Relationship to Other Principles
- Model Persistence: Cleanup is the inverse of persistence, removing what was previously saved.
- Model Versioning: Cleanup interacts with the versioning system, particularly the
"latest"symlink resolution. - Model Cloud Sync: Models pushed to BentoCloud are not affected by local cleanup. Cloud sync can serve as a backup before cleanup.
- Model Export/Import: Exported archives are not affected by local cleanup and can be used to restore deleted models.