mlflow.tracking

The mlflow.tracking module provides a Python CRUD interface to MLflow experiments and runs. This is a lower level API that directly translates to MLflow REST API calls. For a higher level API for managing an “active run”, use the mlflow module.

class mlflow.tracking.MlflowClient(tracking_uri=None)

Bases: object

Client of an MLflow Tracking Server that creates and manages experiments and runs.

create_experiment(name, artifact_location=None)

Create an experiment.

Parameters:
  • name – The experiment name. Must be unique.
  • artifact_location – The location to store run artifacts. If not provided, the server picks an appropriate default.
Returns:

Integer ID of the created experiment.

create_run(experiment_id, start_time=None, tags=None)

Create a mlflow.entities.Run object that can be associated with metrics, parameters, artifacts, etc. Unlike mlflow.projects.run(), creates objects but does not run code. Unlike mlflow.start_run(), does not change the “active run” used by mlflow.log_param().

Parameters:
  • experiment_id – The ID of then experiment to create a run in.
  • start_time – If not provided, use the current timestamp.
  • tags – A dictionary of key-value pairs that are converted into mlflow.entities.RunTag objects.
Returns:

mlflow.entities.Run that was created.

delete_experiment(experiment_id)

Delete an experiment from the backend store.

Parameters:experiment_id – The experiment ID returned from create_experiment.
delete_run(run_id)

Deletes a run with the given ID.

download_artifacts(run_id, path)

Download an artifact file or directory from a run to a local directory if applicable, and return a local path for it.

Parameters:
  • run_id – The run to download artifacts from.
  • path – Relative source path to the desired artifact.
Returns:

Local path of desired artifact.

get_experiment(experiment_id)
Parameters:experiment_id – The experiment ID returned from create_experiment.
Returns:mlflow.entities.Experiment
get_experiment_by_name(name)
Parameters:name – The experiment name.
Returns:mlflow.entities.Experiment
get_metric_history(run_id, key)

Return a list of metric objects corresponding to all values logged for a given metric.

Parameters:
  • run_id – Unique identifier for run
  • key – Metric name within the run
Returns:

A list of mlflow.entities.Metric entities if logged, else empty list

get_run(run_id)

Fetch the run from backend store. The resulting Run contains a collection of run metadata – RunInfo, as well as a collection of run parameters, tags, and metrics – RunData. In the case where multiple metrics with the same key are logged for the run, the RunData contains the most recently logged value at the largest step for each metric.

Parameters:run_id – Unique identifier for the run.
Returns:A single mlflow.entities.Run object, if the run exists. Otherwise, raises an exception.
list_artifacts(run_id, path=None)

List the artifacts for a run.

Parameters:
  • run_id – The run to list artifacts from.
  • path – The run’s relative artifact path to list from. By default it is set to None or the root artifact path.
Returns:

List of mlflow.entities.FileInfo

list_experiments(view_type=None)
Returns:List of mlflow.entities.Experiment
list_run_infos(experiment_id, run_view_type=1)
Returns:List of mlflow.entities.RunInfo
log_artifact(run_id, local_path, artifact_path=None)

Write a local file to the remote artifact_uri.

Parameters:
  • local_path – Path to the file to write.
  • artifact_path – If provided, the directory in artifact_uri to write to.
log_artifacts(run_id, local_dir, artifact_path=None)

Write a directory of files to the remote artifact_uri.

Parameters:
  • local_dir – Path to the directory of files to write.
  • artifact_path – If provided, the directory in artifact_uri to write to.
log_batch(run_id, metrics, params, tags)

Log multiple metrics, params, and/or tags.

Parameters:
  • metrics – List of Metric(key, value, timestamp) instances.
  • params – List of Param(key, value) instances.
  • tags – List of RunTag(key, value) instances.

Raises an MlflowException if any errors occur. :returns: None

log_metric(run_id, key, value, timestamp=None, step=None)

Log a metric against the run ID. The timestamp defaults to the current timestamp. The step defaults to 0.

log_param(run_id, key, value)

Log a parameter against the run ID. Value is converted to a string.

rename_experiment(experiment_id, new_name)

Update an experiment’s name. The new name must be unique.

Parameters:experiment_id – The experiment ID returned from create_experiment.
restore_experiment(experiment_id)

Restore a deleted experiment unless permanently deleted.

Parameters:experiment_id – The experiment ID returned from create_experiment.
restore_run(run_id)

Restores a deleted run with the given ID.

search_runs(experiment_ids, filter_string='', run_view_type=1, max_results=1000)

Search experiments that fit the search criteria.

Parameters:
  • experiment_ids – List of experiment IDs, or a single int or string id.
  • filter_string – Filter query string, defaults to searching all runs.
  • run_view_type – one of enum values ACTIVE_ONLY, DELETED_ONLY, or ALL runs defined in mlflow.entities.ViewType.
  • max_results – Maximum number of runs desired.
Returns:

A list of mlflow.entities.Run objects that satisfy the search expressions

set_tag(run_id, key, value)

Set a tag on the run ID. Value is converted to a string.

set_terminated(run_id, status=None, end_time=None)

Set a run’s status to terminated.

Parameters:
  • status – A string value of mlflow.entities.RunStatus. Defaults to “FINISHED”.
  • end_time – If not provided, defaults to the current time.
mlflow.tracking.get_tracking_uri()

Get the current tracking URI. This may not correspond to the tracking URI of the currently active run, since the tracking URI can be updated via set_tracking_uri.

Returns:The tracking URI.
mlflow.tracking.set_tracking_uri(uri)

Set the tracking server URI. This does not affect the currently active run (if one exists), but takes effect for successive runs.

Parameters:uri
  • An empty string, or a local file path, prefixed with file:/. Data is stored locally at the provided file (or ./mlruns if empty).
  • An HTTP URI like https://my-tracking-server:5000.
  • A Databricks workspace, provided as the string “databricks” or, to use a Databricks CLI profile, “databricks://<profileName>”.