Deprecate model registry stages in docs (mlflow#10480)

Signed-off-by: Jerry Liang <[email protected]>
Signed-off-by: Jerry Liang <[email protected]>
Co-authored-by: WeichenXu <[email protected]>
Co-authored-by: Siddharth Murching <[email protected]>

README_SKINNY.rst

@@ -6,7 +6,7 @@ MLflow Skinny is a lightweight MLflow package without SQL storage, server, UI, o
 MLflow Skinny supports:
 
 * Tracking operations (logging / loading / searching params, metrics, tags + logging / loading artifacts)
-* Model registration, search, artifact loading, and transitions
+* Model registration, search, artifact loading, and deployment
 * Execution of GitHub projects within notebook & against a remote target.
 
 Additional dependencies can be installed to leverage the full feature set of MLflow. For example:

docs/source/getting-started/index.rst

@@ -13,7 +13,7 @@ In this brief introductory quickstart on MLflow Tracking, you will learn how to
 
 * **Log** training statistics (loss, accuracy, etc.) and hyperparameters for a model
 * **Log** (save) a model for later retrieval
-* **Register** a model to enable state transitions for deployment
+* **Register** a model to enable deployment
 * **Load** the model and use it for inference
 
 In the process of learning these key concepts, you will be exposed to the MLflow fluent API, the MLflow Tracking UI, and learn how to add metadata associated with 

docs/source/getting-started/quickstart-2/index.rst

@@ -208,14 +208,7 @@ Choose the best run and register it as a model. In the **Table view**, choose th
 
 Now, your model is available for deployment. You can see it in the **Models** page of the MLflow UI. Open the page for the model you just registered.
 
-You can add a description for the model, add tags, and easily navigate back to the source run that generated this model. You can also transition the model to different stages. For example, you can transition the model to **Staging** to indicate that it is ready for testing. You can transition it to **Production** to indicate that it is ready for deployment.
-
-Transition the model to **Staging** by choosing the **Stage** dropdown:
-
-.. image:: ../../_static/images/quickstart_mlops/mlflow_registry_transitions.png
-    :width: 800px
-    :align: center
-    :alt: Screenshot of MLflow tracking UI models page showing the registered model
+You can add a description for the model, add tags, and easily navigate back to the source run that generated this model. You can also apply aliases and tags to the model for easier organization and deployment. For more information, see :ref:`registry`.
 
 Serve the model locally
 ----------------------------
@@ -224,7 +217,7 @@ MLflow allows you to easily serve models produced by any run or model version. Y
 
 .. code-block:: bash
 
-  mlflow models serve -m "models:/wine-quality/Staging" --port 5002
+  mlflow models serve -m "models:/wine-quality/1" --port 5002
 
 (Note that specifying the port as above will be necessary if you are running the tracking server on the same machine at the default port of **5000**.)
 
@@ -256,7 +249,7 @@ Most routes toward deployment will use a container to package your model, its de
 
   mlflow models build-docker --model-uri "models:/wine-quality/1" --name "qs_mlops"
 
-This command builds a Docker image named ``qs_mlops`` that contains your model and its dependencies. The ``model-uri`` in this case specifies a version number (``/1``) rather than a lifecycle stage (``/staging``), but you can use whichever integrates best with your workflow. It will take several minutes to build the image. Once it completes, you can run the image to provide real-time inferencing locally, on-prem, on a bespoke Internet server, or cloud platform. You can run it locally with:
+This command builds a Docker image named ``qs_mlops`` that contains your model and its dependencies. It will take several minutes to build the image. Once it completes, you can run the image to provide real-time inferencing locally, on-prem, on a bespoke Internet server, or cloud platform. You can run it locally with:
 
 .. code-block:: bash
 

docs/source/introduction/index.rst

@@ -25,7 +25,7 @@ foundational components:
 
 * :ref:`Tracking <tracking>`: MLflow Tracking provides both an API and UI dedicated to the logging of parameters, code versions, metrics, and artifacts during the ML process. This centralized repository captures details such as parameters, metrics, artifacts, data, and environment configurations, giving teams insight into their models' evolution over time. Whether working in standalone scripts, notebooks, or other environments, Tracking facilitates the logging of results either to local files or a server, making it easier to compare multiple runs across different users.
 
-* :ref:`Model Registry <registry>`: A systematic approach to model management, the Model Registry assists in handling different versions of models, discerning their current state, and ensuring a smooth transition from development to production. It offers a centralized model store, APIs, and UI to collaboratively manage an MLflow Model's full lifecycle, including model lineage, versioning, stage transitions, and annotations.
+* :ref:`Model Registry <registry>`: A systematic approach to model management, the Model Registry assists in handling different versions of models, discerning their current state, and ensuring smooth productionization. It offers a centralized model store, APIs, and UI to collaboratively manage an MLflow Model's full lifecycle, including model lineage, versioning, aliasing, tagging, and annotations.
 
 * :ref:`AI Gateway <gateway>`: This server, equipped with a set of standardized APIs, streamlines access to both SaaS and OSS LLM models. It serves as a unified interface, bolstering security through authenticated access, and offers a common set of APIs for prominent LLMs.
 
@@ -51,7 +51,7 @@ Ensuring productivity and efficiency throughout this lifecycle poses several cha
 
 - **Deployment Consistency**: With the plethora of ML libraries available, there's often no standardized way to package and deploy models. Custom solutions can lead to inconsistencies, and the crucial link between a model and the code and parameters that produced it might be lost.
 
-- **Model Management**: As data science teams produce numerous models, managing these models, their versions, and stage transitions becomes a significant hurdle. Without a centralized platform, managing model lifecycles, from development to staging to production, becomes unwieldy.
+- **Model Management**: As data science teams produce numerous models, managing, testing, and continuously deploying these models becomes a significant hurdle. Without a centralized platform, managing model lifecycles becomes unwieldy.
 
 - **Library Agnosticism**: While individual ML libraries might offer solutions to some of the challenges, achieving the best results often involves experimenting across multiple libraries. A platform that offers compatibility with various libraries while ensuring models are usable as reproducible "black boxes" is essential.
 

docs/source/model-registry.rst

@@ -22,10 +22,10 @@ Model
     An MLflow Model is created from an experiment or run that is logged with one of the model flavor’s ``mlflow.<model_flavor>.log_model()`` methods. Once logged, this model can then be registered with the Model Registry.
 
 Registered Model
-    An MLflow Model can be registered with the Model Registry. A registered model has a unique name, contains versions, associated transitional stages, model lineage, and other metadata.
+    An MLflow Model can be registered with the Model Registry. A registered model has a unique name, contains versions, aliases, tags, and other metadata.
 
 Model Version
-    Each registered model can have one or many versions. When a new model is added to the Model Registry, it is added as version 1. Each new model registered to the same model name increments the version number.
+    Each registered model can have one or many versions. When a new model is added to the Model Registry, it is added as version 1. Each new model registered to the same model name increments the version number. Model versions have tags, which can be useful for tracking attributes of the model version (e.g. `pre_deploy_checks: "PASSED"`)
 
 .. _using-registered-model-aliases:
 
@@ -40,9 +40,6 @@ Tags
 Annotations and Descriptions
     You can annotate the top-level model and each version individually using Markdown, including description and any relevant information useful for the team such as algorithm descriptions, dataset employed or methodology.
 
-Model Stage
-    Each distinct model version can be assigned one stage at any given time. MLflow provides predefined stages for common use-cases such as *Staging*, *Production* or *Archived*. You can transition a model version from one stage to another stage.
-
 Model Registry Workflows
 ========================
 If running your own MLflow server, you must use a database-backed backend store in order to access
@@ -277,21 +274,6 @@ To fetch a model version by alias, specify the model alias in the model URI, and
 
 Note that model alias assignments can be updated independently of your production code. If the ``champion`` alias in the snippet above is reassigned to a new model version in the Model Registry, the next execution of this snippet will automatically pick up the new model version. This allows you to decouple model deployments from your inference workloads.
 
-**Fetch the latest model version in a specific stage**
-
-To fetch a model version by stage, simply provide the model stage as part of the model URI, and it will fetch the most recent version of the model in that stage.
-
-.. code-block:: python
-
-    import mlflow.pyfunc
-
-    model_name = "sk-learn-random-forest-reg-model"
-    stage = "Staging"
-
-    model = mlflow.pyfunc.load_model(model_uri=f"models:/{model_name}/{stage}")
-
-    model.predict(data)
-
 Serving an MLflow Model from Model Registry
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -519,7 +501,7 @@ This code snippet creates a sklearn model, which we assume that you had created
     Coefficient of determination: 0.47
 
 
-Once saved in pickled format, we can load the sklearn model into memory using pickle API and
+Once saved in pickled format, you can load the sklearn model into memory using pickle API and
 register the loaded model with the Model Registry.
 
 .. code-block:: python
@@ -557,7 +539,7 @@ register the loaded model with the Model Registry.
     Model name: SklearnLinearRegression, version 1
     Created version '1' of model 'SklearnLinearRegression'.
 
-Now, using MLflow fluent APIs, we reload the model from the Model Registry and score.
+Now, using MLflow fluent APIs, you reload the model from the Model Registry and score.
 
 .. code-block:: python
 
@@ -705,8 +687,15 @@ save, log, register, and load from the Model Registry and score.
     <Yay!! Another good phone interview. I nailed it!!> -- {'neg': 0.0, 'neu': 0.446, 'pos': 0.554, 'compound': 0.816}
     <This is INSANE! I can't believe it. How could you do such a horrible thing?> -- {'neg': 0.357, 'neu': 0.643, 'pos': 0.0, 'compound': -0.8034}
 
-Transitioning an MLflow Model’s Stage
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Deprecated: Using Model Stages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. warning:: Model Stages are deprecated and will be removed in a future major release. To learn more about this deprecation, see our :ref:`migration guide<migrating-from-stages>` below.
+
+See the sections below on using Model Stages in the MLflow Model Registry.
+
+**Transitioning an MLflow Model’s Stage**
+
 Over the course of the model’s lifecycle, a model evolves—from development to staging to production.
 You can transition a registered model to one of the stages: **Staging**, **Production** or **Archived**.
 
@@ -719,8 +708,23 @@ You can transition a registered model to one of the stages: **Staging**, **Produ
 
 The accepted values for <stage> are: Staging|Archived|Production|None.
 
-Archiving an MLflow Model
-^^^^^^^^^^^^^^^^^^^^^^^^^
+**Fetch the latest model version in a specific stage**
+
+To fetch a model version by stage, simply provide the model stage as part of the model URI, and it will fetch the most recent version of the model in that stage.
+
+.. code-block:: python
+
+    import mlflow.pyfunc
+
+    model_name = "sk-learn-random-forest-reg-model"
+    stage = "Staging"
+
+    model = mlflow.pyfunc.load_model(model_uri=f"models:/{model_name}/{stage}")
+
+    model.predict(data)
+
+**Archiving an MLflow Model**
+
 You can move models versions out of a **Production** stage into an **Archived** stage.
 At a later point, if that archived model is not needed, you can delete it.
 
@@ -732,3 +736,84 @@ At a later point, if that archived model is not needed, you can delete it.
         name="sk-learn-random-forest-reg-model", version=3, stage="Archived"
     )
 
