Merge pull request #228013 from santiagxf/santiagxf/mlflow-patch

Update how-to-use-mlflow-cli-runs.md

Author: v-dirichards

articles/machine-learning/how-to-use-mlflow-cli-runs.md

@@ -16,19 +16,44 @@ ms.devlang: azurecli
 
 # Track ML experiments and models with MLflow
 
-> [!div class="op_single_selector" title1="Select the version of Azure Machine Learning developer platform you are using:"]
+> [!div class="op_single_selector" title1="Select the version of Azure Machine Learning developer platform you're using:"]
 > * [v1](./v1/how-to-use-mlflow.md)
 > * [v2 (current version)](how-to-use-mlflow-cli-runs.md)
 
-Azure Machine Learning workspaces are MLflow-compatible, which means you can use MLflow to track runs, metrics, parameters, and artifacts with your Azure Machine Learning workspaces. By using MLflow for tracking, you don't need to change your training routines to work with Azure Machine Learning or inject any cloud-specific syntax, which is one of the main advantages of the approach. 
+__Tracking__ refers to process of saving all experiment's related information that you may find relevant for every experiment you run. Such metadata varies based on your project, but it may include:
 
-See [MLflow and Azure Machine Learning](concept-mlflow.md) for all supported MLflow and Azure Machine Learning functionality including MLflow Project support (preview) and model deployment.
+> [!div class="checklist"]
+> - Code
+> - Environment details (OS version, Python packages)
+> - Input data
+> - Parameter configurations
+> - Models
+> - Evaluation metrics 
+> - Evaluation visualizations (confusion matrix, importance plots)  
+> - Evaluation results (including some evaluation predictions)
+
+Some of these elements are automatically tracked by Azure Machine Learning when working with jobs (including code, environment, and input and output data). However, others like models, parameters, and metrics, need to be instrumented by the model builder as it's specific to the particular scenario. 
 
-In this article, you will learn how to use MLflow for tracking your experiments and runs in Azure Machine Learning workspaces.
+In this article, you'll learn how to use MLflow for tracking your experiments and runs in Azure Machine Learning workspaces.
 
 > [!NOTE] 
 > If you want to track experiments running on Azure Databricks or Azure Synapse Analytics, see the dedicated articles [Track Azure Databricks ML experiments with MLflow and Azure Machine Learning](how-to-use-mlflow-azure-databricks.md) or [Track Azure Synapse Analytics ML experiments with MLflow and Azure Machine Learning](how-to-use-mlflow-azure-synapse.md).
 
+## Benefits of tracking experiments
+
+We highly encourage machine learning practitioners to instrument their experimentation by tracking them, regardless if they're training with jobs in Azure Machine Learning or interactively in notebooks. Benefits include:
+
+- All of your ML experiments are organized in a single place, allowing you to search and filter experiments to find the information and drill down to see what exactly it was that you tried before.
+- Compare experiments, analyze results, and debug model training with little extra work.
+- Reproduce or re-run experiments to validate results.
+- Improve collaboration by seeing what everyone is doing, sharing experiment results, and access experiment data programmatically.
+
+### Why MLflow
+
+Azure Machine Learning workspaces are MLflow-compatible, which means you can use MLflow to track runs, metrics, parameters, and artifacts with your Azure Machine Learning workspaces. By using MLflow for tracking, you don't need to change your training routines to work with Azure Machine Learning or inject any cloud-specific syntax, which is one of the main advantages of the approach. 
+
+See [MLflow and Azure Machine Learning](concept-mlflow.md) for all supported MLflow and Azure Machine Learning functionality including MLflow Project support (preview) and model deployment.
+
 ## Prerequisites
 
 [!INCLUDE [mlflow-prereqs](../../includes/machine-learning-mlflow-prereqs.md)]
@@ -56,13 +81,13 @@ When submitting jobs using Azure Machine Learning CLI or SDK, you can set the ex
 
 ## Configure the run
 
