|
| 1 | +--- |
| 2 | +title: Manage models registries in Azure Machine Learning with MLflow |
| 3 | +titleSuffix: Azure Machine Learning |
| 4 | +description: Explains how to use MLflow for managing models in Azure Machine Learning |
| 5 | +services: machine-learning |
| 6 | +author: santiagxf |
| 7 | +ms.author: fasantia |
| 8 | +ms.service: machine-learning |
| 9 | +ms.subservice: core |
| 10 | +ms.date: 06/08/2022 |
| 11 | +ms.topic: conceptual |
| 12 | +ms.custom: how-to, devx-track-python |
| 13 | +--- |
| 14 | + |
| 15 | +# Manage models registries in Azure Machine Learning with MLflow |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +## Support matrix for managing models with MLflow |
| 20 | + |
| 21 | +The MLflow client exposes several methods to retrieve and manage models. The following table shows which of those methods are currently supported in MLflow when connected to Azure ML. It also compares it with other models management capabilities in Azure ML. |
| 22 | + |
| 23 | +| Feature | MLflow | Azure ML with MLflow | Azure ML CLIv2 | Azure ML Studio | |
| 24 | +| :- | :-: | :-: | :-: | :-: | |
| 25 | +| Registering models in MLflow format | **✓** | **✓** | **✓** | **✓** | |
| 26 | +| Registering models not in MLflow format | | | **✓** | **✓** | |
| 27 | +| Registering models from runs outputs/artifacts | **✓** | **✓**<sup>1</sup> | **✓**<sup>2</sup> | **✓** | |
| 28 | +| Listing registered models | **✓** | **✓** | **✓** | **✓** | |
| 29 | +| Retrieving details of registered model's versions | **✓** | **✓** | **✓** | **✓** | |
| 30 | +| Editing registered model's versions description | **✓** | **✓** | **✓** | **✓** | |
| 31 | +| Editing registered model's versions tags | **✓** | **✓** | **✓** | **✓** | |
| 32 | +| Renaming registered models | **✓** | <sup>3</sup> | <sup>3</sup> | <sup>3</sup> | |
| 33 | +| Deleting a registered model (container) | **✓** | <sup>3</sup> | <sup>3</sup> | <sup>3</sup> | |
| 34 | +| Deleting a registered model's version | **✓** | **✓** | **✓** | **✓** | |
| 35 | +| Manage MLflow model stages | **✓** | **✓** | | | |
| 36 | +| Search registered models by name | **✓** | **✓** | **✓** | **✓**<sup>4</sup> | |
| 37 | +| Search registered models using string comparators `LIKE` and `ILIKE` | **✓** | | | **✓**<sup>4</sup> | |
| 38 | +| Search registered models by tag | | | | **✓**<sup>4</sup> | |
| 39 | + |
| 40 | +> [!NOTE] |
| 41 | +> - <sup>1</sup> Use URIs with format `runs:/<ruin-id>/<path>`. |
| 42 | +> - <sup>2</sup> Use URIs with format `azureml://jobs/<job-id>/outputs/artifacts/<path>`. |
| 43 | +> - <sup>3</sup> Registered models are immutable objects in Azure ML. |
| 44 | +> - <sup>4</sup> Use search box in Azure ML Studio. Partial match supported. |
| 45 | +
|
| 46 | +## Registering new models in the registry |
| 47 | + |
| 48 | +### Creating models from an existing run |
| 49 | + |
| 50 | +If you have an MLflow model logged inside of a run and you want to register it in a registry, you can do that by using the run ID and the path where the model was logged. See [Manage experiments and runs with MLflow](how-to-track-experiments-mlflow.md) to know how to query this information if you don't have it. |
| 51 | + |
| 52 | +```python |
| 53 | +mlflow.register_model(f"runs:/{run_id}/{artifact_path}", model_name) |
| 54 | +``` |
| 55 | + |
| 56 | +### Creating models from assets |
| 57 | + |
| 58 | +If you have a folder with an MLModel MLflow model, then you can register it directly. There's no need for the model to be always in the context of a run. To do that you can use the URI schema `file://path/to/model` to register MLflow models stored in the local file system. Let's create a simple model using `Scikit-Learn` and save it in MLflow format in the local storage: |
| 59 | + |
| 60 | +```python |
| 61 | +from sklearn import linear_model |
| 62 | + |
| 63 | +reg = linear_model.LinearRegression() |
| 64 | +reg.fit([[0, 0], [1, 1], [2, 2]], [0, 1, 2]) |
| 65 | + |
| 66 | +mlflow.sklearn.save_model(reg, "./regressor") |
| 67 | +``` |
| 68 | + |
| 69 | +> [!TIP] |
| 70 | +> The method `save_model` works in the same way as `log_model`. While the latter requires an MLflow run to be active so the model can be logged there, the former uses the local file system for the stage of the model's artifacts. |
| 71 | +
|
| 72 | +You can now register the model from the local path: |
| 73 | + |
| 74 | +```python |
| 75 | +import os |
| 76 | + |
| 77 | +model_local_path = os.path.abspath("./regressor") |
| 78 | +mlflow.register_model(f"file://{model_local_path}", "local-model-test") |
| 79 | +``` |
| 80 | + |
| 81 | +> [!NOTE] |
| 82 | +> Notice how the model URI schema `file:/` requires absolute paths. |
| 83 | +
|
| 84 | +## Querying models |
| 85 | + |
| 86 | +### Querying all the models in the registry |
| 87 | + |
| 88 | +You can query all the registered models in the registry using the MLflow client with the method `list_registered_models`. The MLflow client is required to do all these operations. |
| 89 | + |
| 90 | +```python |
| 91 | +using mlflow |
| 92 | + |
| 93 | +client = mlflow.tracking.MlflowClient() |
| 94 | +``` |
| 95 | + |
| 96 | +The following sample prints all the model's names: |
| 97 | + |
| 98 | +```python |
| 99 | +for model in client.list_registered_models(): |
| 100 | + print(f"{model.name}") |
| 101 | +``` |
| 102 | + |
| 103 | +### Getting specific versions of the model |
| 104 | + |
| 105 | +The command above will retrieve the model object which contains all the model versions. However, if you want to get the last registered model version of a given model, you can use `get_registered_model`: |
| 106 | + |
| 107 | +```python |
| 108 | +client.get_registered_model(model_name) |
| 109 | +``` |
| 110 | + |
| 111 | +If you need a specific version of the model, you can indicate so: |
| 112 | + |
| 113 | +```python |
| 114 | +client.get_model_version(model_name, version=2) |
| 115 | +``` |
| 116 | + |
| 117 | +## Model stages |
| 118 | + |
| 119 | +MLflow supports model's stages to manage model's lifecycle. Model's version can transition from one stage to another. Stages are assigned to a model's version (instead of models) which means that a given model can have multiple versions on different stages. |
| 120 | + |
| 121 | +> [!IMPORTANT] |
| 122 | +> Stages can only be accessed using the MLflow SDK. They don't show up in the [Azure ML Studio portal](https://ml.azure.com) and can't be retrieved using neither Azure ML SDK, Azure ML CLI, or Azure ML REST API. Creating deployment from a given model's stage is not supported by the moment. |
| 123 | +
|
| 124 | +### Querying model stages |
| 125 | + |
| 126 | +You can use the MLflow client to check all the possible stages a model can be: |
| 127 | + |
| 128 | +```python |
| 129 | +client.get_model_version_stages(model_name, version="latest") |
| 130 | +``` |
| 131 | + |
| 132 | +You can see what model's version is on each stage by getting the model from the registry. The following example gets the model's version currently in the stage `Staging`. |
| 133 | + |
| 134 | +> [!WARNING] |
| 135 | +> Stage names are case sensitive. |
| 136 | +
|
| 137 | +```python |
| 138 | +client.get_latest_versions(model_name, stages=["Staging"]) |
| 139 | +``` |
| 140 | + |
| 141 | +> [!NOTE] |
| 142 | +> Multiple versions can be in the same stage at the same time in Mlflow, however, this method returns the latest version (greater version) among all of them. |
| 143 | +
|
| 144 | +### Transitioning models |
| 145 | + |
| 146 | +Transitioning a model's version to a particular stage can be done using the MLflow client. |
| 147 | + |
| 148 | +```python |
| 149 | +client.transition_model_version_stage(model_name, version=3, stage="Staging") |
| 150 | +``` |
| 151 | + |
| 152 | +By default, if there were an existing model version in that particular stage, it will remain there. Hence, it won't be replaced as multiple model's versions can be in the same stage at the same time. Alternatively, you can indicate `archive_existing_versions=True` to tell MLflow to move the existing model's version to the stage `Archived`. |
| 153 | + |
| 154 | +```python |
| 155 | +client.transition_model_version_stage( |
| 156 | + model_name, version=3, stage="Staging", archive_existing_versions=True |
| 157 | +) |
| 158 | +``` |
| 159 | + |
| 160 | +### Loading models from stages |
| 161 | + |
| 162 | +ou can load a model in a particular stage directly from Python using the `load_model` function and the following URI format. Notice that for this method to success, you need to have all the libraries and dependencies already installed in the environment you're working at. |
| 163 | + |
| 164 | +```python |
| 165 | +model = mlflow.pyfunc.load_model(f"models:/{model_name}/Staging") |
| 166 | +``` |
| 167 | + |
| 168 | +## Editing and deleting models |
| 169 | + |
| 170 | +Editing registered models is supported in both Mlflow and Azure ML, however, there are some differences between them that are important to notice: |
| 171 | + |
| 172 | +> [!WARNING] |
| 173 | +> Renaming models is not supported in Azure Machine Learning as model objects are immmutable. |
| 174 | +
|
| 175 | +### Editing models |
| 176 | + |
| 177 | +You can edit model's description and tags from a model using Mlflow: |
| 178 | + |
| 179 | +```python |
| 180 | +client.update_model_version(model_name, version=1, description="My classifier description") |
| 181 | +``` |
| 182 | + |
| 183 | +To edit tags, you have to use the method `set_model_version_tag` and `remove_model_version_tag`: |
| 184 | + |
| 185 | +```python |
| 186 | +client.set_model_version_tag(model_name, version="1", key="type", value="classification") |
| 187 | +``` |
| 188 | + |
| 189 | +Removing a tag: |
| 190 | + |
| 191 | +```python |
| 192 | +client.delete_model_version_tag(model_name, version="1", key="type") |
| 193 | +``` |
| 194 | + |
| 195 | +### Deleting a model's version |
| 196 | + |
| 197 | +You can delete any model version in the registry using the MLflow client, as demonstrated in the following example: |
| 198 | + |
| 199 | +```python |
| 200 | +client.delete_model_version(model_name, version="2") |
| 201 | +``` |
| 202 | + |
| 203 | +> [!NOTE] |
| 204 | +> Azure Machine Learning doesn't support deleting the entire model container. To achieve the same thing, you will need to delete all the model versions from a given model. |
0 commit comments