`ModelVersion`#

Representation of all metadata about a specific model version.

Initialization#

Initialize with the init_model_version() function or the class constructor.

init_model_version()ModelVersion()

import neptune

run = neptune.init_model_version(model="MODEL-ID")

from neptune import ModelVersion

model_version = ModelVersion(model="MODEL-ID")

If Neptune can't find your project name or API token

As a best practice, you should save your Neptune API token and project name as environment variables:

export NEPTUNE_API_TOKEN="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jvYh3Kb8"
export NEPTUNE_PROJECT="ml-team/classification"

You can, however, also pass them as arguments when initializing Neptune:

run = neptune.init_run( # (1)!
    api_token="h0dHBzOi8aHR0cHM6Lkc78ghs74kl0jvYh3Kb8",  # your token here
    project="ml-team/classification",  # your full project name here
)

Also works for init_model(), init_model_version(), and init_project().
API token: In the bottom-left corner, expand the user menu and select Get my API token.
Project name: in the top-right menu: → Edit project details.

If you haven't registered, you can also log anonymously to a public project (make sure not to publish sensitive data through your code!):

run = neptune.init_run(
    api_token=neptune.ANONYMOUS_API_TOKEN,
    project="common/quickstarts",
)

You can use the model_version object to:

Log and fetch metadata about a specific version of the model.
Manage the lifecycle stage of the model version.

Parameters