-Azure Machine Learning any training job in what MLflow calls a run. Use runs to capture all the processing that your job performs.
+Azure Machine Learning tracks any training job in what MLflow calls a run. Use runs to capture all the processing that your job performs.
 
 # [Working interactively](#tab/interactive)
 
-When working interactively, MLflow starts tracking your training routine as soon as you try to log information that requires an active run. For instance, when you log a metric, log a parameter, or when you start a training cycle when Mlflow's autologging functionality is enabled. However, it is usually helpful to start the run explicitly, specially if you want to capture the total time of your experiment in the field __Duration__. To start the run explicitly, use `mlflow.start_run()`.
+When working interactively, MLflow starts tracking your training routine as soon as you try to log information that requires an active run. For instance, when you log a metric, log a parameter, or when you start a training cycle when Mlflow's autologging functionality is enabled. However, it's usually helpful to start the run explicitly, specially if you want to capture the total time of your experiment in the field __Duration__. To start the run explicitly, use `mlflow.start_run()`.
 
-Regardless if you started the run manually or not, you will eventually need to stop the run to inform MLflow that your experiment run has finished and marks its status as __Completed__. To do that, all `mlflow.end_run()`. We strongly recommend starting runs manually so you don't forget to end them when working on notebooks.
+Regardless if you started the run manually or not, you'll eventually need to stop the run to inform MLflow that your experiment run has finished and marks its status as __Completed__. To do that, all `mlflow.end_run()`. We strongly recommend starting runs manually so you don't forget to end them when working on notebooks.
 
 ```python
 mlflow.start_run()
@@ -72,7 +97,7 @@ mlflow.start_run()
 mlflow.end_run()
 ```
 
-To help you avoid forgetting to end the run, it is usually helpful to use the context manager paradigm:
+To help you avoid forgetting to end the run, it's usually helpful to use the context manager paradigm:
 
 ```python
 with mlflow.start_run() as run:
@@ -96,23 +121,23 @@ When working with jobs, you typically place all your training logic inside of a
 
 :::code language="python" source="~/azureml-examples-main/cli/jobs/basics/src/hello-mlflow.py" highlight="9-10,12":::
 
-The previous code example doesn't uses `mlflow.start_run()` but if used you can expect MLflow to reuse the current active run so there is no need to remove those lines if migrating to Azure Machine Learning.
+The previous code example doesn't uses `mlflow.start_run()` but if used you can expect MLflow to reuse the current active run so there's no need to remove those lines if migrating to Azure Machine Learning.
 
 ### Adding tracking to your routine
 
 Use MLflow SDK to track any metric, parameter, artifacts, or models. For detailed examples about how to log each, see [Log metrics, parameters and files with MLflow](how-to-log-view-metrics.md).
 
 ### Ensure your job's environment has MLflow installed
 
-All Azure Machine Learning environments already have MLflow installed for you, so no action is required if you are using a curated environment. If you want to use a custom environment:
+All Azure Machine Learning environments already have MLflow installed for you, so no action is required if you're using a curated environment. If you want to use a custom environment:
 
 1. Create a `conda.yml` file with the dependencies you need:
 
     :::code language="yaml" source="~/azureml-examples-main//sdk/python/using-mlflow/deploy/environment/conda.yml" highlight="7-8" range="1-12":::
 
-1. Reference the environment in the job you are using.
+1. Reference the environment in the job you're using.
 
-### Configuring the job's name
+### Configuring job's name
 
 Use the parameter `display_name` of Azure Machine Learning jobs to configure the name of the run. The following example shows how:
 
@@ -138,11 +163,11 @@ Use the parameter `display_name` of Azure Machine Learning jobs to configure the
     )
     ```
 
-2. Ensure you are not using `mlflow.start_run(run_name="")` inside of your training routine.
+2. Ensure you're not using `mlflow.start_run(run_name="")` inside of your training routine.
 
 ### Submitting the job
 
