Implementation:Bentoml BentoML BentoModel Descriptor

Implementation Metadata
Implementation Name	BentoModel Descriptor
API	BentoModel class
Source	src/_bentoml_sdk/models/base.py:L65-178
Workflow	Model_Store_Management
Domain	ML_Serving, Model_Management
Implements	Principle:Bentoml_BentoML_Model_Loading_From_Store
Last Updated	2026-02-13 15:00 GMT

Overview

The BentoModel class is an attrs-frozen descriptor that resolves BentoML model tags to StoredModel instances. It checks the local model store first and falls back to pulling from BentoCloud if the model is not found locally. It is the primary mechanism for declaring model dependencies in BentoML services.

Import

from bentoml.models import BentoModel

Class Definition

@attrs.frozen
class BentoModel(Model[StoredModel]):
    tag: Tag = attrs.field(converter=Tag.from_taglike)

Key Methods

Method	Signature	Description
resolve()	resolve(base_path=None) -> StoredModel	Resolves the model tag to a StoredModel. Checks the local store first; if not found, pulls from BentoCloud. The base_path parameter allows resolution relative to a bento directory.
to_info()	to_info() -> BentoModelInfo	Converts the model reference to a BentoModelInfo object containing the tag and module information, used for serializing model references in bento configurations.
stored (property)	None	Returns the resolved StoredModel if already resolved, or None if not yet resolved. Does not trigger resolution.

Parameters

Parameter	Type	Description
tag	str	BentoML model tag (e.g., "my_model:latest", "my_model:abc123"). Automatically converted via Tag.from_taglike.

Inputs and Outputs

Inputs:

• A BentoML model tag (e.g., "my_model:latest")

Outputs:

• A StoredModel instance with:
  • .path — filesystem path to the model artifact directory
  • .tag — the resolved immutable tag
  • .info — model metadata (labels, creation time, framework info)

Resolution Behavior

The resolve() method follows this sequence:

1. Check the local BentoML model store for the given tag
2. If found locally, return the StoredModel
3. If not found locally and BentoCloud credentials are configured, attempt to pull the model from BentoCloud
4. If pulled successfully, return the StoredModel
5. If not found anywhere, raise a NotFound error

Usage Example

import bentoml
from bentoml.models import BentoModel

@bentoml.service
class TextClassifier:
    # Declare model dependency at class level
    model = BentoModel("text_classifier:latest")

    @bentoml.api
    def predict(self, text: str) -> str:
        # Access resolved model — lazy resolution on first access
        model_path = self.model.path
        # Load and use the model artifact from model_path
        ...

Descriptor Behavior

BentoModel is an attrs frozen class, meaning it is immutable after construction. The tag field uses a converter (Tag.from_taglike) that accepts both string and Tag inputs:

# These are equivalent
model_a = BentoModel("my_model:latest")
model_b = BentoModel(Tag("my_model", "latest"))

Source Reference

File: src/_bentoml_sdk/models/base.py, lines 65-178.

Knowledge Sources

• BentoML
• BentoML Docs