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. Unlikemlflow.projects.run()
, creates objects but does not run code. Unlikemlflow.start_run()
, does not change the “active run” used bymlflow.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
.
-
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, theRunData
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.
-
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
.
-
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_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.
- status – A string value of
-
-
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>”.
- An empty string, or a local file path, prefixed with