Model version
API reference page for the model version object

Model version

A Model version object, in a similar fashion as Run, is a representation of all metadata about a specific model version. You can use it to store and retrieve metadata about the model version and to manage its stage.

[] (field lookup)

You can access any model version's field through a dict-like field lookup model_version[field_path].
This way you can both store metadata:
1
model_version["model/binary"].upload("model.pt")
2
model_version["validation/dataset"].track_files("s3://datasets/validation")
3
model_version["validation/metrics/acc"] = 0.98
Copied!
as well as fetch already tracked metadata -- for example, fetching validation metrics for the model version:
1
model_version = neptune.init_model_version(version="PROJ-MOD-3")
2
val_acc = model_version["validation/metrics/acc"].fetch()
3
if val_acc >= ACC_THRESHOLD:
4
model_version.change_stage("staging")
Copied!

Returns

The returned type depends on the field's type and whether a field is stored under the given path.
Field
Returns
The field exists.
The field does not exist
Handler object
The path is a namespace e.g. model when a field model/signature exists.

=

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 one command.
Parameters
Text
value
(dict ) - A dictionary with values to assign, where keys 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, default is False) - If True the client will first wait to send all tracked metadata to the server. This makes the call synchronous, see Connection modes guide.

Examples

1
import neptune.new as neptune
2
model_version = neptune.init_model_version(model="PROJ-MOD")
3
4
# Assign multiple fields from a dictionary
5
model_info = {"size_limit": 50.0, "size_units": "MB"}
6
model_version["model"] = model_info
7
8
# You can always explicitly store metadata piece by piece
9
model_version["model/size_limit"] = 50.0
10
model_version["model/size_units"] = "MB"
11
12
# Dictionaries can be nested
13
model_info = {"size": {"limit": 50.0}}
14
model_version["model"] = model_version
15
# This will store the number 50.0 under path "model/size/limit"
Copied!

.print_structure()

Pretty prints the structure of the model version's metadata. Paths are ordered lexicographically and the whole structure is neatly colored.
See also: .get_structure().

.change_stage()

Changes the stage of the model version. Possible stages are "none", "staging", "production", and "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 Neptune servers before executing it.
Parameters
Text
stage
(str ) - The new stage of the model. Possible stages are "none", "staging", "production", and "archived".

Examples

1
import neptune.new as neptune
2
model_version = neptune.init_model_version(version="PROJ-MOD-3")
3
4
# If the model is good enough promote it to the staging
5
val_acc = model_version["validation/metrics/acc"].fetch()
6
if val_acc >= ACC_THRESHOLD:
7
model_version.change_stage("staging")
Copied!

.get_structure()

Returns a model version's metadata structure in the form of a dictionary.
This method can be used to traverse the model version's metadata structure programmatically when using Neptune in automated workflows.
The returned object is a shallow copy of the internal structure. Any modifications to it may result in tracking malfunction.

Returns

dict with the model version's metadata structure.

del

Completely removes the field or whole namespace stored under the path and all data associated with them. See also .pop().

Examples

1
import neptune.new as neptune
2
model_version = neptune.init_model_version(version="PROJ-MOD-3")
3
4
# Delete a field with path "model/binary"
5
del model_version["model/binary"]
6
7
# You can also delete the whole namespace
8
del model_version["model"]
Copied!

.pop()

Removes the field or whole namespace stored under the path completely and all data associated with them. See also .del().
Parameters
Text
path
(str ) - Path of the field or namespace to be removed.
wait
(Boolean, optional, default is False) - If True the client will wait before sending all tracked metadata to the server. This makes the call synchronous. For details, see the Connection modes guide.

Examples

1
import neptune.new as neptune
2
model_version = neptune.init_model_version(version="PROJ-MOD-3")
3
4
# Delete a field along with its data
5
model_version.pop("model/binary")
6
7
# .pop() can be invoked directly on fields and namespaces
8
9
# Following line
10
model_version.pop("model/binary")
11
# is equiavlent to this line
12
model_version["model/binary"].pop()
13
# or this line
14
model_version["model"].pop("binary")
15
16
# You can also delete in batch whole namespace
17
model_version["model"].pop()
Copied!

