[HWORKS-888] Improve documentation for gRPC support

Author: javierdlrm

docs/assets/images/guides/mlops/serving/deployment_grpc_select.png

@@ -1,19 +1,30 @@
-KServe is an open-source framework for model serving on Kubernetes.
-In Hopsworks, you can easily deploy models from the model registry in KServe or in Docker containers (for Hopsworks Community). You can deploy models in either programs, using the HSML library, or in the UI. A KServe model deployment can include the following components:
-
- - **Transformer**
-    - A pre-processing and post-processing component that can transform model inputs before predictions are made
- - **Predictor** 
-    - A predictor is a ML model in a Python object that takes a feature vector as input and returns a prediction as output
- - **Inference Logger**
-    - Hopsworks logs inputs and outputs of transformers and predictors to a Kafka topic that is part of the same project as the model
- - **Inference Batcher**
-    - Inference requests can be batched in different ways to adjust the trade-off between throughput and latencies of the model predictions
- - **Versioned Deployments**
-    - Model deployments are versioned, enabling A/B testing and more.
- - **Istio Model Endpoint**
-    - You can publish model via a REST Endpoint using Istio and access it over HTTP using a Hopsworks API key (with serving scope). Secure and authorized access is guaranteed by Hopsworks.
-
-Models deployed on KServe in Hopsworks can be easily integrated with the Hopsworks feature store using a Transformer Python script, that builds the predictor's input feature vector using the application input and pre-computed features from the feature store.
+In Hopsworks, you can easily deploy models from the model registry in KServe or in Docker containers (for Hopsworks Community). KServe is an open-source framework for model serving on Kubernetes. You can deploy models in either programs, using the HSML library, or in the UI. A KServe model deployment can include the following components:
+
+**`Transformer`**
+
+:   A ^^pre-processing^^ and ^^post-processing^^ component that can transform model inputs before predictions are made, and predictions before these are delivered back to the client.
+    
+
+**`Predictor`**
+
+:   A predictor is a ML model in a Python object that takes a feature vector as input and returns a prediction as output.
+
+**`Inference Logger`**
+
+:   Hopsworks logs inputs and outputs of transformers and predictors to a ^^Kafka topic^^ that is part of the same project as the model.
+
+**`Inference Batcher`**
+
+:   Inference requests can be batched in different ways to adjust the trade-off between throughput and latencies of the model predictions.
+
+**`Istio Model Endpoint`**
+
+:   You can publish a model via a ^^REST or gRPC Endpoint^^ using Istio and access it over HTTP using a Hopsworks API key (with serving scope). Secure and authorized access is guaranteed by Hopsworks.
+
+
+Models deployed on KServe in Hopsworks can be easily integrated with the Hopsworks Feature Store using a Transformer Python script, that builds the predictor's input feature vector using the application input and pre-computed features from the Feature Store.
 
 <img src="../../../assets/images/concepts/mlops/kserve.svg">
+
+!!! info "Model Serving Guide"
+    More information can be found in the [Model Serving guide](../../../user_guides/mlops/serving/index.md).

docs/concepts/mlops/kserve.md

@@ -155,7 +155,7 @@ pointer-events: initial;
             <div class="rec_frame_main">
               <div class="text_and_icon">
                 <div class="svg_icon w-embed"><img alt="svgImg" src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHg9IjBweCIgeT0iMHB4Igp3aWR0aD0iNjQiIGhlaWdodD0iNjQiCnZpZXdCb3g9IjAgMCA1MTIgNTEyIgpzdHlsZT0iIGZpbGw6I3VuZGVmaW5lZDsiPjxwYXRoIGQ9Ik01MyA0MTUuNjQ1YTMwLjAzNCAzMC4wMzQgMCAwMDMwIDMwSDQyOWEzMC4wMzQgMzAuMDM0IDAgMDAzMC0zMFYxNjcuNTEzSDUzek0zMDIuNjY3IDI2My41MzdhMTAgMTAgMCAxMTE0LjAwOC0xNC4yNzZsNDQuMTM3IDQzLjMxYTEwIDEwIDAgMDEwIDE0LjI3NmwtNDQuMTM3IDQzLjMwOWExMCAxMCAwIDExLTE0LjAwOC0xNC4yNzZsMzYuODYyLTM2LjE3MXptLTgwLjkgMTA5LjVsMzguMjU3LTE1MC41YTEwIDEwIDAgMTExOS4zODMgNC45MjdsLTM4LjI1NyAxNTAuNWExMCAxMCAwIDAxLTE5LjM4My00LjkyN3ptLTc3LjA3NC04MC40NjVsNDQuMTM3LTQzLjMxYTEwIDEwIDAgMTExNC4wMDggMTQuMjc2bC0zNi44NjIgMzYuMTcyIDM2Ljg2MiAzNi4xNzFhMTAgMTAgMCAwMS0xNC4wMDggMTQuMjc2bC00NC4xMzctNDMuMzA5YTEwIDEwIDAgMDEwLTE0LjI3NnpNNDI5IDY2LjM1NUg4M2EzMC4wMzQgMzAuMDM0IDAgMDAtMzAgMzB2NTEuMTU3SDQ1OVY5Ni4zNTVBMzAuMDM0IDMwLjAzNCAwIDAwNDI5IDY2LjM1NXoiPjwvcGF0aD48L3N2Zz4="></div>
