Skip to content

Model#

Representation of all metadata about a model.

Initialize with the init_model() function:

Initialization
import neptune

# Create a new model
model = neptune.init_model(key="PRE")

# Initialize existing model with identifier "CLS-PRE"
model = neptune.init_model(with_id="CLS-PRE")

You can use the model object to:

  • Store and retrieve general metadata about a machine-learning model.
    • This can be the model signature, validation datasets, or anything else that is supposed to be common to all versions of the model.
  • List the created versions of that model.

Field lookup: []#

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

This way, you can

  • store metadata:

    model["model/signature"].upload("model_signature.json")

model["validation/data/v0.1"].track_files("s3://datasets/validation")
model.wait()
model["validation/data/latest"] = model["validation/data/v0.1"].fetch()

  • fetch already tracked metadata – for example, to have the single source of truth when evaluating a new model version:

    model_version = neptune.init_model_version(model="CLS-PRE")
model_version["validation/data"] = model["validation/data/latest"].fetch()
model["validation/data/latest"].download()

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/signature" exists

 Namespace handler object

Example

import neptune

model = neptune.init_model(key="PRE")

# Create new Float field
model["size/limit"] = 50

# Update the value of the field
model["size/limit"] = 100

# Error - it's no longer possible to store a File under a Float field
model["size/limit"].upload("large_model.pkl")  # Error

# Create new Series fields
model["train/logs"].append("Model registry, day 1:")

# Continue logging to existing Series fields
model["train/logs"].append("A model is born")

# If you access a namespace handler, you can interact with it like an object
info_ns = model["model_info"]
info_ns["size_units"] = "MB"  # Stores "MB" under path "model_info/size_units"

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 = neptune.init_model(key="PRE")

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

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

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

del#

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

See also: pop().

Examples

import neptune

model = neptune.init_model(with_id="CLS-PRE")

# Delete the field with the path "datasets/v0.4"
del model["datasets/v0.4"]

# You can also delete the whole namespace
del model["datasets"]

exists()#

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

Info

This method checks the local representation of the model. 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 object to synchronize the local representation with the server.
  • Call wait() on the model 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 object.

import neptune

model = neptune.init_model(with_id="CLS-PRE")

model["model/signature"].upload("model_signature.json")

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

model.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 = neptune.init_model(with_id="CLS-PRE")

# Fetch all the model metrics
model_metrics = model["metrics"].fetch()

fetch_model_versions_table()#

List the versions of the model, up to a maximum of 10 000.

Parameters

Name Type Default Description
columns list[str], optional None

Names of columns to include in the table, as a list of namespace or field names.

The Neptune ID ("sys/id") is included automatically.

If None, all the columns of the model versions table are included.

Returns

An interim Table object containing ModelVersion objects.

Use to_pandas() to convert it to a pandas DataFrame.

Example

>>> import neptune

# Initialize an existing model
>>> model = neptune.init_model(with_id="CLS-FOREST")
https://app.neptune.ai/workspace/project/m/CLS-FOREST
Remember to stop your model...

# Fetch list of all version of the model as pandas DataFrame
>>> full_model_versions_df = model.fetch_model_versions_table().to_pandas()
>>> print(full_model_versions_df)
                  sys/creation_time         sys/id  ... val/acc ...
0  2022-08-26 05:19:54.712000+00:00  CLS-FOREST-12  ...    0.98 ...
1  2022-08-26 05:19:17.197000+00:00  CLS-FOREST-11  ...    0.53 ...
2  2022-08-26 05:19:01.999000+00:00  CLS-FOREST-10  ...    0.19 ...
3  2022-08-26 05:18:42.380000+00:00  CLS-FOREST-9   ...    0.35 ...

# Fetch list of all model versions, including only the "train/acc"
# and "val/acc" fields as columns
>>> filtered_versions_table = model.fetch_model_versions_table(
...     columns=["train/acc", "val/acc"]
... )
>>> filtered_versions_df = filtered_versions_table.to_pandas()
>>> print(filtered_versions_df)
           sys/id  train/acc  val/acc
0   CLS-FOREST-12       0.94     0.98
1   CLS-FOREST-11       0.65     0.53
2   CLS-FOREST-10       0.73     0.19
3   CLS-FOREST-9        0.44     0.35
...

get_structure()#

Returns the metadata structure of a Model 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 model metadata structure.

Example

>>> import neptune
>>> model = neptune.init_model(with_id="CLS-PRE")
>>> model.get_structure()
{'model': {'signature': <neptune.attributes.atoms.file.File object at 0x000001C8EF87DD50>, 'size_limit': <neptune.attributes.atoms.float.Float object at 0x000001C8EF87DE40>, 'size_units': <neptune.attributes.atoms.string.String object at 0x000001C8EF87DEA0>}, ... }}

get_url()#

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

Returns

str with the URL of the model in Neptune.

Example

>>> import neptune
>>> model = neptune.init_model(with_id="CLS-PRE")
>>> model.get_url()
https://app.neptune.ai/ml-team/classification/m/CLS-PRE

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 = neptune.init_model(with_id="CLS-PRE")

# Delete a field along with its data
model.pop("datasets/v0.4")

You can invoke pop() directly on fields and namespaces.

# The following line
model.pop("datasets/v0.4")
# is equiavlent to this line
model["datasets/v0.4"].pop()
# and this line
model["datasets"].pop("v0.4")

# You can also batch-delete the whole namespace
model["datasets"].pop()

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 = neptune.init_model(with_id="CLS-PRE")
>>> model.print_structure()
'model':
    'signature': File
    'size_limit': Float
    'size_units': String
'sys':
    'creation_time': Datetime
    'id': String
    'modification_time': Datetime
    'monitoring_time': Integer
    'name': String
    'owner': String
    'ping_time': Datetime
    'running_time': Float
    'size': Float
    'state': RunState
    'tags': StringSet
    'trashed': Boolean
'validation':
    'dataset':
        'v0.1': Artifact

stop()#

Stops the connection to Neptune and synchronizes all data.

When using context managers, Neptune automatically calls stop() when exiting the model 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 = neptune.init_model(key="PRE")

[...] # Your code

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

Using with statement and context manager:

for model_identifier in models:
    with neptune.init_model(model=model_identifier) as model:
        [...] # Your code
        # stop() is automatically called
        # when code execution exits the with statement

sync()#

Synchronizes the local representation of the model 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.

Table.to_pandas()#

The Table object is an interim object containing the metadata of fetched objects. To access the data, you need to convert it to a pandas DataFrame by invoking to_pandas().

Returns

Tabular data in the pandas.DataFrame format.

Example

import neptune

model = neptune.init_model(with_id="CLS-PRE")

# Fetch list of all version of the model as pandas DataFrame
model_versions_df = model.fetch_model_versions_table().to_pandas()