PM feedback + peer review

nibaccam · nibaccam · commit fda6ef112e66 · 2021-12-14T11:08:52.000-08:00
diff --git a/articles/machine-learning/how-to-use-mlflow-cli-runs.md b/articles/machine-learning/how-to-use-mlflow-cli-runs.md
@@ -8,48 +8,49 @@ ms.author: osomorog
 ms.service: machine-learning
 ms.subservice: mlops
 ms.reviewer: nibaccam
-ms.date: 11/23/2021
+ms.date: 12/16/2021
 ms.topic: how-to
 ms.custom: devx-track-python
 ---
 
-# Track ML experiments and models with MLflow and Azure Machine Learning CLI (v2) (preview)
+# Track ML experiments and models with MLflow or Azure Machine Learning CLI (v2) (preview)
 
 [!INCLUDE [preview disclaimer](../../includes/machine-learning-preview-generic-disclaimer.md)]
 
-In this article, learn how to enable MLflow's tracking URI and logging API, collectively known as [MLflow Tracking](https://mlflow.org/docs/latest/quickstart.html#using-the-tracking-api), to connect Azure Machine Learning as the backend of your MLflow experiments with the [Azure Machine Learning CLI (v2)](how-to-train-cli.md). You also learn how to use [MLflow's Model Registry](https://mlflow.org/docs/latest/model-registry.html) capabilities with Azure Machine Learning.
+In this article, learn how to enable MLflow's tracking URI and logging API, collectively known as [MLflow Tracking](https://mlflow.org/docs/latest/quickstart.html#using-the-tracking-api), to connect Azure Machine Learning as the backend of your MLflow experiments. You can accomplish this connection with either the MLflow Python API or the [Azure Machine Learning CLI (v2)](how-to-train-cli.md). You also learn how to use [MLflow's Model Registry](https://mlflow.org/docs/latest/model-registry.html) capabilities with Azure Machine Learning.
 
 [MLflow](https://www.mlflow.org) is an open-source library for managing the lifecycle of your machine learning experiments. MLFlow Tracking is a component of MLflow that logs and tracks your training run metrics and model artifacts, no matter your experiment's environment--locally on your computer, on a remote compute target, a virtual machine, or an [Azure Databricks cluster](how-to-use-mlflow-azure-databricks.md).
 
 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.
 
+ 
 > [!TIP]
 > The information in this document is primarily for data scientists and developers who want to monitor the model training process. If you are an administrator interested in monitoring resource usage and events from Azure Machine Learning, such as quotas, completed training runs, or completed model deployments, see [Monitoring Azure Machine Learning](monitor-azure-machine-learning.md).
 
-> [!NOTE]
+> [!NOTE] 
 > You can use the [MLflow Skinny client](https://github.com/mlflow/mlflow/blob/master/README_SKINNY.rst) which is a lightweight MLflow package without SQL storage, server, UI, or data science dependencies. This is recommended for users who primarily need the tracking and logging capabilities without importing the full suite of MLflow features including deployments.
 
 ## Prerequisites
 
-* Install the `azureml-mlflow` package.
-    * This package automatically brings in `azureml-core` of the [The Azure Machine Learning Python SDK](/python/api/overview/azure/ml/install), which provides the connectivity for MLflow to access your workspace.
-
 * [Create an Azure Machine Learning Workspace](how-to-manage-workspace.md).
     * See which [access permissions you need to perform your MLflow operations with your workspace](how-to-assign-roles.md#mlflow-operations).
 
-* Install and [set up CLI (v2)](how-to-configure-cli.md#prerequisites).
+* Install and [set up CLI (v2)](how-to-configure-cli.md#prerequisites) and make sure you install the ml extension
 
 ## Track runs from your local machine
 
 MLflow Tracking with Azure Machine Learning lets you store the logged metrics and artifacts runs that were executed on your local machine into your Azure Machine Learning workspace.
 
-### Setting up tracking environment to track local run
+### Set up tracking environment
 
-First, you need to point your local machine to the Azure Machine Learning MLFlow Tracking URI. 
+To track a local run, you need to point your local machine to the Azure Machine Learning MLFlow Tracking URI. 
 
-This can be done in a couple ways. You can import the `mlflow` and [`subprocess`](https://docs.python.org/3/library/subprocess.html) classes to access MLflow's tracking URI.
+>[!NOTE]
+>The tracking URI is valid up to an hour or less. If you restart your script after some idle time, use the get_mlflow_tracking_uri API to get a new URI.
 
-The following code, uses the subprocess class in Python to run the Azure Machine Learning CLI (v2) command to retrieve the unique MLFLow tracking URI associated with your workspace, and [`set_tracking_uri()`](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.set_tracking_uri) points the MLflow tracking URI to that URI.
+# [MLflow](#tab/mlflow)
+
+The following code uses `mlflow` and the [`subprocess`](https://docs.python.org/3/library/subprocess.html) classes in Python to run the Azure Machine Learning CLI (v2) command to retrieve the unique MLFLow tracking URI associated with your workspace. Then the method [`set_tracking_uri()`](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.set_tracking_uri) points the MLflow tracking URI to that URI.
 
 ```Python
 import mlflow
@@ -60,41 +61,49 @@ MLFLOW_TRACKING_URI = subprocess.run(["az", "ml", "workspace", "show", "--query"
 MLFLOW_TRACKING_URI = str(MLFLOW_TRACKING_URI.stdout).strip()
 ```
 
+# [Azure CLI](#tab/azure-cli)
+
 Another option is to set one of the MLflow environment variables [MLFLOW_TRACKING_URI](https://mlflow.org/docs/latest/tracking.html#logging-to-a-tracking-server) directly in your terminal.
 
-```Bash
+```Azure CLI
 # Configure MLflow to communicate with a Azure Machine Learning-hosted tracking server
+
 export MLFLOW_TRACKING_URI=$(az ml workspace show --query mlflow_tracking_uri | sed 's/"//g') 
 ```
+---
 
->[!NOTE]
->The tracking URI is valid up to an hour or less. If you restart your script after some idle time, use the get_mlflow_tracking_uri API to get a new URI.
 
-Next, you set the experiment name.
+### Set experiment name
 
-All MLflow runs are logged to the active experiment, which can be set using any of the following ways:
+All MLflow runs are logged to the active experiment, which can be set using MLflow or the Azure CLI. 
 
-* You can use the [mlflow.set_experiment()](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.set_experiment) command.
+# [MLflow](#tab/mlflow)
+
+With MLflow you can use the [`mlflow.set_experiment()`](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.set_experiment) command.
     
     ```Python
     experiment_name = 'experiment_with_mlflow'
     mlflow.set_experiment(experiment_name)
     ```
 
-* You can use the `experiment_id` parameter in the [mlflow.start_run()](https://www.mlflow.org/docs/latest/python_api/mlflow.html#mlflow.start_run) command.
+ Another option is to use the `experiment_id` parameter in the [mlflow.start_run()](https://www.mlflow.org/docs/latest/python_api/mlflow.html#mlflow.start_run) command.
 
     ```Python
     experiment_name = 'experiment_with_mlflow'
     with mlflow.start_run(experiment_id=experiment_name) as mlflow_run:
         mlflow.log_param("hello_param", "world")
     ```
+# [Azure CLI](#tab/azure-cli)
 
-* Another option is to set one of the MLflow environment variables [MLFLOW_EXPERIMENT_NAME or MLFLOW_EXPERIMENT_ID](https://mlflow.org/docs/latest/cli.html#cmdoption-mlflow-run-arg-uri).
+With the Azure CLI, set one of the MLflow environment variables [MLFLOW_EXPERIMENT_NAME or MLFLOW_EXPERIMENT_ID](https://mlflow.org/docs/latest/cli.html#cmdoption-mlflow-run-arg-uri) with the experiment name.
 
-    ```Bash
+    ```Azure CLI
     # Configure MLflow to communicate with a Azure Machine Learning-hosted tracking server
     export MLFLOW_EXPERIMENT_NAME="experiment_with_mlflow"
     ```
+---
+
+### Start training run
 
 After you set the MLflow experiment name, you can start your training run with `start_run()`. Then use `log_metric()` to activate the MLflow logging API and begin logging your training run metrics.
 
@@ -113,7 +122,7 @@ with mlflow.start_run() as mlflow_run:
 
 Remote runs (jobs) let you train your models on more powerful computes, such as GPU enabled virtual machines, or Machine Learning Compute clusters. See [Use compute targets for model training](how-to-set-up-training-targets.md) to learn about different compute options.
 
-MLflow Tracking with Azure Machine Learning lets you store the logged metrics and artifacts from your remote runs into your Azure Machine Learning workspace. Any run with MLflow Tracking code in it will have metrics logged automatically to the workspace. 
+MLflow Tracking with Azure Machine Learning lets you store the logged metrics and artifacts from your remote runs into your Azure Machine Learning workspace. Any run with MLflow Tracking code in it logs metrics automatically to the workspace. 
 
 First, you should create a `src` subdirectory and create a file with your training code in a `train.py` file in the `src` subdirectory. All your training code will go into the `src` subdirectory, including `train.py`.
 
@@ -142,7 +151,7 @@ if __name__ == "__main__":
     main()
 ```
 
-Use the [Azure Machine Learning CLI (v2)](how-to-train-cli.md) to submit a run. When using the Azure Machine Learning CLI (v2), the MLflow tracking URI and experiment name is set automatically and directs the logging from MLflow to your Workspace. Learn more about [logging Azure Machine Learning CLI (v2) experiments with MLflow](how-to-train-cli.md#model-tracking-with-mlflow) 
+Use the [Azure Machine Learning CLI (v2)](how-to-train-cli.md) to submit a run. When using the Azure Machine Learning CLI (v2), the MLflow tracking URI and experiment name are set automatically and directs the logging from MLflow to your workspace. Learn more about [logging Azure Machine Learning CLI (v2) experiments with MLflow](how-to-train-cli.md#model-tracking-with-mlflow) 
 
 Create a YAML file with your job definition in a `job.yml` file. This file should be created outside the `src` directory. Copy this code into the file:
 
@@ -162,7 +171,7 @@ compute: azureml:MyCluster
 
 Open your terminal and use the following to submit the job.
 
-```Bash
+```Azure CLI
 az ml job create -f job.yml --web
 ```
 
@@ -172,7 +181,7 @@ The metrics and artifacts from MLflow logging are tracked in your workspace. To
 
 Retrieve run metric using MLFlow [get_run()](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.get_run).
 
-```python
+```Python
 from mlflow.tracking import MlflowClient
 # Use MlFlow to retrieve the run that was just completed
 client = MlflowClient()
@@ -189,21 +198,22 @@ print(metrics,tags,params)
 ### Retrieve artifacts with MLFLow
 
 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
+
+```Python
 client.list_artifacts(run_id)
 ```
 
 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)
 
-```python
+```Python
 client.download_artifacts(run_id, "helloworld.txt", ".")
 ```
 
 ### Compare and query
 
 To compare and query all MLFlow runs in your Azure Machine Learning Workspace
 
-```python
+```Python
 from mlflow.entities import ViewType
 
 all_experiments = [exp.experiment_id for exp in MlflowClient().list_experiments()]
@@ -223,7 +233,7 @@ To register and view a model from a run, use the following steps:
 
 1. Once a run is complete, call the [`register_model()`](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.register_model) method.
 
-    ```python
+    ```Python
     # the model folder produced from a run is registered. This includes the MLmodel file, model.pkl and the conda.yaml.
     model_path = "model"
     model_uri = 'runs:/{}/{}'.format(run_id, model_path) 
@@ -247,8 +257,7 @@ To register and view a model from a run, use the following steps:
 
 ## Example notebooks
 
-A community-driven repository of examples using mlflow can be found at https://github.com/Azure/azureml-examples.
-* [Using MLFlow and CLI (v2)](https://github.com/Azure/azureml-examples/blob/main/cli/jobs/basics/hello-mlflow.yml)
+[Use MLFlow and CLI (v2)](https://github.com/Azure/azureml-examples/blob/main/cli/jobs/basics/hello-mlflow.yml)
 
 ## Next steps
 