.exists()

Checks if there is a field or namespace under the specified path.
Note that this method checks the local representation of the model. The field may have been created by another process (use .sync() to synchronize local representation) or the metadata may have not reached the Neptune servers, so it may be impossible to fetch (use .wait() to wait for all tracking calls to finish).
Parameters
Text
path
(str) - The path to check for the existence of a field or a namespace

Examples

1
import neptune.new as neptune
2
model_version = neptune.init_model_version(version="PROJ-MOD-3")
3
4
# Remove validation metrics associated with a deleted dataset:
5
if model_version.exists("validation/dataset_3"):
6
del model_version["validation/dataset_3"]
Copied!
When working in the asynchronous (default) mode, your tracked metadata may not be immediately available to fetch from the server even if it appears in the local representation. To circumvent that, you can use .wait().
1
import neptune.new as neptune
2
model_version = neptune.init_model_version(version="PROJ-MOD-3")
3
4
model_version["model/binary"].upload("model.pt")
5
6
# The path exists in the local representation
7
if model_version.exists("model/binary"):
8
# However, the tracking call may have not reached Neptune servers yet
9
model_version["model/binary"].download() # Error - the field does not exist
Copied!

.stop()

Stops the connection to the model version and kills the synchronization thread. .stop() will be automatically called when a script that initialized the connection finishes or when exiting the Neptune context.
When using Neptune with Jupyter notebooks, it's a good practice to stop the connection manually. Otherwise it's automatically stopped only when the Jupyter kernel stops.
Parameters
Text
seconds
(int or float, optional, default is None) - The method will wait for the specified time for all tracking calls to finish, before stopping the connection. If None, it will wait for all tracking calls to finish.

Example

If you are initializing the connection from a script, you don't need to call .stop():
1
import neptune.new as neptune
2
model_version = neptune.init_model_version(model="PROJ-MOD")
3
4
[...] # Your code
5
6
# If you are executing Python script, then .stop()
7
# is automatically called at the end for every Neptune object
Copied!
If you are initializing multiple connections from one script, it is a good practice to call .stop() for any unneeded connections. You can also use Context Managers -- Neptune will automatically call .stop() when exiting the ModelVersion context:
1
import neptune.new as neptune
2
3
# If you are initializing multiple connections from the same script,
4
# stop the connection manually once not needed
5
for model_version_id in model_versions:
6
model_version = neptune.init_model_version(version=model_version_id)
7
[...] # Your code
8
model_version.stop()
9
10
# You can also use "with" statement and context manager
11
for model_version_id in model_versions:
12
with neptune.init_model_version(version=model_version_id) as model_version:
13
[...] # Your code
14
# .stop() is automatically called
15
# when code execution exits the with statement
Copied!
If you are using Jupyter notebooks for connecting to a model version, you need to manually invoke .stop() once the connection is not needed.

.fetch()

Fetch values of all non-File Atom fields as a dictionary.
The result will preserve the hierarchical structure of the model version's metadata but will contain only non-File Atom fields.

Returns

dict containing all non-File Atom fields values.

Examples

1
import neptune.new as neptune
2
model_version = neptune.init_model_version(version="PROJ-MOD-3")
3
4
# Fetch all the validation metrics
5
val_metrics = model_version["validation/metrics"].fetch()
Copied!

.get_url()

Returns the URL of the model version in Neptune.

returns

str with the URL of the model version in Neptune

.wait()

Wait for all the tracking calls to finish.
Parameters
Text
disk_only
(Boolean, optional, default is False) - If True the process will only wait for data to be saved locally from memory, but will not wait for them to reach Neptune servers.

.sync()

Synchronizes local representation of the model version with Neptune servers.
Parameters
Text
wait
(Boolean, optional, default is True) - If True the client will wait before sending all tracked metadata to the server. This makes the call synchronous. For details, see the Connection modes guide.