Merge pull request #187580 from AbeOmor/patch-45

Update the MLFLow article to have better details

Author: jborsecnik

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

@@ -50,7 +50,11 @@ The following diagram illustrates that with MLflow Tracking, you track an experi
 
 ## Track local runs
 
-MLflow Tracking with Azure Machine Learning lets you store the logged metrics and artifacts from your local runs into your Azure Machine Learning workspace.
+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. 
+
+### Set up tracking environment
+
+To track a local run, you need to point your local machine to the Azure Machine Learning MLflow Tracking URI. 
 
 Import the `mlflow` and [`Workspace`](/python/api/azureml-core/azureml.core.workspace%28class%29) classes to access MLflow's tracking URI and configure your workspace.
 
@@ -65,14 +69,30 @@ ws = Workspace.from_config()
 mlflow.set_tracking_uri(ws.get_mlflow_tracking_uri())
 ```
 
-Set the MLflow experiment name with `set_experiment()` and start your training run with `start_run()`. Then use `log_metric()` to activate the MLflow logging API and begin logging your training run metrics.
+### Set experiment name
+
+All MLflow runs are logged to the active experiment, which can be set with the MLflow SDK or Azure CLI. 
+
+Set the MLflow experiment name with [`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)
+```
+
+### Start training run
 
-with mlflow.start_run():
-    mlflow.log_metric('alpha', 0.03)
+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.
+
+```Python
+import os
+from random import random
+
+with mlflow.start_run() as mlflow_run:
+    mlflow.log_param("hello_param", "world")
+    mlflow.log_metric("hello_metric", random())
+    os.system(f"echo 'hello world' > helloworld.txt")
+    mlflow.log_artifact("helloworld.txt")
 ```
 
 ## Track remote runs
@@ -81,45 +101,149 @@ Remote runs let you train your models on more powerful computes, such as GPU ena
 
 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. 
 
-The following example conda environment includes `mlflow` and `azureml-mlflow` as pip packages. 
+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`.
+
+The training code is taken from this [MLflow example](https://github.com/Azure/azureml-examples/blob/main/cli/jobs/basics/src/hello-mlflow.py) in the Azure Machine Learning example repo. 
+
+Copy this code into the file:
+
+```Python
+# imports
+import os
+import mlflow
+
+from random import random
+
+# define functions
+def main():
+    mlflow.log_param("hello_param", "world")
+    mlflow.log_metric("hello_metric", random())
+    os.system(f"echo 'hello world' > helloworld.txt")
+    mlflow.log_artifact("helloworld.txt")
 
 
-```yaml
-name: sklearn-example
-dependencies:
-  - python=3.6.2
-  - scikit-learn
-  - matplotlib
-  - numpy
-  - pip:
-    - azureml-mlflow
-    - mlflow
-    - numpy
+# run functions
+if __name__ == "__main__":
+    # run main function
+    main()
 ```
 
-In your script, configure your compute and training run environment with the [`Environment`](/python/api/azureml-core/azureml.core.environment.environment) class. Then, construct  [`ScriptRunConfig`](/python/api/azureml-core/azureml.core.script_run_config.scriptrunconfig) with your remote compute as the compute target.
+Load training script to submit an experiement.
 
 ```Python
-import mlflow
+script_dir = "src"
+training_script = 'train.py'
+with open("{}/{}".format(script_dir,training_script), 'r') as f:
+    print(f.read())
+```
+
+In your script, configure your compute and training run environment with the [`Environment`](/python/api/azureml-core/azureml.core.environment.environment) class. 
+
+```Python
+from azureml.core import Environment
+from azureml.core.conda_dependencies import CondaDependencies
+
+env = Environment(name="mlflow-env")
 
-with mlflow.start_run():
-    mlflow.log_metric('example', 1.23)
+# Specify conda dependencies with scikit-learn and temporary pointers to mlflow extensions
+cd = CondaDependencies.create(
+    conda_packages=["scikit-learn", "matplotlib"],
+    pip_packages=["azureml-mlflow", "pandas", "numpy"]
+    )
+
+env.python.conda_dependencies = cd
+```
+
+Then, construct  [`ScriptRunConfig`](/python/api/azureml-core/azureml.core.script_run_config.scriptrunconfig) with your remote compute as the compute target.
+
+```Python
+from azureml.core import ScriptRunConfig
+
+src = ScriptRunConfig(source_directory="src",
+                      script=training_script,
+                      compute_target="<COMPUTE_NAME>",
+                      environment=env)
 ```
 
 With this compute and training run configuration, use the `Experiment.submit()` method to submit a run. This method automatically sets the MLflow tracking URI and directs the logging from MLflow to your Workspace.
 
 ```Python
+from azureml.core import Experiment
+from azureml.core import Workspace
+ws = Workspace.from_config()
+
+experiment_name = "experiment_with_mlflow"
+exp = Experiment(workspace=ws, name=experiment_name)
+
 run = exp.submit(src)
 ```
 
 ## View metrics and artifacts in your workspace
 
-The metrics and artifacts from MLflow logging are kept in your workspace. To view them anytime, navigate to your workspace and find the experiment by name in your workspace in [Azure Machine Learning studio](https://ml.azure.com).  Or run the below code. 
+The metrics and artifacts from MLflow logging are tracked in your workspace. To view them anytime, navigate to your workspace and find the experiment by name in your workspace in [Azure Machine Learning studio](https://ml.azure.com).  Or run the below code. 
+
+Retrieve run metric using MLflow [get_run()](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.get_run).
+
+```Python
+from mlflow.entities import ViewType
+from mlflow.tracking import MlflowClient
+
+# Retrieve run ID for the last run experiement
+current_experiment=mlflow.get_experiment_by_name(experiment_name)
+runs = mlflow.search_runs(experiment_ids=current_experiment.experiment_id, run_view_type=ViewType.ALL)
+run_id = runs.tail(1)["run_id"].tolist()[0]
+
+# Use MlFlow to retrieve the run that was just completed
+client = MlflowClient()
+finished_mlflow_run = MlflowClient().get_run(run_id)
 
-```python
-run.get_metrics()
+metrics = finished_mlflow_run.data.metrics
+tags = finished_mlflow_run.data.tags
+params = finished_mlflow_run.data.params
+
+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
+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
+client.download_artifacts(run_id, "helloworld.txt", ".")
+```
+
+### Compare and query
+
+Compare and query all MLflow runs in your Azure Machine Learning workspace with the following code. 
+[Learn more about how to query runs with MLflow](https://mlflow.org/docs/latest/search-syntax.html#programmatically-searching-runs). 
+
+```Python
+from mlflow.entities import ViewType
+
+all_experiments = [exp.experiment_id for exp in MlflowClient().list_experiments()]
+query = "metrics.hello_metric > 0"
+runs = mlflow.search_runs(experiment_ids=all_experiments, filter_string=query, run_view_type=ViewType.ALL)
+
+runs.head(10)
+```
+
+## Automatic logging
+With Azure Machine Learning and MLFlow, users can log metrics, model parameters and model artifacts automatically when training a model.  A [variety of popular machine learning libraries](https://mlflow.org/docs/latest/tracking.html#automatic-logging) are supported. 
+
+To enable [automatic logging](https://mlflow.org/docs/latest/tracking.html#automatic-logging) insert the following code before your training code:
+
+```Python
+mlflow.autolog()
+```
+
+[Learn more about Automatic logging with MLflow](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.autolog). 
+
 ## Manage models 
 
 Register and track your models with the [Azure Machine Learning model registry](concept-model-management-and-deployment.md#register-package-and-deploy-models-from-anywhere), which supports the MLflow model registry. Azure Machine Learning models are aligned with the MLflow model schema making it easy to export and import these models across different workflows. The MLflow related metadata such as, run ID is also tagged with the registered model for traceability. Users can submit training runs, register, and deploy models produced from MLflow runs. 
@@ -128,11 +252,13 @@ If you want to deploy and register your production ready model in one step, see
 
 To register and view a model from a run, use the following steps:
 
-1. Once the run is complete call the `register_model()` method.
+1. Once a run is complete, call the [`register_model()`](https://mlflow.org/docs/latest/python_api/mlflow.html#mlflow.register_model) method.
 
-    ```python
-    # the model folder produced from the run is registered. This includes the MLmodel file, model.pkl and the conda.yaml.
-    run.register_model(model_name = 'my-model', model_path = 'model')
+    ```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) 
+    mlflow.register_model(model_uri,"registered_model_name")
     ```
 
 1. View the registered model in your workspace with [Azure Machine Learning studio](overview-what-is-machine-learning-studio.md).