Implementation:Bentoml BentoML Models Create

Implementation Metadata
Implementation Name	Models Create
API	bentoml.models.create()
Source	src/bentoml/models.py:L327-378
Workflow	Model_Store_Management
Domain	ML_Serving, Model_Management
Implements	Principle:Bentoml_BentoML_Model_Persistence
Last Updated	2026-02-13 15:00 GMT

Overview

The bentoml.models.create() function is a context manager that creates a new model entry in the BentoML local model store. It yields a Model instance whose .path attribute points to a dedicated directory where callers write model artifact files. The context manager ensures atomic saves with proper cleanup on failure.

Import

import bentoml

Signature

@contextlib.contextmanager
def create(
    name: Tag | str,
    *,
    labels: dict[str, Any] = None,
    metadata: dict[str, Any] = None,
    module: str = "",
    api_version: str = "v1",
    signatures: ModelSignaturesType = {},
    options: ModelOptions = ModelOptions(),
    custom_objects: dict = None,
    context: ModelContext = ModelContext(...),
) -> Generator[Model, None, None]

Parameters

Parameter	Type	Default	Description
name	str	required	Model tag in the form "name" or "name:version". If no version is provided, one is auto-generated.
labels	dict[str, Any]	None	Key-value pairs for filtering and organizing models (e.g., {"framework": "pytorch", "team": "nlp"}).
metadata	dict[str, Any]	None	Arbitrary metadata attached to the model (e.g., accuracy scores, hyperparameters, training dataset info).
module	str	""	The Python module that saved the model (e.g., "bentoml.pytorch").
api_version	str	"v1"	API version for the model store format.
signatures	ModelSignaturesType	{}	Model method signatures used for runner inference.
options	ModelOptions	ModelOptions()	Framework-specific options for the model.
custom_objects	dict	None	Additional Python objects to serialize alongside the model.
context	ModelContext	auto-detected	Context recording Python version and framework version.

Inputs and Outputs

Inputs:

• Model name (or full tag) and model files/objects to save into the yielded directory

Outputs:

• Yields: A Model instance during the context manager block. Callers write files to model_ref.path.
• On disk: Model files saved to <bentoml_home>/models/<name>/<version>/
• Side effect: A "latest" symlink is updated to point to the new version

Usage Example

import bentoml
import pickle

# Train your model
trained_model = train_my_model()

# Persist to BentoML store
with bentoml.models.create(
    "my_classifier",
    labels={"framework": "sklearn", "task": "classification"},
    metadata={"accuracy": 0.95, "dataset": "iris"},
) as model_ref:
    with open(model_ref.path_of("model.pkl"), "wb") as f:
        pickle.dump(trained_model, f)

print(f"Saved model: {model_ref.tag}")
# Output: Saved model: my_classifier:<auto-version>

Behavior Details

• If no version is specified in the tag, a unique version string is auto-generated using a timestamp-based scheme.
• The context manager creates a temporary directory, and on successful exit, moves it into the model store atomically.
• If an exception is raised inside the with block, the temporary directory is cleaned up and no model is registered.
• A "latest" symlink under <bentoml_home>/models/<name>/ is updated to point to the newest version.

Source Reference

File: src/bentoml/models.py, lines 327-378.

Knowledge Sources

• BentoML
• BentoML Docs