+.. _migrating-from-stages:
+
+Migrating from Stages
+=====================
+
+As of MLflow 2.9.0, Model Stages have been deprecated and will be removed in a future major release. This is the culmination of extensive feedback on the inflexibility of model stages for expressing MLOps workflows, from which we developed and introduced of new tools for managing and deploying models in the MLflow Model Registry. Learn more below.
+
+New model deployment tools
+--------------------------
+
+Model stages were used to express the lifecycle of MLflow Models for productionization and deployment. Users transitioned model versions through four fixed stages (from **none**, to **staging**, to **production**, and then to **archived**) as they proposed, validated, deployed, and deprecated models for their ML use-cases. In doing so, model registry stages provided labeling and aliasing functionality for the model versions, by denoting the status of a model version in the UI and providing named references to model versions in the code (e.g. ``/Staging`` in the model URI). Model registry stages were also used to denote the environment that the model is in, though it was not possible to set up access controls for them.
+
+To replace and improve upon stages, we elevated **model version tags** in the UI and introduced **model version aliases** to provide flexible and powerful ways to label and alias MLflow models in the Model Registry. We also made it possible to **set up separate environments** for your models and configure access controls for each environment.
+
+**Model version tags**
+
+Model version tags can be used to annotate model versions with their status. For example, you could apply a tag of key ``validation_status`` and value ``pending`` to a model version while it is being validated and then update the tag value to ``passed`` when it has passed smoke tests and performance tests.
+
+**Model version aliases**
+
+Model version aliases provide a flexible way to create named references for particular model versions, and are useful for identifying which model version(s) are deployed within an environment. For example, setting a **champion** alias on a model version enables you to fetch the model version by that alias via the :meth:`~mlflow.client.MlflowClient.get_model_version_by_alias` client API or the model URI ``models:/<registered model name>@champion``. Aliases can be reassigned to new model versions via the UI and client API. Unlike model registry stages, more than one alias can be applied to any given model version, allowing for easier A/B testing and model rollout.
+
+**Set up separate environments for models**
+
+In mature DevOps and MLOps workflows, organizations use separate environments (typically, dev, staging, and prod) with access controls to enable quick development without compromising stability in production. With :ref:`MLflow Authentication <auth>`, you can use registered models to express access-controlled environments for your MLflow models. For example, you can create registered models corresponding to each combination of environment and business problem (e.g. `prod.ml_team.revenue_forecasting`, `dev.ml_team.revenue_forecasting`) and configure permissions accordingly. Automate model retraining against your production registered models, or for simple model deployment use cases, use :meth:`~mlflow.client.MlflowClient.copy_model_version` to promote model versions across registered models.
+
+Migrating models away from stages
+---------------------------------
+
+See the information below to learn how to use the new tools for your legacy Model Stage use-cases.
+
+**Model environments**
+
+To set up separate environments and permissions for your model versions, create separate registered models:
+
+* Given a base name for your model’s use-case, e.g. ``revenue_forecasting``, set up various registered models corresponding to your environments with different prefixes.
+* For example, if you want three separate dev, staging, and production environments, you can set up ``dev.ml_team.revenue_forecasting``, ``staging.ml_team.revenue_forecasting``, and ``prod.ml_team.revenue_forecasting`` registered models.
+* Use :ref:`MLflow Authentication <auth>` to grant appropriate permissions on these models.
+
+**Transition models across environments**
+
+Once you have registered models set up for each environment, you can build your MLOps workflows on top of them.
+
+* For simple model promotion use cases, you can first register your MLflow models under the dev registered model and then promote models across environments using the :meth:`~mlflow.client.MlflowClient.copy_model_version` client API.
+* For more mature production-grade setups, we recommend promoting your ML code (including model training code, inference code, and ML infrastructure as code) across environments. This eliminates the need to transition models across environments. Dev ML code is experimental and in a dev environment, hence targeting the dev registered model. Before merging developed ML code into your source code repository, your CI stages the code in a staging environment for integration testing (targeting the staging registered model). Post-merge, the ML code is deployed to production for automated retraining (targeting the prod registered model). Such setups enable safe and robust CI/CD of ML systems - including not just model training, but also feature engineering, model monitoring, and automated retraining.
+
+**Model aliasing**
+
+To specify (via named references) which model version to deploy to serve traffic within an environment (e.g. production), use **model aliases**:
+
+1. Decide on an equivalent model alias for each model registry stage (e.g., **champion** for the **Production** stage, to specify the model intended to serve the majority of traffic)
+2. Assign the chosen alias to the latest model version under each stage. You can use the helper function below for this.
+3. Update ML workflows to target the alias rather than the stage. For example, the model URI ``models:/regression_model/Production`` will be replaced by the model URI ``models:/prod.ml_team.regression_model@champion`` in the production code.
+
+.. code-block:: python
+
+    from mlflow import MlflowClient
+
+    # Initialize an MLflow Client
+    client = MlflowClient()
+
+
+    def assign_alias_to_stage(model_name, stage, alias):
+        """
+        Assign an alias to the latest version of a registered model within a specified stage.
+
+        :param model_name: The name of the registered model.
+        :param stage: The stage of the model version for which the alias is to be assigned. Can be
+                    "Production", "Staging", "Archived", or "None".
+        :param alias: The alias to assign to the model version.
+        :return: None
+        """
+        latest_mv = client.get_latest_versions(model_name, stages=[stage])[0]
+        client.set_registered_model_alias(model_name, alias, latest_mv.version)
+
+**Model status**
+
+To represent and communicate the status of your model versions, use model version tags:
+
+* Set tags on model versions to indicate the status of the model.
+* For example, to indicate the review status of a model version, you can set a tag with key ``validation_status`` and value ``pending`` or ``passed``.