User instructions for installing Model Registry (#137)

* User instructions for installing Model Registry Signed-off-by: Ramesh Reddy <rareddy@redhat.com> * addtions to enhance documentation to add general model registry sections then also details on deployment Signed-off-by: Ramesh Reddy <rareddy@redhat.com> * Added instructions for UI based instuctions to install Model Registry and as well usage patterns of Model Registry. Some portions from the Model Registry introduction is taken as is from Kubeflow Model registry documention. Some document contributions were also made by Matteo Mortari and Alessio Pragliola. Thank you. Signed-off-by: Ramesh Reddy <rareddy@redhat.com> * Escaping the $ in the scripts to copy and paste Signed-off-by: Ramesh Reddy <rareddy@redhat.com> * rebase after the matteo's changes Signed-off-by: Ramesh Reddy <rareddy@redhat.com> Co-authored-by: Alessio Pragliola <seth.pro@gmail.com> Co-authored-by: Matteo Mortari <matteo.mortari@gmail.com> --------- Signed-off-by: Ramesh Reddy <rareddy@redhat.com>
opendatahub-io · Oct 11, 2024 · a0afa2a · a0afa2a
1 parent 002ecbb
commit a0afa2a
Show file tree

Hide file tree

Showing 35 changed files with 1,312 additions and 0 deletions.
diff --git a/docs/Readme.md b/docs/Readme.md
@@ -0,0 +1,16 @@
+# 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, serving as the central repository holding metadata pertaining to machine learning models from inception to deployment. This encompasses both high-level details like deployment environment and project origins, as well as intricate information like training hyperparameters, performance metrics, and deployment events. Acting as a bridge between model experimentation and serving, it offers a secure, collaborative interface of a metadata store for stakeholders involved in the ML lifecycle.
+
+![Model Registry](./images/model-registry.png)
+
+
+The below are links more documentation on Model Registry
+
+1. [Introduction](./introduction.md)
+2. [Install Model Registry](./install.md)
+3. [Install and using Model Registry using UI](./how-to-use-ui.md)
+4. [How to use Model Registry Python library](./getting-started.md)
+5. [Deploy a model using UI](./deploy-model.md)
+
+
diff --git a/docs/deploy-model.md b/docs/deploy-model.md
@@ -0,0 +1,30 @@
+# Deploy Model Using Dashboard
+
+Once the model is designed and uploaded to a S3 bucket and "registered" in the Model Registry, user can choose to deploy the model for inferencing.
+
+It is expected that you have access to Open Data Hub Dashboard. Using the Dashboard, create or use existing "Data Science Project"
+
+![Model Registry](./images/dashboard-home.png)
+
+Now click on leftnav item "Model Registry", click the model, which will switch to displaying all the model versions under that model name. You can click the kebab menu next to model version and select "deploy" or client on version and then select the "actions" menu to get to the "deploy"
+
+![Model Registry](./images/dashboard-modelregistry-model.png)
+
+Which pops this window
+
+![Model Registry](./images/dashboard-modelregistry-deploy1.png)
+
+Select the target "project" you want to deploy this model into from the drop down box. Note that Model Registry is not scoped to a single project, it can scoped to whole cluster, or to more than one project. So it is required that user choose the project where they want to deploy into. Which will bring to this page
+
+![Model Registry](./images/dashboard-modelregistry-deploy2.png)
+
+On this dialog box please select
+* Serving Runtime: Model Runtime server you want to use to run your model
+* Model Framework: Select the model framework that model is designed from dropdown list.
+* Data Connection: This is one key property user must provide. Since Model Registry only contains metadata information not actual physical model, user need to provide credentials to access the model on S3 bucket. Here if "data connection" is already available in the project you can select to reuse, if not user has option to provide the credentials to the S3 bucket to reach to the model.
+
+Once you make all the other selections, click deploy. This should show the "Deployments" tab and status of the deployment.
+
+![Model Registry](./images/dashboard-modelregistry-deploy3.png)
+
+You can click on the "inference service" link in the middle of the screen to get to the Inference endpoint that you can use to connect from your application for predictions.
diff --git a/docs/example-utils.py b/docs/example-utils.py
@@ -0,0 +1,22 @@
+import requests
+import boto3
+from botocore.exceptions import NoCredentialsError
+
+def download_file(url, local_filename):
+    """
+    Downloads a file from the given URL and saves it locally.
+    
+    :param url: The URL of the file to download
+    :param local_filename: The path to save the file locally
+    :return: The local file path
+    """
+    response = requests.get(url, stream=True)
+    if response.status_code == 200:
+        with open(local_filename, 'wb') as f:
+            for chunk in response.iter_content(1024):
+                f.write(chunk)
+        print(f"File downloaded successfully: {local_filename}")
+        return local_filename
+    else:
+        raise Exception(f"Failed to download file: Status code {response.status_code}")
+
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,21 @@
+# Model Registry Python Library Usage
+
+This document introduces Model Registry Python library and some of its methods for registering and viewing models inside the Model Registry, however this should not be considered as full library reference. This is only is only used as a document to how start using the Model Registry. Refer the Python library documentation for full library reference.
+
+## Prerequisites
+It is expected that you have access to Open Data Hub Dashboard
+<ol>
+<li> You have logged into Dashboard
+<li> Created a "Data Science Project"
+<li> Configured any Cluster Storage.
+<li> Configured Data Connections needed for your project. For creating a data connection you would require connection details for S3 bucket.
+<li> Created Workbench and logged into it.
+</ol>
+
+once you have a Workbench available, log into the Jupyter Notebook and load this Python Jupyter Notebook [python-example-usage.ipynb](./python-example-usage.ipynb) for further instructions.
+
+To load the note book, click 
+
+![Upload Files](./images/upload.png) 
+
+to load the python notebook and follow directions. 
diff --git a/docs/how-to-use-ui.md b/docs/how-to-use-ui.md
@@ -0,0 +1,79 @@
+# Model Registry UI
+
+This section of the document goes over Model Registry UI and shows various features of the Model Registry.
+
+## Install Model Registry 
+
+The instructions here show how to install Model Registry using the UI. The instructions [here](./install.md) show how to install using terminal using `oc` command. You can use either one. Please note that in order to install Model Registry using UI, the installer must be in `odh-admin` user group. Please consult your cluster admin other wise.
+
+
+### Prerequisites 
+The following prerequisites are needed for installing Model Registry
+<ol>
+<li> Access to OpenShift Cluster 4.17 + (recommend)
+<li> To install the operators you need "cluster-admin" access
+<li> To install Data Science Cluster and Model Registry you need to be `odh-admin` user group. Please if you already in `cluster-admin` role one should already have this role, other wise consult your cluster administrator for requesting access. 
+<li> Make sure you have enough capacity on the cluster to install a "data science cluster" minimum is with HCP cluster is 2 nodes of m6i, real world use cases might need to be larger than this. Please consult sizing guides for OpenShift AI.
+<li> Model registry currently only works MySQL or MariaDB database, if you have an access to external database collect the credentials for it. You  need `user-id`, `password`, `host`, `port`, `database-name`
+</ol>
+
+### Installation
+
+Log "cluster-admin" install the following operators in cluster scope. Please follow the order of their install as, Authorino Operator, Red Hat Serverless Operator, Red Hat Service Mesh operator, and then Open Data Hub Operator.
+
+![Model Registry](./images/dashboard-operators.png)
+
+For installing the "Data Science Cluster", install "DSCi" and "DSC" custom resources, and make sure in DSC custom resource has below to install Model Registry operator
+
+```
+modelregistry:
+    managementState: Managed
+```
+
+when DSC cluster shows in "ready" state. Goto "route" for dashboard setting in "opendatahub" namespace and log into it. Typically there is applications tool bar button in toolbar area you can find the "Open Data Hub Dashboard" link.
+
+Once logged into Dashboard, click on "Settings -> Model Registry", on the screen choose to "Create Model Registry" which should present with the following document
+
+![Model Registry](./images/dashboard-modelregistry-create.png)
+
+Give the name to Model Registry accordingly representing the business function it represents. Please note that you can install multiple Model Registries in a given cluster with varying degrees of access. For example, you can have Model Registry that public across your whole organization, another one could be across your business unit, or could be just for your team. The access is determined by controlling users in the unique user-group that is created as part of Model Registry installation.
+
+![Model Registry](./images/dashboard-modelregistry-create2.png)
+
+Provide all the database configuration and click "create", once the status shown as "Ready", you can click on kebab menu and select "manage access" where you can manage the user-group that is mentioned above. Please note that to add users to user group, you need to log into OpenShift console and use User Management screens. Otherwise you can add individual users to "add-user" section to grant access to individual access to the registry created. Please note currently all the access control is based on Kubernetes Authn/AuthZ, there is no options to include third party authentication or authorization systems. Once the access is defined, installation of Model Registry is complete.
+
+### Catalog of Models in Model Registry
+
+Client on left navigation item "Model Registry" on the Dashboard, to take you to screen that shows the catalog of models that are registered in Model Registry. If no models are registered it will show an empty list. If there are registered models you can click to see details of the models
+
+![Model Registry](./images/dashboard-modelregistry-catalog1.png)
+
+
+### Register a Model
+
+There are two different ways of registring model in the Model Registry. One using the button in this screen "Register Model" which should pop the following screen. Follow the entries on the screen to register the model. Please note that, Model Registry currently does not actually store the model but it will capture the location of the model where it is stored in a S3 store. First get hold of the model from hugging face or other places, save it into S3 bucket, and provide the details of S3 bucket and its credentials into Register dialog box under "Data Connection" section. Once registered the model will show under model catalog screen.
+
+![Model Registry](./images/dashboard-modelregistry-catalog1.png)
+
+it will bring this screen for registering a model
+
+![Model Registry](./images/dashboard-modelregistry-registermodel.png)
+
+Another way register the model is using [Python library](./getting-started.md). Note that when you register a model the first time, it creates a Registered Model entry and related entries for the initial version that is defined. If you ever need to deploy another iteration of the model after re-training, try to add a new Model Version of the model under the original Registered Model entry. A Registered Model can contain any number of Model Versions underneath. Each version is individually managed. The below screen shows when model is drilled down to version level.
+
+![Model Registry](./images/dashboard-modelregistry-model-versions.png)
+
+and you can click on given model version and see the metadata registered at model version level.
+
+![Model Registry](./images/dashboard-modelregistry-model-versions-details.png)
+
+### Deploy Model
+
+A model version can be deployed using "deploy" action from top right. Please follow directions in [here](./deploy-model.md) for deploying a model.
+
+### Archive Model
+
+In Model Registry a model can not be deleted but it can be archived to remove from UI to reduce clutter when the number models deployed are very large. The user can choose to archive individual model versions or they can choose to archive the entire model. 
+
+![Model Registry](./images/dashboard-modelregistry-model-versions-archive.png)
+
diff --git a/docs/images/dashboard-home.png b/docs/images/dashboard-home.png
diff --git a/docs/images/dashboard-modelregistry-catalog1.png b/docs/images/dashboard-modelregistry-catalog1.png
diff --git a/docs/images/dashboard-modelregistry-catalog2.png b/docs/images/dashboard-modelregistry-catalog2.png
diff --git a/docs/images/dashboard-modelregistry-create.png b/docs/images/dashboard-modelregistry-create.png
diff --git a/docs/images/dashboard-modelregistry-create2.png b/docs/images/dashboard-modelregistry-create2.png
diff --git a/docs/images/dashboard-modelregistry-deploy1.png b/docs/images/dashboard-modelregistry-deploy1.png
diff --git a/docs/images/dashboard-modelregistry-deploy2.png b/docs/images/dashboard-modelregistry-deploy2.png
diff --git a/docs/images/dashboard-modelregistry-deploy3.png b/docs/images/dashboard-modelregistry-deploy3.png
diff --git a/docs/images/dashboard-modelregistry-model-versions-archive.png b/docs/images/dashboard-modelregistry-model-versions-archive.png
diff --git a/docs/images/dashboard-modelregistry-model-versions-details.png b/docs/images/dashboard-modelregistry-model-versions-details.png
diff --git a/docs/images/dashboard-modelregistry-model-versions.png b/docs/images/dashboard-modelregistry-model-versions.png
diff --git a/docs/images/dashboard-modelregistry-model.png b/docs/images/dashboard-modelregistry-model.png
diff --git a/docs/images/dashboard-modelregistry-registermodel.png b/docs/images/dashboard-modelregistry-registermodel.png
diff --git a/docs/images/dashboard-modelserver.png b/docs/images/dashboard-modelserver.png
diff --git a/docs/images/dashboard-operators.png b/docs/images/dashboard-operators.png
diff --git a/docs/images/ml-lifecycle-kubeflow-modelregistry.drawio.svg b/docs/images/ml-lifecycle-kubeflow-modelregistry.drawio.svg
diff --git a/docs/images/model-registry-architecture.png b/docs/images/model-registry-architecture.png
diff --git a/docs/images/model-registry.png b/docs/images/model-registry.png
diff --git a/docs/images/upload.png b/docs/images/upload.png