add Model Registry doc to website

content/en/docs/components/model-registry/_index.md

@@ -0,0 +1,5 @@
++++
+title = "Model Registry"
+description = "Documentation for Kubeflow Model Registry"
+weight = 70
++++

content/en/docs/components/model-registry/getting-started.md

@@ -0,0 +1,173 @@
++++
+title = "Getting started"
+description = "Getting started with Model Registry using examples"
+weight = 30
+
++++
+
+This guide shows how to get started with Model Registry and run a few examples using the
+command line or Python clients.
+
+At this time, the Model Registry does not include a web-based User Interface (UI), therefore this documentation focuses on backend services and APIs.
+
+For an overview of the logical model of model registry, check the
+[Model Registry logical model](https://github.com/kubeflow/model-registry/blob/main/docs/logical_model.md).
+The logical model is exposed via the Model Registry [REST API](https://editor.swagger.io/?url=https://raw.githubusercontent.com/kubeflow/model-registry/main/api/openapi/model-registry.yaml).
+
+## Prerequisites
+
+To follow along the examples in this guide, you will need a Kubeflow installation and the Model Registry installed:
+
+- Kubeflow [installed](/docs/started/installing-kubeflow/)
+- Model Registry [installed](/docs/components/model-registry/installation/)
+- Python >= 3.9, < 3.11
+
+## Example: track Model Artifacts from a Notebook
+
+This section details a step by step example on using Model Registry from a Notebook, installing and creating a client instance, indexing metadata, and retrieving metadata.
+
+### Install Model Registry Python client
+
+You can install the Model Registry python client in a Notebook, for instance with:
+
+```
+!pip install model-registry
+```
+
+Note: depending on your Python and Notebook environment, you might need to fine-tune the dependencies of: `ml-metadata`, `protobuf`, `grpcio`, or `tensorflow` if used.
+
+You can now create a client instance pointing to your deployed Model Registry from the previous steps.
+
+```python
+from model_registry import ModelRegistry
+
+registry = ModelRegistry(server_address="model-registry-service.kubeflow.svc.cluster.local", port=9090, author="your name")
+```
+
+You now have a Model Registry client instance: `registry`.
+
+### Register a Model Artifact metadata
+
+You can use the `register_model` method to index a model's artifacts and its metadata, for instance:
+
+```python
+registeredmodel_name = "mnist"
+version_name = "v0.1"
+rm = registry.register_model(registeredmodel_name,
+                                "https://github.com/tarilabs/demo20231212/raw/main/v1.nb20231206162408/mnist.onnx",
+                                model_format_name="onnx",
+                                model_format_version="1",
+                                version=version_name,
+                                description="lorem ipsum mnist",
+                                metadata={
+                                    "accuracy": 3.14,
+                                    "license": "apache-2.0",
+                                }
+                                )
+```
+
+For more information on indexing metadata in the Model Registry, refer to the pydoc documentation of the Model Registry Python client.
+
+### Retrieve a given Model Artifact metadata
+
+Continuing on the previous example, you can use the following methods to retrieve the metadata associated with a given Model Artifact:
+
+```python
+print("RegisteredModel:")
+print(registry.get_registered_model(registeredmodel_name))
+
+print("ModelVersion:")
+print(registry.get_model_version(registeredmodel_name, version_name))
+
+print("ModelArtifact:")
+print(registry.get_model_artifact(registeredmodel_name, version_name))
+```
+
+## Example add-on: deploy inference endpoint using Model Registry metadata 
+
+This section details a step by step example on using Model Registry to retrieve indexed ML artifacts metadata, and using that metadata to create an inference endpoint deployment.
+
+Without Model Registry, you would need to fill this information manually and potentially from several sources, resulting in a not-trivial, manual process.
+Using Model Registry ensures simplified access to accurate metadata, and enables you to automate deployment based on the Model Registry values, as also shown in the example below.
+
+Note: the provided example uses the Model Registry Python client and KServe Python SDK. You can analogously make use of the Model Registry REST APIs, and your own Add-on SDK as needed.
+
+### Retrieve a given Model Artifact metadata
+
+You can use the Model Registry Python client to retrieve the needed ML artifact metadata, for example:
+
+```python
+from model_registry import ModelRegistry
+
+registry = ModelRegistry(server_address="model-registry-service.kubeflow.svc.cluster.local", port=9090, author="mmortari")
+
+lookup_name = "mnist"
+lookup_version="v20231206163028"
+
+print("RegisteredModel:")
+registered_model = registry.get_registered_model(lookup_name)
+print(registered_model)
+print("ModelVersion:")
+model_version = registry.get_model_version(lookup_name, lookup_version)
+print(model_version)
+print("ModelArtifact:")
+model_artifact = registry.get_model_artifact(lookup_name, lookup_version)
+print(model_artifact)
+
+storage_uri = model_artifact.uri
+model_format_name = model_artifact.model_format_name
+model_format_version = model_artifact.model_format_version
+```
+
+These metadata values can be used to create a KServe modelmesh inference endpoint.
+
+### Create an inference endpoint using the retrieved metadata
+
+You can use the retrieved metadata from the previous step with the KServe Python SDK to create an inference endpoint, for example:
+
+```python
+from kubernetes import client 
+from kserve import KServeClient
+from kserve import constants
+from kserve import utils
+from kserve import V1beta1InferenceService
+from kserve import V1beta1InferenceServiceSpec
+from kserve import V1beta1PredictorSpec
+from kserve import V1beta1SKLearnSpec
+from kserve import V1beta1ModelSpec
+from kserve import V1beta1ModelFormat
+
+namespace = utils.get_default_target_namespace()
+name='mnist'
+kserve_version='v1beta1'
+api_version = constants.KSERVE_GROUP + '/' + kserve_version
+
+isvc = V1beta1InferenceService(api_version=api_version,
+                               kind=constants.KSERVE_KIND,
+                               metadata=client.V1ObjectMeta(
+                                   name=name, namespace=namespace,
+                                   labels={'modelregistry/registered-model-id': registered_model.id, 'modelregistry/model-version-id': model_version.id}
+                               ),
+                               spec=V1beta1InferenceServiceSpec(
+                               predictor=V1beta1PredictorSpec(
+                                 model=V1beta1ModelSpec(
+                                     storage_uri=storage_uri,
+                                     model_format=V1beta1ModelFormat(name=model_format_name, version=model_format_version),
+                                     runtime="kserve-ovms",
+                                     protocol_version='v2'
+                                 )
+                               )))
+KServe = KServeClient()
+KServe.create(isvc)
+```
+
+An inference endpoint is now created, using the artifact metadata retrieved from the Model Registry (previous step),
+specifying the serving runtime to be used to serve the model, and references to the original entities in Model Registry.
+
+## Next steps
+
+- Get involved:
+  - Model Registry working group: https://www.kubeflow.org/docs/about/community/#kubeflow-community-calendars
+  - https://github.com/kubeflow/model-registry
+- Feedback: {{% alpha-status feedbacklink="https://github.com/kubeflow/model-registry" %}}
+

content/en/docs/components/model-registry/installation.md

@@ -0,0 +1,66 @@
++++
+title = "Installation"
+description = "How to set up Model Registry"
+weight = 20
+
++++
+
+This section details how to set up and configure Model Registry on your Kubernetes cluster with Kubeflow.
+
+## Prerequisites
+
+These are the minimal requirements to install Model Registry:
+
+- Kubernetes >= 1.27
+- Kustomize >= 5.0.3 ([see more](https://github.com/kubeflow/manifests/issues/2388))
+
+<a id="model-registry-install"></a>
+
+## Installing Model Registry
+
+You can skip this step if you have already installed Kubeflow >=1.9. Your Kubeflow
+deployment includes Model Registry ([see tracker issue](https://github.com/kubeflow/manifests/issues/2631)).
+
+To install Model Registry as part of Kubeflow, follow the
+[Kubeflow installation guide](/docs/started/installing-kubeflow/).
+
+If you want to install Model Registry separately from Kubeflow, or to get a later version
+of Model Registry, you can use one of the following Model Registry manifests.
+Remember to substitute the relevant release (e.g. `v0.1.2`), modify `ref=main` to `ref=v0.1.2`.
+
+The following steps show how to install Model Registry in the context of a default Kubeflow >=1.8 installation.
+
+```shell
+kubectl apply -k "https://github.com/kubeflow/model-registry/manifests/kustomize/overlays/db?ref=main"
+```
+
+As the default Kubeflow installation provides an Istio mesh, apply the necessary manifests:
+
+```shell
+kubectl apply -k "https://github.com/kubeflow/model-registry/manifests/kustomize/options/istio?ref=main"
+```
+
+## Check Model Registry setup
+
+You can check the status of the Model Registry deployment with your Kubernetes tooling, or for example with:
+
+```shell
+kubectl wait --for=condition=available -n kubeflow deployment/model-registry-deployment --timeout=1m
+kubectl logs -n kubeflow deployment/model-registry-deployment
+```
+
+Optionally, you can also manually forward the REST API container port of Model Registry and interact with the [REST API](https://editor.swagger.io/?url=https://raw.githubusercontent.com/kubeflow/model-registry/main/api/openapi/model-registry.yaml),
+for example with:
+```shell
+kubectl port-forward svc/model-registry-service -n kubeflow 8081:8080
+# in another terminal:
+curl -X 'GET' \
+  'http://localhost:8081/api/model_registry/v1alpha3/registered_models?pageSize=100&orderBy=ID&sortOrder=DESC' \
+  -H 'accept: application/json' | jq
+```
+
+If you are not receiving a `2xx` response, it might be the case you are trying to consume a different version (`v1alphaX`) of the REST API than intended.
+
+## Next steps
+
+- Run some examples following the [getting started guide](/docs/components/model-registry/getting-started/)

content/en/docs/components/model-registry/overview.md

@@ -0,0 +1,99 @@
++++
+title = "Overview"
+description = "An overview for Kubeflow Model Registry"
+weight = 10
+
++++
+
+{{% alpha-status
+  feedbacklink="https://github.com/kubeflow/model-registry" %}}
+
+## What is Model Registry?
+
+A model registry is an important component in the lifecycle of AI/ML models, an integral component for any MLOps platform and for ML workflows.
+
+A model registry provides a central index for ML model developers to index and manage models, versions, and ML artifacts metadata.
+It fills a gap between model experimentation and production activities.
+It provides a central interface for all stakeholders in the ML lifecycle to collaborate on ML models.
+
+<img src="/docs/components/model-registry/images/MLloopinnerouter.png"
+  alt="Model Registry MLOps loop"
+  class="mt-3 mb-3">
+
+- **Create**: during the creation phase, the Model Registry facilitates collaboration between different teams in order to track changes, experiment with different model architectures, and maintain a history of model iterations.
+- **Verify**: in the verification stage, the Model Registry supports rigorous testing and validation before progressing further, maintaining a record of performance metrics and test results for each version.
+- **Package**: the Model Registry assists in organizing model artifacts and dependencies, enabling seamless integration with deployment pipelines and ensuring reproducibility across environments.
+- **Release**: when releasing a model, the Model Registry manages the transition of validated versions to production-ready status, helping organization to maintain versioning conventions and facilitating approval workflows.
+- **Deploy**: during deployment, the Model Registry provides information of the approved model versions and associated artifacts, ensuring consistency and traceability across deployment environments.
+- **Monitor**: in the monitoring phase, the Model Registry supports ongoing performance monitoring and model drift detection by maintaining a comprehensive record of deployed models and linking to their performance metrics, facilitating proactive maintenance and retraining as needed.
+
+DevOps, Data Scientists, and developers need to collaborate with other users in the ML workflow to get models into production.
+Data scientists need an efficient way to share model versions, artifacts and metadata with other users that need access to those models as part of the MLOps workflow.
+
+## Use Cases
+
+This section describes Model Registry use-cases in the context of a MLOps Platform with Model Training, Experimentation, and Deployment.
+
+A company, ACME Inc., is developing a machine-learning model for predicting customer churn. They require a centralized model registry for their MLOps platform (based on Kubeflow) for managing their ML model development lifecycle, including training, experimentation, and deployment. They want to ensure model governance, reproducibility, and efficient collaboration across data scientists and engineers.
+
+### Personas
+
+* **Data Scientist**: develops and evaluates different models for customer churn prediction. Tracks the performance of various model versions to compare them easily.
+* **MLOps Engineer**: deploys the chosen model into production. Uses the latest model version and its metadata to configure the deployment environment.
+* **Business Analyst**: Monitors the deployed model's performance and makes decisions based on its predictions. Uses model lineage and metadata to drive business outcomes.
+
+### Use Case 1: Tracking the Training of Models
+
+The _Data Scientist_ uses Kubeflow Notebooks to perform exploratory research and trains several types of models, with different hyperparameters and metrics. The Kubeflow Model Registry is used to track those models, in order to make comparisons and identify the best-performing model. Once the champion model is selected, the _Data Scientist_ shares the model with the team by maintaining the appropriate status flag on the registry. The _Data Scientist_ also tracks the lineage of training data sources and notebook code.
+
+* Track models available on storage: once the model is stored, it can then be tracked in the Kubeflow Model Registry for managing its lifecycle. The Model Registry can catalog, list, index, share, record, organize this information. This allows the _Data Scientist_ to compare different versions and revert to previous versions if needed.
+* Track and compare performance: View key metrics like accuracy, recall, and precision for each model version. This helps identify the best-performing model for deployment.
+* Create lineage: Capture the relationships between data, code, and models. This enables the _Data Scientist_ to understand the origin of each model and reproduce specific experiments.
+* Collaborate: Share models and experiment details with the _MLOps Engineer_ for deployment preparation. This ensures a seamless transition from training to production.
+
+### Use Case 2: Experimenting with Different Model Weights to Optimize Model Accuracy
+
+The _Data Scientist_ after identifying a base model, uses Kubeflow Pipelines, Katib, and other components to experiment model training with alternative weights, hyperparameters, and other variations to improve the model’s performance metrics; Kubeflow Model Registry can be used to track data related to experiments and runs for comparison, reproducibility and collaboration.
+
+* Register the Base Model: Track the Base Model storage location along with hyperparameters in the Model Registry. 
+* Track Experiments/Runs: With Kubeflow pipelines or using the Kubeflow Notebooks, track every variation of the hyper-parameters along with any configuration in that specific Experiment. With each run the different parameters can be tracked in the Model Registry.
+* Track and compare performance: with each run view key metrics like accuracy, recall, and precision. This helps the Data Scientist identify the best-performing run/experiment for deployment.
+* Reproducibility: if needed, the data tracked in Model Registry can be replayed to perform again the experiment/run to reproduce the models.
+* Collaborate: Share models and experiment details with the _MLOps Engineer_ for deployment preparation. This ensures a seamless transition from training to production.
+
+### Use Case 3: Model Deployment
+
+The _MLOps Engineer_ uses Kubeflow Model Registry to locate the most recent version for a given model, verify it is approved for deployment, understand model format, architecture, hyperparameters, and performance metrics to configure the serving environment; once deployed, Model Registry is used to continue monitoring and track deployed models for performance and mitigate drift.
+
+* Retrieve the latest model version: Easily access the model version approved for deployment.
+* Access model metadata: Understand the model's architecture, hyperparameters, and performance metrics. This helps the MLOps engineer to configure the deployment environment and monitor performance after deployment.
+* Manage serving configurations: Define how the model will be served to production applications and set up necessary resources.
+* Track model deployments: Monitor the deployed model's performance and track its health over time. This allows the MLOps Engineer to identify potential issues and take corrective actions.
+
+### Use Case 4: Monitoring and Governance
+
+The _Business Analyst_ uses Kubeflow Model Registry to audit deployed models, monitor model performance by integrating with observability tools to track key metrics and identify when model is drifting or needs re-training; capabilities of model lineage enable identifying all related artifacts such as training which was used or the original training data.
+
+* View model performance metrics: Links to observability tools tracking key metrics in real-time to understand how the model is performing in production.
+* Identify model drift: Can be used as a reference and baseline, by integrating with other tools, to detect if the model's predictions are deviating from expected behavior.
+* Access model lineage: Understand the model's origin and training details to diagnose and address performance issues.
+* Audit model usage: Track who uses the model, ensuring compliance with data privacy and security regulations. Together with lineage, they provide very important capabilities in heavily regulated industries (e.g.: FSI, Healthcare, etc.) and with respect to country regulations (e.g.: GDPR, EU AI Act, etc.).
+
+### Benefits of Model Registry:
+
+* Improved collaboration: Facilitate communication and collaboration between Data Scientists and MLOps engineers.
+* Improved experiment management: Organize and track Experiments in a centralized location for better organization and accessibility.
+* Version control: Track different versions of the model with different weight configurations, allowing comparisons and revert to previous versions if needed.
+* Increased efficiency: Streamline model development and deployment processes.
+* Enhanced governance: Ensure model compliance with regulations and organizational policies.
+* Reproducibility: Enable recreating specific experiments and model versions.
+* Better decision-making: Provide data-driven insights for improving model performance and business outcomes.
+
+### Conclusion:
+
+By implementing a model registry, ACME Inc. can significantly enhance their MLOps platform's functionality, enabling efficient model training, experimentation, and deployment. The Model Registry empowers Data Scientists, MLOps engineers, and Business analysts to collaborate effectively and make informed decisions based on reliable data and insights.
+
+## Next steps
+
+- Follow the [installation guide](/docs/components/model-registry/installation/) to set up Model Registry
+- Run some examples following the [getting started guide](/docs/components/model-registry/getting-started/)