def get_run(run_uuid):
"""Return the run with the specified run UUID from the current tracking server."""
_validate_run_id(run_uuid)
return _get_store().get_run(run_uuid)
def start_run(run_uuid=None,
experiment_id=None,
source_name=None,
source_version=None,
entry_point_name=None,
source_type=None,
run_name=None):
"""
Start a new MLflow run, setting it as the active run under which metrics and parameters
will be logged. The return value can be used as a context manager within a ``with`` block;
otherwise, you must call ``end_run()`` to terminate the current run.
If you pass a ``run_uuid`` or the ``MLFLOW_RUN_ID`` environment variable is set,
``start_run`` attempts to resume a run with the specified run ID and
other parameters are ignored. ``run_uuid`` takes precedence over ``MLFLOW_RUN_ID``.
:param run_uuid: If specified, get the run with the specified UUID and log parameters
and metrics under that run. The run's end time is unset and its status
is set to running, but the run's other attributes (``source_version``,
``source_type``, etc.) are not changed.
:param experiment_id: ID of the experiment under which to create the current run.
Used only when ``run_uuid`` is unspecified. If unspecified,
the run is created under the default experiment.
:param source_name: Name of the source file or URI of the project to be associated with the run.
If none provided defaults to the current file.
:param source_version: Optional Git commit hash to associate with the run.
:param entry_point_name: Optional name of the entry point for the current run.
:param source_type: Integer :py:class:`mlflow.entities.SourceType` describing the type
of the run ("local", "project", etc.). Defaults to
:py:class:`mlflow.entities.SourceType.LOCAL` ("local").
:param run_name: Name of new run. Used only when ``run_uuid`` is unspecified.
:return: :py:class:`mlflow.ActiveRun` object that acts as a context manager wrapping
the run's state.
"""
global _active_run
if _active_run:
raise Exception(
"Run with UUID %s is already active, unable to start nested "
"run" % _active_run.info.run_uuid)
existing_run_uuid = run_uuid or os.environ.get(_RUN_ID_ENV_VAR, None)
if existing_run_uuid:
_validate_run_id(existing_run_uuid)
active_run_obj = get_service().get_run(existing_run_uuid)
else:
exp_id_for_run = experiment_id or _get_experiment_id()
if is_in_databricks_notebook():
databricks_tags = {}
notebook_id = get_notebook_id()
notebook_path = get_notebook_path()
webapp_url = get_webapp_url()
if notebook_id is not None:
databricks_tags[MLFLOW_DATABRICKS_NOTEBOOK_ID] = notebook_id
if notebook_path is not None:
databricks_tags[
MLFLOW_DATABRICKS_NOTEBOOK_PATH] = notebook_path
if webapp_url is not None:
databricks_tags[MLFLOW_DATABRICKS_WEBAPP_URL] = webapp_url
active_run_obj = get_service().create_run(
experiment_id=exp_id_for_run,
run_name=run_name,
source_name=notebook_path,
source_version=source_version or _get_source_version(),
entry_point_name=entry_point_name,
source_type=SourceType.NOTEBOOK,
tags=databricks_tags)
else:
active_run_obj = get_service().create_run(
experiment_id=exp_id_for_run,
run_name=run_name,
source_name=source_name or _get_source_name(),
source_version=source_version or _get_source_version(),
entry_point_name=entry_point_name,
source_type=source_type or _get_source_type())
_active_run = ActiveRun(active_run_obj)
return _active_run
def start_run(run_id=None, experiment_id=None, run_name=None, nested=False):
"""
Start a new MLflow run, setting it as the active run under which metrics and parameters
will be logged. The return value can be used as a context manager within a ``with`` block;
otherwise, you must call ``end_run()`` to terminate the current run.
If you pass a ``run_id`` or the ``MLFLOW_RUN_ID`` environment variable is set,
``start_run`` attempts to resume a run with the specified run ID and
other parameters are ignored. ``run_id`` takes precedence over ``MLFLOW_RUN_ID``.
If resuming an existing run, the run status is set to ``RunStatus.RUNNING``.
MLflow sets a variety of default tags on the run, as defined in
:ref:`MLflow system tags <system_tags>`.
:param run_id: If specified, get the run with the specified UUID and log parameters
and metrics under that run. The run's end time is unset and its status
is set to running, but the run's other attributes (``source_version``,
``source_type``, etc.) are not changed.
:param experiment_id: ID of the experiment under which to create the current run (applicable
only when ``run_id`` is not specified). If ``experiment_id`` argument
is unspecified, will look for valid experiment in the following order:
activated using ``set_experiment``, ``MLFLOW_EXPERIMENT_NAME``
environment variable, ``MLFLOW_EXPERIMENT_ID`` environment variable,
or the default experiment as defined by the tracking server.
:param run_name: Name of new run (stored as a ``mlflow.runName`` tag).
Used only when ``run_id`` is unspecified.
:param nested: Controls whether run is nested in parent run. ``True`` creates a nest run.
:return: :py:class:`mlflow.ActiveRun` object that acts as a context manager wrapping
the run's state.
.. code-block:: python
:caption: Example
import mlflow
# Create nested runs
with mlflow.start_run(run_name='PARENT_RUN') as parent_run:
mlflow.log_param("parent", "yes")
with mlflow.start_run(run_name='CHILD_RUN', nested=True) as child_run:
mlflow.log_param("child", "yes")
print("parent run_id: {}".format(parent_run.info.run_id))
print("child run_id : {}".format(child_run.info.run_id))
print("--")
# Search all child runs with a parent id
query = "tags.mlflow.parentRunId = '{}'".format(parent_run.info.run_id)
results = mlflow.search_runs(filter_string=query)
print(results[["run_id", "params.child", "tags.mlflow.runName"]])
.. code-block:: text
:caption: Output
parent run_id: 5ec0e7ae18f54c2694ffb48c2fccf25c
child run_id : 78b3b0d264b44cd29e8dc389749bb4be
--
run_id params.child tags.mlflow.runName
0 78b3b0d264b44cd29e8dc389749bb4be yes CHILD_RUN
"""
global _active_run_stack
# back compat for int experiment_id
experiment_id = str(experiment_id) if isinstance(experiment_id,
int) else experiment_id
if len(_active_run_stack) > 0 and not nested:
raise Exception((
"Run with UUID {} is already active. To start a new run, first end the "
+ "current run with mlflow.end_run(). To start a nested " +
"run, call start_run with nested=True").format(
_active_run_stack[0].info.run_id))
if run_id:
existing_run_id = run_id
elif _RUN_ID_ENV_VAR in os.environ:
existing_run_id = os.environ[_RUN_ID_ENV_VAR]
del os.environ[_RUN_ID_ENV_VAR]
else:
existing_run_id = None
if existing_run_id:
_validate_run_id(existing_run_id)
active_run_obj = MlflowClient().get_run(existing_run_id)
# Check to see if experiment_id from environment matches experiment_id from set_experiment()
if (_active_experiment_id is not None and
_active_experiment_id != active_run_obj.info.experiment_id):
raise MlflowException(
"Cannot start run with ID {} because active run ID "
"does not match environment run ID. Make sure --experiment-name "
"or --experiment-id matches experiment set with "
"set_experiment(), or just use command-line "
"arguments".format(existing_run_id))
# Check to see if current run isn't deleted
if active_run_obj.info.lifecycle_stage == LifecycleStage.DELETED:
raise MlflowException(
"Cannot start run with ID {} because it is in the "
"deleted state.".format(existing_run_id))
# Use previous end_time because a value is required for update_run_info
end_time = active_run_obj.info.end_time
_get_store().update_run_info(existing_run_id,
run_status=RunStatus.RUNNING,
end_time=end_time)
active_run_obj = MlflowClient().get_run(existing_run_id)
else:
if len(_active_run_stack) > 0:
parent_run_id = _active_run_stack[-1].info.run_id
else:
parent_run_id = None
exp_id_for_run = experiment_id if experiment_id is not None else _get_experiment_id(
)
user_specified_tags = {}
if parent_run_id is not None:
user_specified_tags[MLFLOW_PARENT_RUN_ID] = parent_run_id
if run_name is not None:
user_specified_tags[MLFLOW_RUN_NAME] = run_name
tags = context_registry.resolve_tags(user_specified_tags)
active_run_obj = MlflowClient().create_run(
experiment_id=exp_id_for_run, tags=tags)
_active_run_stack.append(ActiveRun(active_run_obj))
return _active_run_stack[-1]
def get_run(self, run_id):
""":return: :py:class:`mlflow.entities.Run` associated with the run ID."""
_validate_run_id(run_id)
return self.store.get_run(run_id)
def start_run(run_uuid=None, experiment_id=None, source_name=None, source_version=None,
entry_point_name=None, source_type=None, run_name=None, nested=False):
"""
Start a new MLflow run, setting it as the active run under which metrics and parameters
will be logged. The return value can be used as a context manager within a ``with`` block;
otherwise, you must call ``end_run()`` to terminate the current run.
If you pass a ``run_uuid`` or the ``MLFLOW_RUN_ID`` environment variable is set,
``start_run`` attempts to resume a run with the specified run ID and
other parameters are ignored. ``run_uuid`` takes precedence over ``MLFLOW_RUN_ID``.
:param run_uuid: If specified, get the run with the specified UUID and log parameters
and metrics under that run. The run's end time is unset and its status
is set to running, but the run's other attributes (``source_version``,
``source_type``, etc.) are not changed.
:param experiment_id: ID of the experiment under which to create the current run (applicable
only when ``run_uuid`` is not specified). If ``experiment_id`` argument
is unspecified, will look for valid experiment in the following order:
activated using ``set_experiment``, ``MLFLOW_EXPERIMENT_ID`` env variable,
or the default experiment.
:param source_name: Name of the source file or URI of the project to be associated with the run.
If none provided defaults to the current file.
:param source_version: Optional Git commit hash to associate with the run.
:param entry_point_name: Optional name of the entry point for the current run.
:param source_type: Integer :py:class:`mlflow.entities.SourceType` describing the type
of the run ("local", "project", etc.). Defaults to
:py:class:`mlflow.entities.SourceType.LOCAL` ("local").
:param run_name: Name of new run. Used only when ``run_uuid`` is unspecified.
:param nested: Parameter which must be set to ``True`` to create nested runs.
:return: :py:class:`mlflow.ActiveRun` object that acts as a context manager wrapping
the run's state.
"""
global _active_run_stack
# back compat for int experiment_id
experiment_id = str(experiment_id) if isinstance(experiment_id, int) else experiment_id
if len(_active_run_stack) > 0 and not nested:
raise Exception(("Run with UUID {} is already active. To start a nested " +
"run call start_run with nested=True").format(
_active_run_stack[0].info.run_uuid))
existing_run_uuid = run_uuid or os.environ.get(_RUN_ID_ENV_VAR, None)
if existing_run_uuid:
_validate_run_id(existing_run_uuid)
active_run_obj = MlflowClient().get_run(existing_run_uuid)
if active_run_obj.info.lifecycle_stage == LifecycleStage.DELETED:
raise MlflowException("Cannot start run with ID {} because it is in the "
"deleted state.".format(existing_run_uuid))
else:
if len(_active_run_stack) > 0:
parent_run_id = _active_run_stack[-1].info.run_uuid
else:
parent_run_id = None
exp_id_for_run = experiment_id if experiment_id is not None else _get_experiment_id()
user_specified_tags = {}
if parent_run_id is not None:
user_specified_tags[MLFLOW_PARENT_RUN_ID] = parent_run_id
if source_name is not None:
user_specified_tags[MLFLOW_SOURCE_NAME] = source_name
if source_type is not None:
user_specified_tags[MLFLOW_SOURCE_TYPE] = SourceType.to_string(source_type)
if source_version is not None:
user_specified_tags[MLFLOW_GIT_COMMIT] = source_version
if entry_point_name is not None:
user_specified_tags[MLFLOW_PROJECT_ENTRY_POINT] = entry_point_name
tags = context.resolve_tags(user_specified_tags)
active_run_obj = MlflowClient().create_run(
experiment_id=exp_id_for_run,
run_name=run_name,
tags=tags
)
_active_run_stack.append(ActiveRun(active_run_obj))
return _active_run_stack[-1]
def _get_run_dir(self, experiment_id, run_uuid):
_validate_run_id(run_uuid)
if not self._has_experiment(experiment_id):
return None
return os.path.join(self._get_experiment_path(experiment_id, assert_exists=True),
run_uuid)
def _get_artifact_dir(self, experiment_id, run_uuid):
_validate_run_id(run_uuid)
artifacts_dir = posixpath.join(
self.get_experiment(experiment_id).artifact_location, run_uuid,
FileStore.ARTIFACTS_FOLDER_NAME)
return artifacts_dir
def set_tag(self, run_id, tag):
_validate_run_id(run_id)
_validate_tag_name(tag.key)
run_info = self._get_run_info(run_id)
check_run_is_active(run_info)
self._set_run_tag(run_info, tag)
def _get_param_path(self, experiment_id, run_uuid, param_name):
_validate_run_id(run_uuid)
_validate_param_name(param_name)
return os.path.join(self._get_run_dir(experiment_id, run_uuid),
FileStore.PARAMS_FOLDER_NAME, param_name)
def log_metric(self, run_id, metric):
_validate_run_id(run_id)
_validate_metric_name(metric.key)
run_info = self._get_run_info(run_id)
check_run_is_active(run_info)
self._log_run_metric(run_info, metric)
def log_param(self, run_id, param):
_validate_run_id(run_id)
_validate_param_name(param.key)
run_info = self._get_run_info(run_id)
check_run_is_active(run_info)
self._log_run_param(run_info, param)
def get_all_tags(self, run_uuid):
_validate_run_id(run_uuid)
run_info = self._get_run_info(run_uuid)
return self._get_all_tags(run_info)
def get_metric_history(self, run_id, metric_key):
_validate_run_id(run_id)
_validate_metric_name(metric_key)
run_info = self._get_run_info(run_id)
return self._get_metric_history(run_info, metric_key)
def _get_run_dir(self, experiment_id, run_uuid):
_validate_run_id(run_uuid)
return build_path(self._get_experiment_dir(experiment_id), run_uuid)
def start_run(run_id=None, experiment_id=None, run_name=None, nested=False):
"""
Start a new MLflow run, setting it as the active run under which metrics and parameters
will be logged. The return value can be used as a context manager within a ``with`` block;
otherwise, you must call ``end_run()`` to terminate the current run.
If you pass a ``run_id`` or the ``MLFLOW_RUN_ID`` environment variable is set,
``start_run`` attempts to resume a run with the specified run ID and
other parameters are ignored. ``run_id`` takes precedence over ``MLFLOW_RUN_ID``.
MLflow sets a variety of default tags on the run, as defined in
:ref:`MLflow system tags <system_tags>`.
:param run_id: If specified, get the run with the specified UUID and log parameters
and metrics under that run. The run's end time is unset and its status
is set to running, but the run's other attributes (``source_version``,
``source_type``, etc.) are not changed.
:param experiment_id: ID of the experiment under which to create the current run (applicable
only when ``run_id`` is not specified). If ``experiment_id`` argument
is unspecified, will look for valid experiment in the following order:
activated using ``set_experiment``, ``MLFLOW_EXPERIMENT_NAME``
environment variable, ``MLFLOW_EXPERIMENT_ID`` environment variable,
or the default experiment as defined by the tracking server.
:param run_name: Name of new run (stored as a ``mlflow.runName`` tag).
Used only when ``run_id`` is unspecified.
:param nested: Controls whether run is nested in parent run. ``True`` creates a nest run.
:return: :py:class:`mlflow.ActiveRun` object that acts as a context manager wrapping
the run's state.
"""
global _active_run_stack
# back compat for int experiment_id
experiment_id = str(experiment_id) if isinstance(experiment_id,
int) else experiment_id
if len(_active_run_stack) > 0 and not nested:
raise Exception(
("Run with UUID {} is already active. To start a nested " +
"run, call start_run with nested=True").format(
_active_run_stack[0].info.run_id))
if run_id:
existing_run_id = run_id
elif _RUN_ID_ENV_VAR in os.environ:
existing_run_id = os.environ[_RUN_ID_ENV_VAR]
del os.environ[_RUN_ID_ENV_VAR]
else:
existing_run_id = None
if existing_run_id:
_validate_run_id(existing_run_id)
active_run_obj = MlflowClient().get_run(existing_run_id)
if active_run_obj.info.lifecycle_stage == LifecycleStage.DELETED:
raise MlflowException(
"Cannot start run with ID {} because it is in the "
"deleted state.".format(existing_run_id))
else:
if len(_active_run_stack) > 0:
parent_run_id = _active_run_stack[-1].info.run_id
else:
parent_run_id = None
exp_id_for_run = experiment_id if experiment_id is not None else _get_experiment_id(
)
user_specified_tags = {}
if parent_run_id is not None:
user_specified_tags[MLFLOW_PARENT_RUN_ID] = parent_run_id
if run_name is not None:
user_specified_tags[MLFLOW_RUN_NAME] = run_name
tags = context_registry.resolve_tags(user_specified_tags)
active_run_obj = MlflowClient().create_run(
experiment_id=exp_id_for_run, tags=tags)
_active_run_stack.append(ActiveRun(active_run_obj))
return _active_run_stack[-1]
def _get_tag_path(self, experiment_id, run_uuid, tag_name):
_validate_run_id(run_uuid)
_validate_tag_name(tag_name)
return os.path.join(self._get_run_dir(experiment_id, run_uuid),
FileStore.TAGS_FOLDER_NAME, tag_name)
def start_run(run_uuid=None,
experiment_id=None,
source_name=None,
source_version=None,
entry_point_name=None,
source_type=None,
run_name=None,
nested=False):
"""
Start a new MLflow run, setting it as the active run under which metrics and parameters
will be logged. The return value can be used as a context manager within a ``with`` block;
otherwise, you must call ``end_run()`` to terminate the current run.
If you pass a ``run_uuid`` or the ``MLFLOW_RUN_ID`` environment variable is set,
``start_run`` attempts to resume a run with the specified run ID and
other parameters are ignored. ``run_uuid`` takes precedence over ``MLFLOW_RUN_ID``.
:param run_uuid: If specified, get the run with the specified UUID and log parameters
and metrics under that run. The run's end time is unset and its status
is set to running, but the run's other attributes (``source_version``,
``source_type``, etc.) are not changed.
:param experiment_id: ID of the experiment under which to create the current run (applicable
only when ``run_uuid`` is not specified). If ``experiment_id`` argument
is unspecified, will look for valid experiment in the following order:
activated using ``set_experiment``, ``MLFLOW_EXPERIMENT_ID`` env variable,
or the default experiment.
:param source_name: Name of the source file or URI of the project to be associated with the run.
If none provided defaults to the current file.
:param source_version: Optional Git commit hash to associate with the run.
:param entry_point_name: Optional name of the entry point for the current run.
:param source_type: Integer :py:class:`mlflow.entities.SourceType` describing the type
of the run ("local", "project", etc.). Defaults to
:py:class:`mlflow.entities.SourceType.LOCAL` ("local").
:param run_name: Name of new run. Used only when ``run_uuid`` is unspecified.
:param nested: Parameter which must be set to ``True`` to create nested runs.
:return: :py:class:`mlflow.ActiveRun` object that acts as a context manager wrapping
the run's state.
"""
global _active_run_stack
if len(_active_run_stack) > 0 and not nested:
raise Exception(
("Run with UUID {} is already active. To start a nested " +
"run call start_run with nested=True").format(
_active_run_stack[0].info.run_uuid))
existing_run_uuid = run_uuid or os.environ.get(_RUN_ID_ENV_VAR, None)
if existing_run_uuid:
_validate_run_id(existing_run_uuid)
active_run_obj = MlflowClient().get_run(existing_run_uuid)
if active_run_obj.info.lifecycle_stage == RunInfo.DELETED_LIFECYCLE:
raise MlflowException(
"Cannot start run with ID {} because it is in the "
"deleted state.".format(existing_run_uuid))
else:
if len(_active_run_stack) > 0:
parent_run_id = _active_run_stack[-1].info.run_uuid
else:
parent_run_id = None
exp_id_for_run = experiment_id if experiment_id is not None else _get_experiment_id(
)
if is_in_databricks_notebook():
databricks_tags = {}
notebook_id = get_notebook_id()
notebook_path = get_notebook_path()
webapp_url = get_webapp_url()
if notebook_id is not None:
databricks_tags[MLFLOW_DATABRICKS_NOTEBOOK_ID] = notebook_id
if notebook_path is not None:
databricks_tags[
MLFLOW_DATABRICKS_NOTEBOOK_PATH] = notebook_path
if webapp_url is not None:
databricks_tags[MLFLOW_DATABRICKS_WEBAPP_URL] = webapp_url
active_run_obj = MlflowClient().create_run(
experiment_id=exp_id_for_run,
run_name=run_name,
source_name=notebook_path,
source_version=source_version or _get_source_version(),
entry_point_name=entry_point_name,
source_type=SourceType.NOTEBOOK,
tags=databricks_tags,
parent_run_id=parent_run_id)
else:
active_run_obj = MlflowClient().create_run(
experiment_id=exp_id_for_run,
run_name=run_name,
source_name=source_name or _get_source_name(),
source_version=source_version or _get_source_version(),
entry_point_name=entry_point_name,
source_type=source_type or _get_source_type(),
parent_run_id=parent_run_id)
_active_run_stack.append(ActiveRun(active_run_obj))
return _active_run_stack[-1]
def _get_artifact_dir(self, experiment_id, run_uuid):
_validate_run_id(run_uuid)
return append_to_uri_path(
self.get_experiment(experiment_id).artifact_location, run_uuid,
FileStore.ARTIFACTS_FOLDER_NAME)
def _get_metric_path(self, experiment_id, run_uuid, metric_key):
_validate_run_id(run_uuid)
_validate_metric_name(metric_key)
return os.path.join(self._get_run_dir(experiment_id, run_uuid),
FileStore.METRICS_FOLDER_NAME,
metric_key)
def _get_run_dir(self, experiment_id, run_uuid):
_validate_run_id(run_uuid)
return build_path(
self._get_experiment_path(experiment_id, assert_exists=True),
run_uuid)
