---

name: model-management description: "Manage BentoML model stores, model references, framework save/load helpers, optional dependencies, and model troubleshooting for services and builds." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

BentoML Model Management

Use this sub-skill when an agent needs to save, inspect, package, load, import/export, or diagnose BentoML models. Keep service endpoint design in ../service-authoring/SKILL.md; keep Bento build/container packaging mechanics in ../packaging-and-containerization/SKILL.md; keep BentoCloud deployment in ../cli-and-cloud/SKILL.md.

First Decision

1. Need a model dependency in a Service or Bento build? Declare BentoModel("name:version"), BentoModel("name:latest"), or HuggingFaceModel("org/model") as a Service class variable so BentoML can include/resolve it during build and deployment.
2. Need to put files into BentoML's local store? Use bentoml.models.create(name) as a context manager for arbitrary model directories, or a framework helper such as bentoml.sklearn.save_model() when that framework helper is appropriate and installed.
3. Need to inspect or move a stored model? Use bentoml models list/get/export/import/delete or the Python equivalents under bentoml.models.
4. Need to load framework-native objects? Prefer the matching helper (bentoml.sklearn.load_model, bentoml.pytorch.load_model, etc.) only when the stored model's module matches that helper and its optional dependencies are present.

Model Store Essentials

• BentoML stores models by tag (name:version) and supports :latest resolution. bentoml.models.get(tag) returns a bentoml.Model; bentoml.models.list(name_or_none) returns stored model objects.
• bentoml.models.create(name) yields a model reference with path and path_of(...); write or copy model files inside that directory, then let the context manager flush and save on successful exit.
• Model metadata includes the saved module, labels, options, metadata, context, signatures, BentoML version, Python version, and creation time. Use it to diagnose helper mismatch and serialization/version mismatch.
• Import/export moves BentoML model archives or folders between stores. Use framework save/import APIs for raw framework artifacts; bentoml.models.import_model() expects an exported BentoML model archive or folder.
• Store location is controlled by the installed BentoML configuration and environment. If a model appears missing, inspect the active process environment and bentoml models list --output json before assuming the tag is wrong.

Service Loading Pattern

Declare model dependencies at Service class scope, then load the framework object in __init__ or a method:

import bentoml
from bentoml.models import BentoModel

@bentoml.service
class IrisService:
    model_ref = BentoModel("iris_sklearn:latest")

    def __init__(self):
        import joblib
        self.model = joblib.load(self.model_ref.path_of("model.pkl"))

Class-scope declaration is important: BentoML records the model dependency for build, push, and deployment. Creating BentoModel(...) only inside __init__ can produce a Bento that starts without the referenced model and later fails with a model not found error.

For Hugging Face Hub models, use HuggingFaceModel("org/model") as a class variable and pass the resolved path to transformers loaders in __init__. Private or gated Hub models require the appropriate token in the runtime/build environment; do not bake secrets into skill content or service source.

Commands And APIs

• List models: bentoml models list or bentoml.models.list().
• Inspect a model: bentoml models get MODEL_TAG, bentoml models get MODEL_TAG --output json, bentoml models get MODEL_TAG --output path, or bentoml.models.get("MODEL_TAG").
• Export/import: bentoml models export MODEL_TAG OUT_PATH, bentoml models import MODEL_PATH, bentoml.models.export_model(tag, path), and bentoml.models.import_model(path).
• Delete: bentoml models delete MODEL_TAG --yes or bentoml.models.delete(tag). Deletion can fail if a local Bento references the model.
• Cloud transfer: bentoml models push MODEL_TAG and bentoml models pull MODEL_TAG require BentoCloud auth; keep deployment/cloud workflow in ../cli-and-cloud/SKILL.md.

Bundled Helpers

• scripts/inspect_model_store.py lists model tags, modules, locations, metadata keys, context, and optional tag details. It is read-only.
• scripts/check_framework_extra.py checks whether a framework helper's Python modules are importable and warns about deprecated helper-module usage. It does not install packages or download models.

References

• Model store operations: references/model-store.md.
• Framework helpers and optional dependencies: references/frameworks.md.
• Troubleshooting: references/troubleshooting.md.