Merge pull request #203666 from santiagxf/santiagxf/aml-mlflow-review

v-dirichards · web-flow · commit 3f4339ac49c9 · 2022-07-05T10:07:06.000-05:00
Update MLflow general guidance
diff --git a/articles/machine-learning/concept-mlflow.md b/articles/machine-learning/concept-mlflow.md
@@ -48,6 +48,10 @@ With MLflow Tracking you can connect Azure Machine Learning as the backend of yo
 
 Azure Machine Learning uses MLflow Tracking for metric logging and artifact storage for your experiments, whether you created the experiment via the Azure Machine Learning Python SDK, Azure Machine Learning CLI or the Azure Machine Learning studio. Learn more at [Track experiments with MLflow](how-to-use-mlflow-cli-runs.md).
 
+> [!IMPORTANT]
+> - MLflow in R support is limited to tracking experiment's metrics and parameters on Azure Machine Learning jobs. RStudio or Jupyter Notebooks with R kernels are not supported. View the following [R example about using the MLflow tracking client with Azure Machine Learning](https://github.com/Azure/azureml-examples/tree/main/cli/jobs/single-step/r).
+> - MLflow in Java support is limited to tracking experiment's metrics and parameters on Azure Machine Learning jobs. View the following [Java example about using the MLflow tracking client with the Azure Machine Learning](https://github.com/Azure/azureml-examples/tree/main/cli/jobs/single-step/java/iris).
+
 ## Model Registries with MLflow
 
 Azure Machine Learning supports MLflow for model management. This represents a convenient way to support the entire model lifecycle for users familiar with the MLFlow client. The following article describes the different capabilities and how it compares with other options.
