Skip to content

Use a model

The common Model object methods apply across model kinds. They let you persist or refresh an entity, handle its files, and log metrics.

Persist and refresh

These methods interact with the entity in the backend or locally.

update

Update the entity in the backend.

Returns:

Type Description
ContextEntity

Entity updated.

export

Export object as a YAML file in the context folder.

Returns:

Type Description
str

Exported filepath.

refresh

Refresh object from backend.

Returns:

Type Description
ContextEntity

Entity refreshed.

File I/O

Use these methods to handle model files.

as_file

Download the entity's files to a temporary local directory.

Returns:

Type Description
list[str]

Paths to the downloaded files.

download

Download the entity's files to a local destination.

Parameters:

Name Type Description Default
destination str

Local destination directory. If omitted, use the project context directory for this entity type.

None
overwrite bool

Whether to overwrite existing files.

False

Returns:

Type Description
str

Destination path returned by the store.

upload

Upload local files to the entity's storage path.

Parameters:

Name Type Description Default
source SourcesOrListOfSources

Local file or files to upload.

required
keep_dir_structure bool

Whether to preserve the source directory structure.

False

Raises:

Type Description
EntityErrorFileNotFound

If a source file does not exist.

EntityError

If the upload fails for another supported storage or filesystem error.

files

Return file objects associated with the entity.

Returns:

Type Description
list[MaterialFile]

Objects built from the files API or the entity status.

Metrics

The common Model object can record one or more metrics and exposes them through its metrics property.

metrics

Get metrics from entity status.

Returns:

Type Description
dict[str, MetricType]

Metrics dictionary.

log_metric

Log metric into entity status. A metric is named by a key and value (single number or list of numbers). The metric by default is put in a list or appended to an existing list. If single_value is True, the value will be a single number.

Parameters:

Name Type Description Default
key str

Key of the metric.

required
value MetricType

Value of the metric.

required
overwrite bool

If True, overwrite existing metric.

False
single_value bool

If True, value is a single value.

False

Examples:

Log a new value in a list

>>> entity.log_metric("loss", 0.002)

Append a new value in a list

>>> entity.log_metric("loss", 0.0019)

Log a list of values and append them to existing metric:

>>> entity.log_metric(
...     "loss",
...     [
...         0.0018,
...         0.0015,
...     ],
... )

Log a single value (not represented as list):

>>> entity.log_metric(
...     "accuracy",
...     0.9,
...     single_value=True,
... )

Log a list of values and overwrite existing metric:

>>> entity.log_metric(
...     "accuracy",
...     [0.8, 0.9],
...     overwrite=True,
... )
log_metrics

Log metrics into entity status. If a metric is a list, it will be logged as a list. Otherwise, it will be logged as a single value.

Parameters:

Name Type Description Default
metrics dict[str, MetricType]

Dict of metrics to log.

required
overwrite bool

If True, overwrite existing metrics.

False

Examples:

Log multiple metrics at once

>>> entity.log_metrics(
...     {
...         "loss": 0.002,
...         "accuracy": 0.95,
...     }
... )

Log metrics with lists and single values

>>> entity.log_metrics(
...     {
...         "loss": [
...             0.1,
...             0.05,
...         ],
...         "epoch": 10,
...     }
... )

Append to existing metrics (default behavior)

>>> entity.log_metrics(
...     {
...         "loss": 0.001,
...         "accuracy": 0.96,
...     }
... )  # Appends to existing

Overwrite existing metrics

>>> entity.log_metrics(
...     {
...         "loss": 0.0005,
...         "accuracy": 0.98,
...     },
...     overwrite=True,
... )
See Also

log_metric

Kind-specific APIs and runtime workflows

Runtime-specific model classes only define their constructors and kind-specific data; they do not add instance methods beyond the common Model interface documented above. Kind-specific log_*() and register_*() APIs are functions, not Model methods; see the kind pages.

Serving is a separate runtime workflow that uses a runtime Function, not a Model method. See the ModelServe runtime or the TVM runtime.