ModelVersion
#
Representation of all metadata about a specific model version.
import neptune
# Create a new model version for a model with identifier "CLS-PRE"
model_version = neptune.init_model_version(model="CLS-PRE")
# Initialize model version object from an existing model version
# with identifier "CLS-PRE-12"
model_version = neptune.init_model(with_id="CLS-PRE-12")
You can use the model_version
object to:
- Log and fetch metdata about the model version.
- Manage the stage of the model version.
Field lookup: []
#
You can access the field of a model version through a dict-like field lookup: model[field_path]
.
This way, you can
-
store metadata:
-
fetch already tracked metadata – for example, validation metrics for the model version:
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: Field |
Namespace handler object |
Example
import neptune
model_version = neptune.init_model_version(key="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, tracked 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.
See also: pop()
.
Examples
import neptune
model_version = neptune.init_model_version(with_id="CLS-TREE-3")
# Delete field with path "model/binary"
del model_version["model/binary"]
# You can also delete the whole namespace
del model_version["model"]
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 themodel_version
object to synchronize the local representation with the server. - Call
wait()
on themodel_version
object to wait for all tracking 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 = neptune.init_model(with_id="CLS-PRE")
# If an old dataset exists, remove it
if model.exists("dataset/v0.4"):
del model["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 Atom
fields (that are not of type File
) as a dictionary.
The result preserves the hierarchical structure of the model metadata, but contains only Atom
fields that are not of the type File
.
Returns
dict
containing the values of all non-File
Atom
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 model version
object in the form of a dictionary.
This method can be used to traverse the metadata structure programmatically when using Neptune in automated workflows.
See also: print_structure()
.
Warning
The returned object is a shallow copy of the internal structure. Any modifications to it may result in tracking malfunction.
Returns
dict
with the metadata structure of the model version.
Example
>>> import neptune
>>> model_version = neptune.init_model(with_id="CLS-PRE-3")
>>> model_version.get_structure()
{'model': {'binary': <neptune.attributes.atoms.file.File object at 0x000001C8EF8A1690>, 'parameters': {'eta': <neptune.attributes.atoms.float.Float object at 0x000001C8EF8A1780>, 'gamma': <neptune.attributes.atoms.float.Float object at 0x000001C8EF8A1840>, 'max_depth': <neptune.attributes.atoms.integer.Integer object at 0x000001C8EF8A1900>}}, ... }}
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(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.
See also del
.
Parameters
Name | Type | Default | Description |
---|---|---|---|
path |
str |
- | Path of the field or namespace to be removed. |
wait |
Boolean , optional |
False |
By default, tracked 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. |
Examples
import neptune
model_version = neptune.init_model_version(with_id="CLS-TREE-3")
# Delete a field along with its data
model_version.pop("model/binary")
# You can invoke pop() directly on fields and namespaces
# The following line
model_version.pop("model/binary")
# is equiavlent to this line
model_version["model/binary"].pop()
# or this line
model_version["model"].pop("binary")
# You can also batch-delete the whole namespace
model_version["model"].pop()
print_structure()
#
Pretty-prints the structure of the model metadata. Paths are ordered lexicographically and the structure is colored.
See also: get_structure()
Example
>>> import neptune
>>> model_version = neptune.init_model(with_id="CLS-PRE-3")
>>> model_version.print_structure()
'model':
'binary': File
'parameters':
'eta': Float
'gamma': Float
'max_depth': Integer
'sys':
'creation_time': Datetime
'id': String
'model_id': String
'modification_time': Datetime
'monitoring_time': Integer
'name': String
'owner': String
'ping_time': Datetime
'running_time': Float
'size': Float
'stage': String
'state': RunState
'tags': StringSet
'trashed': Boolean
'train':
'acc': Float
'dataset': Artifact
'val':
'acc': Float
'dataset': Artifact
stop()
#
Stops the connection to Neptune and synchronizes all data.
When using context managers, Neptune automatically calls stop()
when exiting the model version
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 tracking calls to finish before stopping the connection. If None , wait for all tracking 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 is 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, tracked 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 tracking 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. |