@@ -68,7 +72,6 @@ You can submit training jobs to Azure Machine Learning using [MLflow Projects](h
 
 Learn more at [Train ML models with MLflow projects and Azure Machine Learning (preview)](how-to-train-mlflow-projects.md).
 
-
 ## MLflow SDK, Azure ML v2 and Azure ML Studio capabilities
 
 The following table shows which operations are supported by each of the tools available in the ML lifecycle.
@@ -82,19 +85,27 @@ The following table shows which operations are supported by each of the tools av
 | Submit training pipelines | | **&check;** | |
 | Manage experiments runs | **&check;**<sup>1</sup> | **&check;** | **&check;** |
 | Manage MLflow models | **&check;**<sup>3</sup> | **&check;** | **&check;** |
-| Manage non-MLflow models | **&check;**<sup>4</sup> | **&check;** | **&check;** |
-| Deploy MLflow models to Azure Machine Learning | **&check;**<sup>5</sup> | **&check;** | **&check;** |
+| Manage non-MLflow models | | **&check;** | **&check;** |
+| Deploy MLflow models to Azure Machine Learning | **&check;**<sup>4</sup> | **&check;** | **&check;** |
 | Deploy non-MLflow models to Azure Machine Learning | | **&check;** | **&check;** |
 
 > [!NOTE]
 > - <sup>1</sup> View [Manage experiments and runs with MLflow](how-to-track-experiments-mlflow.md) for details.
 > - <sup>2</sup> Only artifacts and models can be downloaded.
 > - <sup>3</sup> View [Manage models registries in Azure Machine Learning with MLflow](how-to-manage-models-mlflow.md) for details.
-> - <sup>4</sup> Loading models using the syntax `models:/model-name/version` is not supported for non-MLflow models.
-> - <sup>5</sup> View [Deploy MLflow models to Azure Machine Learning](how-to-deploy-mlflow-models.md) for details. Deployment of MLflow models to batch inference using the MLflow SDK is not possible by the moment.
-
-
-## Next steps
-* [Track ML models with MLflow and Azure Machine Learning CLI v2](how-to-use-mlflow-cli-runs.md)
-* [Convert your custom model to MLflow model format for no code deployments](how-to-convert-custom-model-to-mlflow.md)
-* [Deploy MLflow models](how-to-deploy-mlflow-models.md)
+> - <sup>4</sup> View [Deploy MLflow models to Azure Machine Learning](how-to-deploy-mlflow-models.md) for details. Deployment of MLflow models to batch inference using the MLflow SDK is not possible by the moment.
+
+## Example notebooks
+
+If you are getting started with MLflow in Azure Machine Learning, we recommend you to explore the [notebooks examples about how to user MLflow](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/readme.md):
+
+* [Training and tracking a classifier with MLflow](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/train-with-mlflow/xgboost_classification_mlflow.ipynb): Demonstrates how to track experiments using MLflow, log models and combine multiple flavors into pipelines.
+* [Training and tracking a classifier with MLflow using Service Principal authentication](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/train-with-mlflow/xgboost_service_principal.ipynb): Demonstrate how to track experiments using MLflow from compute that is running outside Azure ML and how to authenticate against Azure ML services using a Service Principal.
+* [Hyper-parameters optimization using child runs with MLflow and HyperOpt optimizer](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/train-with-mlflow/xgboost_nested_runs.ipynb): Demonstrate how to use child runs in MLflow to do hyper-parameter optimization for models using the popular library HyperOpt. It shows how to transfer metrics, params and artifacts from child runs to parent runs.
+* [Logging models instead of assets with MLflow](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/logging-models/logging_model_with_mlflow.ipynb): Demonstrates how to use the concept of models instead of artifacts with MLflow, including how to construct custom models.
+* [Manage experiments and runs with MLflow](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/run-history/run_history.ipynb): Demonstrates how to query experiments, runs, metrics, parameters and artifacts from Azure ML using MLflow.
+* [Manage models registries with MLflow](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/model-management/model_management.ipynb): Demonstrates how to manage models in registries using MLflow.
+* [No-code deployment with MLflow](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/no-code-deployment/deploying_with_mlflow.ipynb): Demonstrates how to deploy models in MLflow format to the different deployment target in Azure ML.
+* [Training models in Azure Databricks and deploying them on Azure ML with MLflow](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/no-code-deployment/track_with_databricks_deploy_aml.ipynb): Demonstrates how to train models in Azure Databricks and deploy them in Azure ML. It also includes how to handle cases where you also want to track the experiments with the MLflow instance in Azure Databricks.
+* [Migrating models with scoring scripts to MLflow format](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/migrating-scoring-to-mlflow/scoring_to_mlmodel.ipynb): Demonstrates how to migrate models with scoring scripts to no-code-deployment with MLflow.
+* [Using MLflow REST with Azure ML](https://github.com/Azure/azureml-examples/blob/main/notebooks/using-mlflow/using-rest-api/using_mlflow_rest_api.ipynb): Demonstrates how to work with MLflow REST API when connected to Azure ML.
diff --git a/articles/machine-learning/how-to-deploy-mlflow-models.md b/articles/machine-learning/how-to-deploy-mlflow-models.md
@@ -39,7 +39,7 @@ For no-code-deployment, Azure Machine Learning
 > - Data type `mlflow.types.DataType.Binary` is not supported as column type in signatures. For models that work with images, we suggest you to use or (a) tensors inputs using the [TensorSpec input type](https://mlflow.org/docs/latest/python_api/mlflow.types.html#mlflow.types.TensorSpec), or (b) `Base64` encoding schemes with a `mlflow.types.DataType.String` column type, which is commonly used when there is a need to encode binary data that needs be stored and transferred over media.
 > - Signatures with tensors with unspecified shapes (`-1`) is only supported at the batch size by the moment. For instance, a signature with shape `(-1, -1, -1, 3)` is not supported but `(-1, 300, 300, 3)` is.
 
-For more information about how to specify requests to online endpoints, view [Considerations when deploying to real-time inference](#considerations-when-deploying-to-real-time-inference). FOr more information about the supported file types in batch endpoints, view [Considerations when deploying to batch inference](#considerations-when-deploying-to-batch-inference).
+For more information about how to specify requests to online endpoints, view [Considerations when deploying to real-time inference](#considerations-when-deploying-to-real-time-inference). For more information about the supported file types in batch endpoints, view [Considerations when deploying to batch inference](#considerations-when-deploying-to-batch-inference).
 
 ## Deployment tools
 
@@ -49,7 +49,7 @@ There are three workflows for deploying MLflow models to Azure Machine Learning:
 - [Deploy using Azure ML CLI (v2)](#deploy-using-azure-ml-cli-v2)
 - [Deploy using Azure Machine Learning studio](#deploy-using-azure-machine-learning-studio)
 
-Each workflows has different capabilities, particularly around which type of compute they can target. The following table shows them:
+Each workflow has different capabilities, particularly around which type of compute they can target. The following table shows them:
 
 | Scenario | MLflow SDK | Azure ML CLI/SDK v2 | Azure ML studio |
 | :- | :-: | :-: | :-: |
@@ -160,25 +160,31 @@ The MLflow plugin [azureml-mlflow](https://pypi.org/project/azureml-mlflow/) can
    
    ```python
    import json
-   from mlflow.deployments import get_deploy_client
    
-   # Create the deployment configuration.
    deploy_config = {"computeType": "aks", "computeTargetName": "aks-mlflow" }
+   
+   deployment_config_path = "deployment_config.json"
+   with open(deployment_config_path, "w") as outfile:
+      outfile.write(json.dumps(deploy_config))
    ```
    
    # [ACI](#tab/aci)
    
    ```python
    import json
-   from mlflow.deployments import get_deploy_client
 
-   # Create the deployment configuration.
    deploy_config = {"computeType": "aci"}
+   
+   deployment_config_path = "deployment_config.json"
+   with open(deployment_config_path, "w") as outfile:
+      outfile.write(json.dumps(deploy_config))
    ```
    
 4. Create a deployment client using the Azure Machine Learning Tracking URI.
 
    ```python
+   from mlflow.deployments import get_deploy_client
+   
    # Set the tracking uri in the deployment client.
    client = get_deploy_client("<azureml-mlflow-tracking-url>")
    ```
@@ -233,14 +239,52 @@ This example shows how you can deploy an MLflow model to an online endpoint usin
 
     :::code language="azurecli" source="~/azureml-examples-main/cli/deploy-managed-online-endpoint-mlflow.sh" ID="create_endpoint":::
 
-1. Create a YAML configuration file for the deployment. The following example configures a deployment of the `sklearn-diabetes` model to the endpoint created in the previous step:
-
-    > [!IMPORTANT]
-    > For MLflow no-code-deployment (NCD) to work, setting **`type`** to **`mlflow_model`** is required, `type: mlflow_model​`. For more information, see [CLI (v2) model YAML schema](reference-yaml-model.md).
+1. Create a YAML configuration file for the deployment. 
+   
+   # [From a training job](#tab/fromjob)
+   
+   The following example configures a deployment `sklearn-diabetes` to the endpoint created in the previous step. The model is registered from a job previously run:
+   
+   a. Get the job name of the training job. In this example we are assuming the job you want is the last one submitted to the platform.
+   
+   ```bash
+   JOB_NAME=$(az ml job list --query "[0].name" | tr -d '"')
+   ```
+   
+   b. Register the model in the registry. 
+   
+   ```bash
+   az ml model create --name "mir-sample-sklearn-mlflow-model" \
+                      --type "mlflow_model" \
+                      --path "azureml://jobs/$JOB_NAME/outputs/artifacts/model"
+   ```
+   
+   c. Create the deployment `YAML` file:
+   
+   __sklearn-deployment.yaml__
+   
+   ```yaml
+   $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
+   name: sklearn-deployment
+   endpoint_name: my-endpoint
+   model: azureml:mir-sample-sklearn-mlflow-model@latest
+   instance_type: Standard_DS2_v2
+   instance_count: 1
+   ```
+   
+   > [!IMPORTANT]
+   > For MLflow no-code-deployment (NCD) to work, setting **`type`** to **`mlflow_model`** is required, `type: mlflow_model​`. For more information, see [CLI (v2) model YAML schema](reference-yaml-model.md).
+   
+   # [From a local model](#tab/fromlocal)
+   
+   The following example configures a deployment `sklearn-diabetes` to the endpoint created in the previous step using the local MLflow model:
 
     __sklearn-deployment.yaml__
 
     :::code language="yaml" source="~/azureml-examples-main/cli/endpoints/online/mlflow/sklearn-deployment.yaml":::
+    
+    > [!IMPORTANT]
+   > For MLflow no-code-deployment (NCD) to work, setting **`type`** to **`mlflow_model`** is required, `type: mlflow_model​`. For more information, see [CLI (v2) model YAML schema](reference-yaml-model.md).
 
 1. To create the deployment using the YAML configuration, use the following command:
 
@@ -251,7 +295,7 @@ This example shows how you can deploy an MLflow model to an online endpoint usin
 You can use [Azure Machine Learning studio](https://ml.azure.com) to deploy models to Managed Online Endpoints.
 
 > [!IMPORTANT]
-> Although deploying to ACI or AKS with [Azure Machine Learning studio](https://ml.azure.com) is possible. no-code deployment feature is not available for these compute targets. We recommend the use of [managed online endpoints](concept-endpoints.md) as it provides a superior set of features.
+> Although deploying to ACI or AKS with [Azure Machine Learning studio](https://ml.azure.com) is possible, no-code deployment feature is not available for these compute targets. We recommend the use of [managed online endpoints](concept-endpoints.md) as it provides a superior set of features.
 
 1. Ensure your model is registered in the Azure Machine Learning registry. Deployment of unregistered models is not supported in Azure Machine Learning. You can register models from files in the local file system or from the output of a job:
 