-1. First, let's connect to Azure Machine Learning workspace where we are going to work on.
+1. First, let's connect to Azure Machine Learning workspace where we're going to work on.
 
     # [Azure CLI](#tab/cli)
 
@@ -211,40 +236,36 @@ The metrics and artifacts from MLflow logging are tracked in your workspace. To
 
 :::image type="content" source="media/how-to-log-view-metrics/metrics.png" alt-text="Screenshot of the metrics view.":::
 
-Select the logged metrics to render charts on the right side. You can customize the charts by applying smoothing, changing the color, or plotting multiple metrics on a single graph. You can also resize and rearrange the layout as you wish. Once you have created your desired view, you can save it for future use and share it with your teammates using a direct link.
+Select the logged metrics to render charts on the right side. You can customize the charts by applying smoothing, changing the color, or plotting multiple metrics on a single graph. You can also resize and rearrange the layout as you wish. Once you've created your desired view, you can save it for future use and share it with your teammates using a direct link.
 
-Retrieve run metric using MLflow SDK, use [mlflow.get_run()](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.get_run).
+You can also access or __query metrics, parameters and artifacts programatically__ using the MLflow SDK. Use [mlflow.get_run()](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.get_run) as explained bellow:
 
-```Python
-from mlflow.tracking import MlflowClient
+```python
+import mlflow
 
-client = MlflowClient()
-run = MlflowClient().get_run("<RUN_ID>")
+run = mlflow.get_run("<RUN_ID>")
 
 metrics = run.data.metrics
-tags = run.data.tags
 params = run.data.params
+tags = run.data.tags
 
-print(metrics,tags,params)
+print(metrics, params, tags)
 ```
 
-To view the artifacts of a run, you can use [MlFlowClient.list_artifacts()](https://mlflow.org/docs/latest/python_api/mlflow.tracking.html#mlflow.tracking.MlflowClient.list_artifacts)
-
-```Python
-client.list_artifacts(run_id)
-```
+> [!TIP]
+> For metrics, the previous example will only return the last value of a given metric. If you want to retrieve all the values of a given metric, use `mlflow.get_metric_history` method as explained at [Getting params and metrics from a run](how-to-track-experiments-mlflow.md#getting-params-and-metrics-from-a-run).
 
-To download an artifact to the current directory, you can use [MLFlowClient.download_artifacts()](https://www.mlflow.org/docs/latest/python_api/mlflow.tracking.html#mlflow.tracking.MlflowClient.download_artifacts)
+To download artifacts you've logged, like files and models, you can use [mlflow.artifacts.download_artifacts()](https://www.mlflow.org/docs/latest/python_api/mlflow.artifacts.html#mlflow.artifacts.download_artifacts)
 
-```Python
-client.download_artifacts(run_id, "helloworld.txt", ".")
+```python
+mlflow.artifacts.download_artifacts(run_id="<RUN_ID>", artifact_path="helloworld.txt")
 ```
 
-For more details about how to retrieve information from experiments and runs in Azure Machine Learning using MLflow view [Query & compare experiments and runs with MLflow](how-to-track-experiments-mlflow.md).
+For more details about how to __retrieve or compare__ information from experiments and runs in Azure Machine Learning using MLflow view [Query & compare experiments and runs with MLflow](how-to-track-experiments-mlflow.md)
 
 ## Example notebooks
 
-If you are looking for examples about how to use MLflow in Jupyter notebooks, please see our example's repository [Using MLflow (Jupyter Notebooks)](https://github.com/Azure/azureml-examples/tree/main/sdk/python/using-mlflow).
+If you're looking for examples about how to use MLflow in Jupyter notebooks, please see our example's repository [Using MLflow (Jupyter Notebooks)](https://github.com/Azure/azureml-examples/tree/main/sdk/python/using-mlflow).
 
 ## Limitations