-                <div class="name_item_02"><a href="./concepts/projects/search/">Search</a>, <a href="./concepts/fs/feature_group/versioning/">Versioning</a>, <a href="./concepts/fs/feature_group/fg_statistics/">Statistics</a></div>
+                <div class="name_item_02"><a href="./concepts/projects/search/">Search</a>, <a href="./concepts/fs/feature_group/versioning/">Versioning</a>, <a href="./concepts/fs/feature_group/fg_statistics/">Statistics</a>, <a href="./concepts/fs/feature_group/feature_monitoring/">Monitoring</a></div>
               </div>
             </div>
             <div class="rec_frame_main">

docs/index.md

@@ -0,0 +1,96 @@
+# How to Select the API protocol for a Deployment
+
+## Introduction
+
+Hopsworks supports both REST and gRPC as API protocols for sending inference requests to model deployments. While REST API protocol is supported in all types of model deployments, support for gRPC is only available for models served with [KServe](predictor.md#serving-tool).
+
+!!! warning
+    At the moment, gRPC API protocol is only supported for **Python model deployments** (e.g., scikit-learn, xgboost, ...). Support for Tensorflow model deployments is coming soon.
+
+## GUI
+
+### Step 1: Create new deployment
+
+If you have at least one model already trained and saved in the Model Registry, navigate to the deployments page by clicking on the `Deployments` tab on the navigation menu on the left.
+
+<p align="center">
+  <figure>
+    <img src="../../../../assets/images/guides/mlops/serving/deployments_tab_sidebar.png" alt="Deployments navigation tab">
+    <figcaption>Deployments navigation tab</figcaption>
+  </figure>
+</p>
+
+Once in the deployments page, click on `New deployment` if there are not existing deployments or on `Create new deployment` at the top-right corner to open the deployment creation form.
+
+### Step 2: Go to advanced options
+
+A simplified creation form will appear including the most common deployment fields among all the configuration possible. Resource allocation is part of the advanced options of a deployment. To navigate to the advanced creation form, click on `Advanced options`.
+
+<p align="center">
+  <figure>
+    <img  style="max-width: 85%; margin: 0 auto" src="../../../../assets/images/guides/mlops/serving/deployment_simple_form_adv_options.png" alt="Advance options">
+    <figcaption>Advanced options. Go to advanced deployment creation form</figcaption>
+  </figure>
+</p>
+
+### Step 3: Select the API protocol
+
+Enabling gRPC as the API protocol for a model deployment requires KServe as the serving platform for the deployment. Make sure that KServe is enabled by activating the corresponding checkbox.
+
+<p align="center">
+  <figure>
+    <img src="../../../../assets/images/guides/mlops/serving/deployment_adv_form_kserve.png" alt="KServe enabled in advanced deployment form">
+    <figcaption>Enable KServe in the advanced deployment form</figcaption>
+  </figure>
+</p>
+
+Then, you can select the API protocol to be enabled in your model deployment.
+
+!!! note "Only one API protocol can be enabled simultaneously"
+    Currently, KServe model deployments are limited to one API protocol at a time. Therefore, only one of REST or gRPC API protocols can be enabled at the same time on the same model deployment.
+
+<p align="center">
+  <figure>
+    <img src="../../../../assets/images/guides/mlops/serving/deployment_grpc_select.png" alt="Select gRPC API protocol">
+    <figcaption>Select gRPC API protocol</figcaption>
+  </figure>
+</p>
+
+Once you are done with the changes, click on `Create new deployment` at the bottom of the page to create the deployment for your model.
+
+## Code
+
+### Step 1: Connect to Hopsworks
+
+```python
+import hopsworks
+
+project = hopsworks.login()
+
+# get Hopsworks Model Registry handle
+mr = project.get_model_registry()
+
+# get Hopsworks Model Serving handle
+ms = project.get_model_serving()
+```
+
+### Step 2: Create a deployment with a specific API protocol
+
+```python
+
+my_model = mr.get_model("my_model", version=1)
+
+my_predictor = ms.create_predictor(my_model,
+                                   api_protocol="GRPC"  # defaults to "REST"
+                                   )
+my_predictor.deploy()
+
+# or
+
+my_deployment = ms.create_deployment(my_predictor)
+my_deployment.save()
+```
+
+### API Reference
+
+[API Protocol](https://docs.hopsworks.ai/machine-learning-api/{{{ hopsworks_version }}}/generated/api/api-protocol/)

docs/user_guides/mlops/serving/api-protocol.md

@@ -72,6 +72,7 @@ You will be redirected to a full-page deployment creation form where you can see
     3. [Inference logger](#inference-logger)
     4. [Inference batcher](#inference-batcher)
     5. [Resources](#resources)
+    6. [API protocol](#api-protocol)
 
 Once you are done with the changes, click on `Create new deployment` at the bottom of the page to create the deployment for your model.
 
@@ -192,6 +193,10 @@ Inference batcher are deployment component that apply batching to the incoming i
 
 Resources include the number of replicas for the deployment as well as the resources (i.e., memory, CPU, GPU) to be allocated per replica. To learn about the different combinations available, see the [Resources Guide](resources.md).
 
+## API protocol
+
+Hopsworks supports both REST and gRPC as the API protocols to send inference requests to model deployments. To learn about REST and gRPC API protocols for model deployments, see the [API Protocol Guide](api-protocol.md).
+
 ## Conclusion
 
 In this guide you learned how to create a deployment.

docs/user_guides/mlops/serving/deployment.md

@@ -2,7 +2,7 @@
 
 ## Deployment
 
-Assuming you have already created a model in the Model Registry, a deployment can now be created to prepare a model artifact for this model and make it accessible for running predictions behind a REST endpoint. Follow the [Deployment Creation Guide](deployment.md) to create a Deployment for your model.
+Assuming you have already created a model in the Model Registry, a deployment can now be created to prepare a model artifact for this model and make it accessible for running predictions behind a REST or gRPC endpoint. Follow the [Deployment Creation Guide](deployment.md) to create a Deployment for your model.
 
 ### Predictor
 

docs/user_guides/mlops/serving/index.md

@@ -17,6 +17,7 @@ Predictors are the main component of deployments. They are responsible for runni
     5. [Inference Logger](#inference-logger)
     6. [Inference Batcher](#inference-batcher)
     7. [Resources](#resources)
+    8. [API protocol](#api-protocol)
 
 ## GUI
 
@@ -87,6 +88,7 @@ Additionally, you can adjust the default values of the rest of components:
     2. [Inference logger](#inference-logger)
     3. [Inference batcher](#inference-batcher)
     4. [Resources](#resources)
+    5. [API protocol](#api-protocol)
 
 Once you are done with the changes, click on `Create new deployment` at the bottom of the page to create the deployment for your model.
 
@@ -246,6 +248,10 @@ Inference batcher are deployment component that apply batching to the incoming i
 
 Resources include the number of replicas for the deployment as well as the resources (i.e., memory, CPU, GPU) to be allocated per replica. To learn about the different combinations available, see the [Resources Guide](resources.md).
 
+## API protocol
+
+Hopsworks supports both REST and gRPC as the API protocols to send inference requests to model deployments. To learn about REST and gRPC API protocols for model deployments, see the [API Protocol Guide](api-protocol.md).
+
 ## Conclusion
 
 In this guide you learned how to configure a predictor.

docs/user_guides/mlops/serving/predictor.md

@@ -192,6 +192,7 @@ nav:
               - Resource Allocation: user_guides/mlops/serving/resources.md
               - Inference Logger: user_guides/mlops/serving/inference-logger.md
               - Inference Batcher: user_guides/mlops/serving/inference-batcher.md
+              - API Protocol: user_guides/mlops/serving/api-protocol.md
               - Troubleshooting: user_guides/mlops/serving/troubleshooting.md
           - Vector Database: user_guides/mlops/vector_database/index.md
       - Migration:
@@ -356,6 +357,7 @@ markdown_extensions:
   - pymdownx.critic
   - attr_list
   - md_in_html
+  - def_list
   - toc:
       permalink: "#"
   - pymdownx.tasklist: