Estimated completion time: 11m.
This tutorial is relevant only for Kubernetes installation of Hydrosphere. Please refer to How to Install Hydrosphere on Kubernetes cluster.
In this tutorial, you will learn how to configure deployed Applications.
By the end of this tutorial you will know how to:
Train and upload an example model version
Create a Deployment Configuration
Create an Application from the uploaded model version with previously created deployment configuration
Examine settings of a Kubernetes cluster
In this section, we describe the resources required to create and upload an example model used in further sections. If you have no prior experience with uploading models to the Hydrosphere platform we suggest that you visit the Getting Started Tutorial.
Here are the resources used to train sklearn.ensemble.GradientBoostingClassifier and upload it to the Hydrosphere cluster.
requirements.txt is a list of Python dependencies used during the process of building model image.
serving.yaml is a resource definition that describes how model should be built and uploaded to Hydrosphere platform.
train.py is used to generate a model.joblib which is loaded from func_main.py during model serving.
Run python train.py to generate model.joblib
func_main.py is a script which serves requests and produces responses.
Our folder structure should look like this:
Do not forget to run python train.py to generate model.joblib!
After we have made sure that all files are placed correctly, we can upload the model to the Hydrosphere platform by running hs upload from the command line.
Next, we are going to create and upload an instance of Deployment Configuration to the Hydrosphere platform.
Deployment Configurations describe with which Kubernetes settings Hydrosphere should deploy servables. You can specify Pod Affinity and Tolerations, the number of desired pods in deployment, ResourceRequirements, and Environment Variables for the model container, and HorizontalPodAutoScaler settings.
Created Deployment Configurations can be attached to Servables and Model Variants inside of Application.
Deployment Configurations are immutable and cannot be changed after they've been uploaded to the Hydrosphere platform.
You can create and upload Deployment Configuration to Hydrosphere via YAML Resource definition or via Python SDK.
For this tutorial, we'll create a deployment configuration with 2 initial pods per deployment, HPA, and FOO environment variable with value bar.
Create the deployment configuration resource definition:
To upload it to the Hydrosphere platform, run:
Create the application resource definition:
To upload it to the Hydrosphere platform, run:
You can check whether with_replicas was successful by calling kubectl get deployment -A -o wide and checking the READYcolumn.
To check whether with_hpa was successful you should get a list of all created Horizontal Pod Autoscaler Resources. You can do so by calling kubectl get hpa -A
The output is similar to:
To list all environment variables run kubectl exec my-model-1-tumbling-star -it /bin/bash and then execute the printenv command which prints ann system variables.
The output is similar to:
Estimated Completion Time: 18m.
In this tutorial, you will learn how to create a custom anomaly detection metric for a specific use case.
Let's take a problem described in the previous tutorial as a use case and as a data source. We will monitor a model that classifies whether the income of a given person exceeds $50.000 per year.
By the end of this tutorial you will know how to:
Train a monitoring model
Deploy of a monitoring model with SDK
Manage сustom metrics with UI
Upload a monitoring model with CLI
For this tutorial, you need to have Hydrosphere Platform deployed and Hydrosphere CLI (hs) along with Python SDK (hydrosdk) _**_installed on your local machine. If you don't have them yet, please follow these guides first:
This tutorial is a sequel to the previous tutorial. Please complete it first to have a prepared dataset and a trained model deployed to the cluster:
We start with the steps we used for the common model. First, let's create a directory structure for our monitoring model with an /src folder containing an inference scriptfunc_main.py:
To make sure that our monitoring model will see the same data as our prediction model, we are going to apply the training data that was saved previously for our monitoring model.
This is what the distribution of our inliers looks like. By choosing a contamination parameter we can adjust a threshold that will separate inliers from outliers accordingly. You have to be thorough in choosing it to avoid critical prediction mistakes. Otherwise, you can also stay with 'auto'. To create a monitoring metric, we have to deploy that IsolationForest model as a separate model on the Hydrosphere platform. Let's save a trained model for serving.
First, let's create a new directory where we will store our inference script with declared serving function and its definitions. Put the following code inside the src/func_main.py file:
Next, we need to install the necessary libraries. Create a requirements.txt and add the following libraries to it:
Just like with common models, we can use SDK to upload our monitoring model and bind it to the trained one. The steps are almost the same, but with some slight differences. First, since we want to predict the anomaly score instead of sample class, we need to change the type of output field from 'int64' to 'float64'.
Secondly, we need to apply a couple of new methods to create a metric. MetricSpec is responsible for creating a metric for a specific model, with specific MetricSpecConfig.
Go to the UI to observe and manage all your models. Here you will find 3 models on the left panel:
adult_monitoring_model - our monitoring model
adult_model_metric - a model that was created by Automatic Outlier Detection
During the prediction, you will get anomaly scores for each sample in the form of a chart with two lines. The curved line shows scores, while the horizontal dotted one is our threshold. When the curve intersects the threshold, it might be a sign of potential anomalousness. However, this is not always the case, since there are many factors that might affect this, so be careful about your final interpretation.
Just like in the case with all other types of models, we can define and upload a monitoring model using a resource definition. We have to pack our model with a model definition, like in the previous tutorial.
Inputs of this model are the inputs of the target monitored model plus the outputs of that model. We will use the value field as an output for the monitoring model. The final directory structure should look like this:
From that folder, upload the model to the cluster:
Now we have to attach the deployed Monitoring model as a custom metric. Let's create a monitoring metric for our pre-deployed classification model in the UI:
From the Models section, select the target model you would like to deploy and select the desired model version.
Open the Monitoring tab.
At the bottom of the page click the Configure Metric button.
From the opened window click the Add Metric button.
Specify the name of the metric.
Choose the monitoring model.
Choose the version of the monitoring model.
Select a comparison operator Greater. This means that if you have a metric value greater than a specified threshold, an alarm should be fired.
Set the threshold value. In this case, it should be equal to the value of monitoring_model.threshold_.
Click the Add Metric button.
That's it. Now you have a monitored income classifier deployed on the Hydrosphere platform.
As a monitoring metric, we will use IsolationForest. You can learn how it works in its .
Anomaly scores are obtained through inside the Hydrosphere's engine after making a Servable, so you don't need to perform any additional manipulations.
adult_model - a model that we trained for prediction in the
Click on the trained model and then on Monitoring. On the monitoring dasboard you now have two external metrics: the first one is auto_od_metric that was automatically generated by , and the new one is custom_metric that we have just created. You can also change settings for existing metrics and configure the new ones in the Configure Metrics section:
Monitoring can be used to track the behavior of external models running outside of the Hydrosphere platform. This tutorial describes how to register an external model, trigger analysis over your requests, and retrieve results.
By the end of this tutorial you will know how to:
Register a model
Upload training data
Assign custom metrics
Invoke analysis
Retrieve metrics
For this tutorial, you need to have Hydrosphere Platform deployed on your local machine with Sonar component enabled. If you don't have it yet, please follow this guide first:
You also need a running external model, capable of producing predictions. Inputs and outputs of that model will be fed into Hydrosphere for monitoring purposes.
First, you have to register an external model. To do that, submit a JSON document, defining your model.
This section describes the structure of the JSON document used to register external models within the platform.
The document must contain the following top-level members, describing the interface of your model:
name: the name of the registered model. This name uniquely identifies a collection of model versions, registered within the Hydrosphere platform.
contract: the interface of the registered model. This member describes inputs and outputs of the model, as well as other complementary metadata, such as model signature, and data profile for each field.
A document may contain additional top-level members, describing other details of your model.
metadata: the metadata of the registered model. The structure of the object is not strictly defined. The only constraint is that the object must have a key-value structure, where a value can only be of a simple data type (string, number, boolean).
monitoringConfiguration: monitoring configuration to be used for this model.
This example shows, how a model can be defined at the top level:
monitoringConfiguration object defines a monitoring configuration to be used for the model version. The object must contain the following members:
batchSize: size of the batch to be used for aggregations.
The example below shows how a monitoringConfiguration object can be defined.
Thecontract object appears in the document to define the interface of the model. The contract object must contain the following members:
modelName: the original name of the model. It should be the same as the name of the registered model, defined on the level above;
predict: the signature of the model. It defines the inputs and the outputs of the model.
The example below shows how a contract object can be defined.
predict object describes the signature of the model. The signature object must contain the following members:
signatureName: The signature of the model, used to process the request;
inputs: A collection of fields, defining the inputs of the model. Each item in the collection describes a single data entry, its type, shape, and profile. A collection must contain at least one item;
outputs: A collection of fields, defining the outputs of the model. Each item in the collection describes a single data entry, its type, shape, and profile. A collection must contain at least one item.
The example below shows how a predict object can be defined.
Items in the inputs / outputs collections are collectively called "fields". The field object must contain the following members:
name: Name of the field;
dtype: Data type of the field.
profile: Data profile of the field.
shape: Shape of the field.
The only valid options for dtype are:
DT_STRING;
DT_BOOL;
DT_VARIANT;
DT_HALF;
DT_FLOAT;
DT_DOUBLE;
DT_INT8;
DT_INT16;
DT_INT32;
DT_INT64;
DT_UINT8;
DT_UINT16;
DT_UINT32;
DT_UINT64;
DT_QINT8;
DT_QINT16;
DT_QINT32;
DT_QUINT8;
DT_QUINT16;
DT_COMPLEX64;
DT_COMPLEX128;
The only valid options for profile are:
NONE
NUMERICAL
TEXT
IMAGE
The example below shows how a single field object can be defined.
shape object defines the shape of the data that the model is processing. The shape object must contain the following members:
dim: A collection of items, describing each dimension. A collection may be empty — in that case, the tensor will be interpreted as a scalar value.
unknownRank: Boolean value. Identifies whether the defined shape is of unknown rank.
The example below shows how a shape object can be defined.
dim object defines a dimension of the field. The dim object must contain the following members:
size: Size of the dimension.
name: Name of the dimension.
The example below shows how a dim object can be defined.
A model can be registered by sending a POST request to the /api/v2/externalmodel endpoint. The request must include a model definition as primary data.
The request below shows an example of an external model registration.
As a response, the server will return a JSON object with complementary metadata, identifying a registered model version.
The response object from the external model registration request contains the following fields:
id: Model version ID, uniquely identifying a registered model version within Hydrosphere platform;
model: An object, representing a model collection, registered in Hydrosphere platform;
modelVersion: Model version number in the model collection;
modelContract: Contract of the model, similar to the one defined in the request section above;
metadata: Metadata of the model, similar to the one defined in the request section above;
monitoringConfiguration: MonitoringConfiguration of the model, similar to the one defined in the request section above;
created: Timestamp, indicating when the model was registered.
Note theid field. It will be referred as MODEL_VERSION_ID later throughout the article.
model object represents a collection of model versions, registered in the platform. The response model object contains the following fields:
id: ID of the model collection;
name: Name of the model collection.
The example below shows, a sample server response from an external model registration request.
To let Hydrosphere calculate the metrics of your requests, you have to submit the training data. You can do so by:
In each case your training data should be represented as a CSV document, containing fields named exactly as in the interface of your model.
Currently, we support uploading training data as .csv files and utilizing it for NUMERICAL, CATEGORICAL, and TEXT profiles only.
Switch to the cluster, suitable for your current flow.
If you don't have a defined cluster yet, create one using the following command.
Make sure you have a local copy of the training data that you want to submit.
Submit the training data. You must specify two parameters:
--model-version: A string indicating the model version to which you want to submit the data. The string should be formatted in the following way <model-name>:<model-version>;
--filename: Path to a filename, that you want to submit.
If you already have your training data uploaded to S3, you can specify a path to that object URI using --s3path parameter instead of --filename. The object behind this URI should be available to the Hydrosphere instance.
Depending on the size of your data, you will have to wait for the data to be uploaded. If you don't want to wait, you can use the --async flag.
To upload your data using an HTTP endpoint, stream it to the /monitoring/profiles/batch/<MODEL_VERSION_ID> endpoint.
In the code snippets below you can see how data can be uploaded using sample HTTP clients.
You can acquire MODEL_VERSION_ID by sending a GET request to /model/version/<MODEL_NAME>/<MODEL_VERSION> endpoint. The response document will have a similar structure, already defined @refabove.
This step is optional. If you wish to assign a custom monitoring metric to a model, you can do it by:
using Hydrosphere UI
using HTTP endpoint
To find out how to assign metrics using Hydrosphere UI, refer to this page.
To assign metrics using HTTP endpoint, you will have to submit a JSON document, defining a monitoring specification.
The document must contain the following top-level members.
name: The name of the monitoring metric;
modelVersionId: Unique identifier of the model to which you want to assign a metric;
config: Object, representing a configuration of the metric, which will be applied to the model.
The example below shows how a metric can be defined on the top level.
config object defines a configuration of the monitoring metric that will monitor the model. The model must contain the following members:
modelVersionId: Unique identifier of the model that will monitor requests;
threshold: Threshold value, against which monitoring values will be compared using a comparison operator;
thresholdCmpOperator: Object, representing a comparison operator.
The example below shows, how a metric can be defined on a top-level.
thresholdCmpOperator object defines the kind of comparison operator that will be used when comparing a value produced by the metric against the threshold. The object must contain the following members:
kind: Kind of comparison operator.
The only valid options for kind are:
Eq;
NotEq;
Greater;
Less;
GreaterEq;
LessEq.
The example below shows, how a metric can be defined on the top level.
The request below shows an example of assigning a monitoring metric. At this moment, both monitoring and the actual prediction model should be registered/uploaded to the platform.
To send a request for analysis you have to use gRPC endpoint. We have already predefined ProtoBuf messages for the reference.
Create an ExecutionMetadata message that contains metadata information of the model, used to process a given request:
Create a PredictRequest message that contains the original request passed to the serving model for the prediction:
Create a PredictResponse message that contains inferenced output of the model:
Assemble an ExecutionInformation from the above-created messages.
Submit ExecutionInformation proto to Sonar for analysis. Use the RPC Analyse method of the MonitoringService to calculate metrics.
In the code snippets below you can see how analysis can be triggered with sample gRPC clients.
Once triggered, the analyze method does not return anything. To fetch calculated metrics from the model version, you have to make a GET request to the /monitoring/checks/all/<MODEL_VERSION_ID> endpoint.
A request must contain the following parameters:
limit: how many requests to fetch;
offset: which offset to make from the beginning.
An example request is shown below.
Calculated metrics have a dynamic structure, which is dependant on the model interface.
A response object contains the original data submitted for prediction, the model's response, calculated metrics and other supplementary metadata. Every field produced by Hydrosphere is prefixed with _hs_ char.
_id: ID of the request, generated internally by Hydrosphere;
_hs_request_id: ID of the request, specified by user;
_hs_model_name: Name of the model that processed a request;
_hs_model_incremental_version: Version of the model that processed a request;
_hs_model_version_id: ID of the model version, which processed a request;
_hs_raw_checks: Raw checks calculated by Hydrosphere based on the training data;
_hs_metric_checks: Metrics produced by monitoring models;
_hs_latency: Latency, indicating how much it took to process a request;
_hs_error: Error message that occurred during request processing;
_hs_score: The number of all successful checks divided by the number of all checks;
_hs_overall_score: The amount of all successful metric values (not exceeding a specified threshold), divided by the amount of all metric values;
_hs_timestamp: Timestamp in nanoseconds, when the object was generated;
_hs_year: Year when the object was generated;
_hs_month: Month when the object was generated;
_hs_day: Day when the object was generated;
Apart from the fields defined above, each object will have additional fields specific to the particular model version and its interface.
_hs_<field_name>_score: The number of all successful checks calculated for this specific field divided by the total number of all checks calculated for this specific field;
<field_name>: The value of the field.
_hs_raw_checks object contains all fields, for which checks have been calculated.
The example below shows, how the _hs_raw_checks_ object can be defined.
check object declares the check, that has been calculated for the particular field. The following members will be present in the object.
check: Boolean value indicating, whether the check has been passed;
description: Description of the check that has been calculated;
threshold: Threshold of the check;
value: Value of the field;
metricSpecId: Metric specification ID. For each check object this value will be set to null.
The example below shows, how the check object can be defined.
_hs_metrics_checks object contains all fields for which metrics have been calculated.
The example below shows how the _hs_metrics_checks object can be defined.
metric object declares the metric, that has been calculated for the particular field. The following members will be present in the object.
check: Boolean value indicating, whether the metric has not been fired;
description: Name of the metric that has been calculated;
threshold: Threshold of the metric;
value: Value of the metric;
metricSpecId: Metric specification ID.
The example below shows how the metric object can be defined.
The example below shows a fully composed server response.
This section contains tutorials to help you get started with the Hydrosphere platform. A tutorial shows how to accomplish a goal rather than a single basic task.
Typically, a tutorial has several sections. When a tutorial section has several pieces of code to illustrate it, they can be shown as a group of tabs that you can switch between.
For guides on performing more basic technical steps, please look in the How-To section:
Estimated completion time: 14 min.
In this tutorial, you will learn how to retrospectively compare the behavior of two different models.
By the end of this tutorial you will know how to:
Set up an A/B application
Analyze production data
We train and upload our model with 5 components as movie_rec:v1
Next, we train and upload a new version of our original model with 20 components as movie_rec:v2
We can check that we have multiple versions of our model by running:
To create an A/B deployment we need to create an Application with a single execution stage consisting of two model variants. These model variants are our Model A and Model B correspondingly.
The following code will create such an application:
movie-ab-appWe'll simulate production data flow by repeatedly asking our model for recommendations.
Each request-response pair is stored in S3 (or in minio if deployed locally) in parquet files. We'll use fastparquet package to read these files and use s3fs package to connect to S3.
The only file in the feature-lake folder is ['feature-lake/movie_rec']. Data stored in S3 is stored under the following path: feature-lake/MODEL_NAME/MODEL_VERSION/YEAR/MONTH/DAY/*.parquet
Now that we have loaded the data, we can start analyzing it.
To compare differences between model versions we'll use two metrics:
Latency - we compare the time delay between the request received and the response produced.
Mean Top-3 Hit Rate - we compare recommendations to those the user has rated. If they match then increase the hit rate by 1. Do this for the complete test set to get the hit rate.
Let's calculate the 95th percentile of our latency distributions per model version and plot them. Latencies are stored in the _hs_latency column in our dataframes.
In our case, the output was 13.0ms against 12.0ms. Results may differ.
Furthermore, we can visualize our data. To plot latency distribution we'll use the Matplotlib library.
Next, we'll calculate hit rates. To do so, we need new labeled data. For recommender systems, this data is usually available after a user has clicked\watched\liked\rated the item we've recommended to him. We'll use the test part of movielens as labeled data.
To measure how well our models were recommending movies we'll use a hit rate metric. It calculates how many movies users have watched and rated with 4 or 5 out of 3 movies recommended to him.
In our case the mean_hit_rate variable is {'v1': 0.137, 'v2': 0.141} . Which means that the second model version is better in terms of hit rate.
You have successfully completed the tutorial! 🚀
Now you know how to read and analyze automatically stored data.
In this tutorial, you will learn how to train and deploy a model for a classification task based on the Adult Dataset. The main steps of this process are data preparation, training a model, uploading a model to the cluster, and making a prediction on test samples.
By the end of this tutorial you will know how to:
Prepare data
Train a model
Deploy a model with SDK
Explore models via UI
Deploy a model with CLI and resource definition
For this tutorial, you need to have Hydrosphere Platform deployed and Hydrosphere CLI (hs) along with Python SDK (hydrosdk) _**_installed on your local machine. If you don't have them yet, please follow these guides first:
For this tutorial, you can use a local cluster. To ensure that, run hs cluster in your terminal. This command will show the name and server address of a cluster you’re currently using. If it shows that you're not using a local cluster, you can configure one with the following commands:
Model training always requires some amount of initial preparation, most of which is data preparation. The Adult Dataset consists of 14 descriptors, 5 of which are numerical and 9 categorical, including the class column.
Categorical features are usually presented as strings. This is not an appropriate data type for sending it into a model, so we need to transform it first. We can remove rows that contain question marks in some samples. Once the preprocessing is complete, you can delete the DataFrame (df):
There are many classifiers that you can potentially use for this step. In this example, we’ll apply the Random Forest classifier. After preprocessing, the dataset will be separated into train and test subsets. The test set will be used to check whether our deployed model can process requests on the cluster. After the training step, we can save a model with joblib.dump() in a model/ model folder.
The easiest way to upload a model to your cluster is by using Hydrosphere SDK. SDK allows Python developers to configure and manage the model lifecycle on the Hydrosphere platform. Before uploading a model, you need to connect to your cluster:
Next, we need to create an inference script to be uploaded to the Hydrosphere platform. This script will be executed each time you are instantiating a model servable. Let's name our function file func_main.py and store it in the src folder inside the directory where your model is stored. Your directory structure should look like this:
The code in the func_main.py should be as follows:
It’s important to make sure that variables will be in the right order after we transform our dictionary for a prediction. So in cols we preserve column names as a list sorted by order of their appearance in the DataFrame.
To start working with the model in a cluster, we need to install the necessary libraries used in func_main.py. Create a requirements.txt in the folder with your model and add the following libraries to it:
After this, your model directory with all necessary dependencies should look as follows:
Now we are ready to upload our model to the cluster.
Hydrosphere Serving has a strictly typed inference engine, so before uploading our model we need to specify it’s signature withSignatureBuilder. A signature contains information about which method inside the func_main.py should be called, as well as shapes and types of its inputs and outputs.
Use X.dtypes to check what types of data you have for each column. You can use int64 fields for all variables including income, which is our dependent variable and we can name it as 'y' in a signature for further prediction.
Besides, you can specify the type of profiling for each variable using ProfilingType so Hydrosphere could know what this variable is about and analyze it accordingly. For this purpose, we can create a dictionary, which could contain keys as our variables and values as our profiling types. Otherwise, you can describe them one by one as a parameter in the input.
Finally, we can complete our signature with the .build() method.
Next, we need to specify which files will be uploaded to the cluster. We use path to define the root model folder and payload to point out paths to all files that we need to upload.
At this point, we can combine all our efforts into the LocalModel object. LocalModels are models before they get uploaded to the cluster. They contain all the information required to instantiate a ModelVersion in a Hydrosphere cluster. We’ll name this model adult_model.
Additionally, we need to specify the environment in which our model will run. Such environments are called Runtimes. In this tutorial, we will use the default Python 3.7 runtime. This runtime uses the src/func_main.py script as an entry point, which is the reason we organized our files the way we did.
One more parameter that you can define is a path to the training data of your model, required if you want to utilize additional services of Hydrosphere (for example, Automatic Outlier Detection).
Now we are ready to upload our model to the cluster. This process consists of several steps:
Once LocalModel is prepared we can apply the upload method to upload it.
Then we can lock any interaction with the model until it will be successfully uploaded.
ModelVersion helps to check whether our model was successfully uploaded to the platform by looking for it.
To deploy a model you should create an Application - a linear pipeline of ModelVersions with monitoring and other benefits. Applications provide Predictor objects, which should be used for data inference purposes.
Predictors provide a predict method which we can use to send our data to the model. We can try to make predictions for our test set that has preliminarily been converted to a list of dictionaries. You can check the results using the name you have used for an output of Signature and preserve it in any format you would prefer. Before making a prediction don't forget to make a small pause to finish all necessary loadings.
If you want to interact with your model via Hydrosphere UI, you can go to http://localhost. Here you can find all your models. Click on a model to view information about it: versions, building logs, created applications, model's environments, and other services associated with deployed models.
You might notice that after some time there appears an additional model with the metric postscript at the end of the name. This is your automatically formed monitoring model for outlier detection. Learn more about the Automatic Outlier Detection feature here.
🎉 You have successfully finished this tutorial! 🎉
Next, you can:
Go to the next tutorial and learn how to create a custom Monitoring Metric and attach it to your deployed model:
Explore the extended part of this tutorial to learn how to use YAML resource definitions to upload a ModelVersion and create an Application.
Another way to upload your model is to apply a resource definition. This process repeats all the previous steps like data preparation and training. The difference is that instead of SDK, we are using CLI to apply a resource definition.
A resource definition is a file that defines the inputs and outputs of a model, a signature function, and some other metadata required for serving. Go to the root directory of the model and create a serving.yaml file. You should get the following file structure:
Model deployment with a resource definition repeats all the steps of that with SDK, but in one file. A considerable advantage of using a resource definition is that besides describing your model it allows creating an application by simply adding an object to the contract after the separation line at the bottom. Just name your application and provide the name and version of a model you want to tie to it.
To start uploading, run hs apply -f serving.yaml. To monitor your model you can use Hydrosphere UI as was previously shown.