Name	Type	Default	Description
`with_id`	`str`, optional	`None`	The Neptune identifier of an existing model version to resume, such as "CLS-PRE-3". The identifier is stored in the object's `sys/id` field. If omitted or `None` is passed, a new model version is created.
`name`	`str`, optional	`"Untitled"`	A custom name for the model version. You can use it as a human-readable ID and add it to the model versions table as a column (`sys/name`).
`model`	`str`, optional	`None`	Identifier of the model for which the new version should be created. Required when creating a new model version. The identifier is stored in the model's `sys/id` field.
`project`	`str`, optional	`None`	Name of a project in the form `workspace-name/project-name`. If `None`, the value of the `NEPTUNE_PROJECT` environment variable is used.
`api_token`	`str`, optional	`None`	Your Neptune API token (or a service account's API token). If `None`, the value of the `NEPTUNE_API_TOKEN` environment variable is used. To keep your token secure, avoid placing it in source code. Instead, save it as an environment variable.
`mode`	`str`, optional	`async`	Connection mode in which the logging will work. Possible values are `async`, `sync`, `read-only`, and `debug`. If you leave it out, the value of the `NEPTUNE_MODE` environment variable is used. If that's not set, the default `async` is used.
`flush_period`	`float`, optional	`5` (seconds)	In asynchronous (default) connection mode, how often Neptune should trigger disk flushing.
`proxies`	`dict`, optional	`None`	Argument passed to HTTP calls made via the Requests library. For details on proxies, see the Requests documentation.
`async_lag_callback`	`NeptuneObjectCallback`, optional	`None`	Custom callback function which is called if the lag between a queued operation and its synchronization with the server exceeds the duration defined by `async_lag_threshold`. The callback should take a `ModelVersion` object as the argument and can contain any custom code, such as calling `stop()` on the object. Note: Instead of using this argument, you can use Neptune's default callback by setting the `NEPTUNE_ENABLE_DEFAULT_ASYNC_LAG_CALLBACK` environment variable to `TRUE`.
`async_lag_threshold`	`float`, optional	`1800.0` (seconds)	Duration between the queueing and synchronization of an operation. If a lag callback (default callback enabled via environment variable or custom callback passed to the `async_lag_callback` argument) is enabled, the callback is called when this duration is exceeded.
`async_no_progress_callback`	`NeptuneObjectCallback`, optional	`None`	Custom callback function which is called if there has been no synchronization progress whatsoever for the duration defined by `async_no_progress_threshold`. The callback should take a `ModelVersion` object as the argument and can contain any custom code, such as calling `stop()` on the object. Note: Instead of using this argument, you can use Neptune's default callback by setting the `NEPTUNE_ENABLE_DEFAULT_ASYNC_NO_PROGRESS_CALLBACK` environment variable to `TRUE`.
`async_no_progress_threshold`	`float`, optional	`300.0` (seconds)	For how long there has been no synchronization progress. If a no-progress callback (default callback enabled via environment variable or custom callback passed to the `async_no_progress_callback` argument) is enabled, the callback is called when this duration is exceeded.

Returns

ModelVersion object that is used to manage the model version and log metadata to it.

Examples

Connect to an existing model version with the identifier CLS-PRE-8

from neptune import ModelVersion

model_version = ModelVersion(with_id="CLS-PRE-8")

Field lookup: `[]`#

You can access the field of a model version through a dict-like field lookup: model_version[field_path].

This way, you can

store metadata:

model_version["model/binary"].upload("model.pt")
model_version["validation/dataset"].track_files("s3://datasets/validation")
model_version["validation/metrics/acc"] = 0.98

fetch already logged metadata – for example, validation metrics for the model version:

model_version = neptune.init_model_version(with_id="CLS-TREE-3")
val_acc = model_version["validation/metrics/acc"].fetch()
if val_acc >= ACC_THRESHOLD:
    model_version.change_stage("staging")

Returns

The returned type depends on the field type and whether a field is stored under the given path.

Path Example Returns

Field exists - The returned type matches the type of the field

Field does not exist - Handler object

Path is namespace and has field

Path: "model"

Field "model/binary" exists

Namespace handler object

Example

import neptune

model_version = neptune.init_model_version(model="CLS-PRE")

# Create new Float field
model_version["validation/acc"] = 50
# Update the value of the field
model_version["validation/acc"] = 100
# Error - it's no longer possible to store a File under a Float field
model_version["validation/acc"].upload("acc.bmp")  # Error

# Create new Series fields
model_version["train/logs"].append("Model registry, day 1:")
# Continue logging to existing Series fields
model_version["train/logs"].append("A model version is born")

# If you access a namespace handler, you can interact with it like an object
val_ns = model_version["validation"]
val_ns["accuracy"] = 0.76  # Stores 0.76 under path "validation/accuracy"

Assignment: `=`#

Convenience alias for assign().

`assign()`#

Assign values to multiple fields from a dictionary. You can use this method to store multiple pieces of metadata with a single command.

Parameters

Name	Type	Default	Description
`value`	`dict`	`None`	A dictionary with values to assign, where keys (`str`) become the paths of the fields. The dictionary can be nested, in which case the path will be a combination of all keys.
`wait`	`Boolean`, optional	`False`	By default, logged metadata is sent to the server in the background. With this option set to `True`, Neptune first sends all data before executing the call. See Connection modes.

Example

import neptune

model_version = neptune.init_model_version(model="CLS-TREE")

# Assign multiple fields from a dictionary
model_info = {"size_limit": 50.0, "size_units": "MB"}
model_version["model"] = model_info

# You can also store metadata piece by piece
model_version["model/size_limit"] = 50.0
model_version["model/size_units"] = "MB"

# Dictionaries can be nested
model_info = {"size": {"limit": 50.0}}
model_version["model"] = model_version
# This will store the number 50.0 under path "model/size/limit"

`change_stage()`#

Changes the stage of the model version. The available stages are:

None
Staging
Production
Archived

In order to change the stage of the model version directly, you need contributor permissions within the project.

This method is always synchronous, which means that Neptune will wait for all other calls to reach the Neptune servers before executing it.

Parameters

Name	Type	Default	Description
`stage`	`str`	`None`	The new stage of the model version. Possible values are `"none"`, `"staging"`, `"production"`, and `"archived"`.

Example

import neptune

model_version = neptune.init_model_version(with_id="CLS-TREE-3")

# If the model is good enough, promote it to the staging
val_acc = model_version["validation/metrics/acc"].fetch()

if val_acc >= ACC_THRESHOLD:
    model_version.change_stage("staging")

`del`#

Completely removes the field or namespace and all associated metadata stored under the path.

If you need to free up storage or reduce the number of fields, can use del to remove unneeded metadata that takes up space, such as notebook training checkpoints.

`exists()`#

Checks if there is a field or namespace under the specified path.

Info

This method checks the local representation of the model version. If the field was created by another process or the metadata has not reached the Neptune servers, it may not be possible to fetch. In this case you can:

Call sync() on the model_version object to synchronize the local representation with the server.
Call wait() on the model_version object to wait for all logging calls to finish.

Parameters

Name	Type	Default	Description
`path`	`str`	-	Path to check for the existence of a field or namespace

Examples

import neptune

model_version = neptune.init_model_version(with_id="CLS-PRE-8")

# If an old dataset exists, remove it
if model_version.exists("dataset/v0.4"):
    del model_version["dataset/v0.4"]

Info

When working in asynchronous (default) mode, the metadata you track may not be immediately available to fetch from the server, even if it appears in the local representation.

To work around this, you can call wait() on the model_version object.

import neptune

model_version = neptune.init_model_version(with_id="CLS-TREE-3")

model_version["model/binary"].upload("model.pt")

# The path exists in the local representation
if model_version.exists("model/binary"):
    # However, the tracking call may have not reached Neptune servers yet
    model_version["model/binary"].download()  # Error: the field does not exist

model_version.wait()

`fetch()`#

Fetches the values of all single-value fields (that are not of type File) as a dictionary.

The result preserves the hierarchical structure of the model metadata.

Returns

dict containing the values of all non-File single-value fields.

Example

import neptune

model_version = neptune.init_model_version(with_id="CLS-TREE-3")

# Fetch all the validation metrics
val_metrics = model_version["validation/metrics"].fetch()

`get_structure()`#

Returns the metadata structure of a ModelVersion object in the form of a dictionary.

This method can be used to traverse the metadata structure programmatically when using Neptune in automated workflows.

`get_url()`#

Returns a direct link to model version in Neptune. The same link is printed in the console once the model_version object has been initialized.

Returns

str with the URL of the model version in Neptune.

Example

>>> import neptune
>>> model_version = neptune.init_model_version(with_id="CLS-PRE-3")
>>> model_version.get_url()
https://app.neptune.ai/ml-team/classification/m/CLS-PRE/v/CLS-PRE-3

`pop()`#

Completely removes the field or namespace and all associated metadata stored under the path.

`print_structure()`#

Pretty-prints the structure of the model metadata. Paths are ordered lexicographically and the structure is colored.

`stop()`#

Stops the connection to Neptune and synchronizes all data.

When using context managers, Neptune automatically calls stop() when exiting the ModelVersion context.

Warning

Always call stop() in interactive environments, such as a Python interpreter or Jupyter notebook. The connection to Neptune is not stopped when the cell has finished executing, but rather when the entire notebook stops.

If you're running a script, the connection is stopped automatically when the script finishes executing. However, it's a best practice to call stop() when the connection is no longer needed.

Parameters

Name	Type	Default	Description
`seconds`	`int` or `float`, optional	`None`	Wait for the specified time for all logging calls to finish before stopping the connection. If `None`, wait for all logging calls to finish.

Examples

If you initializing the connection from a Python script, Neptune stops it automatically when the script finishes executing.

import neptune

model_version = neptune.init_model_version(model="CLS-TREE")

[...] # Your code

# stop() is automatically called at the end for every Neptune object

If you are initializing multiple connections from one script, it's a good practice to call stop() for any unneeded connections:

import neptune

for model_version_id in model_versions:
    model_version = neptune.init_model_version(version=model_version_id)
    [...] # Your code
    model_version.stop()

Using with statement and context manager:

for model_version_id in model_versions:
    with neptune.init_model_version(version=model_version_id) as model_version:
        [...] # Your code
        # stop() is automatically called
        # when code execution exits the with statement

`sync()`#

Synchronizes the local representation of the model version with Neptune servers.

Parameters

Name	Type	Default	Description
`wait`	`Boolean`, optional	`False`	By default, logged metadata is sent to the server in the background. With this option set to `True`, Neptune first sends all data before executing the call. See Connection modes.

`wait()`#

Wait for all the logging calls to finish.

Parameters

Name	Type	Default	Description
`disk_only`	`Boolean`, optional	`False`	If `True`, the process will wait only for the data to be saved locally from memory, but will not wait for it to reach Neptune servers.

Name	Type	Default	Description
`path`	`str`	-	Path of the field or namespace to be removed.
`wait`	`Boolean`, optional	`False`	By default, logged metadata is sent to the server in the background. With this option set to `True`, Neptune first sends all data before executing the call. See Connection modes.

ModelVersion#

Initialization#

Field lookup: []#

Assignment: =#

assign()#

change_stage()#

del#

exists()#

fetch()#

get_structure()#

get_url()#

pop()#

print_structure()#

stop()#

sync()#

wait()#

`ModelVersion`#

Field lookup: `[]`#

Assignment: `=`#

`assign()`#

`change_stage()`#

`del`#

`exists()`#

`fetch()`#

`get_structure()`#

`get_url()`#

`pop()`#

`print_structure()`#

`stop()`#

`sync()`#

`wait()`#