Skip to main content

Flower classification with XGBoost

In this example we'll deploy a simple XGBoost model to a REST API. We'll use the sample Iris dataset to create our model.

Before you begin, make sure you've cloned your Modelbit workspace.

Creating the deployment​

We'll call this deployment xgb_iris. Create the directory deployments/xgb_iris in your Modelbit repo. All files created in this tutorial will be under this directory.

We're going to create four files under deployments/xgb_iris/:

  • my_model.pkl: Our example model artifact. It'll be an XGBClassifier
  • source.py: The code we'll use to load and execute the model
  • requirements.txt: The list of pip packages needed in this deployment's environment
  • metadata.yaml: A configuration file that tells Modelbit how to run the deployment

Creating my_model.pkl​

Run the following script within deployments/xgb_iris. It trains and saves a simple classifier from the XGBoost getting started guide:

from xgboost import XGBClassifier
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
import pickle

data = load_iris()
X_train, X_test, y_train, y_test = train_test_split(data['data'], data['target'], test_size=.2)
bst = XGBClassifier(n_estimators=2, max_depth=2, learning_rate=1, objective='binary:logistic')
bst.fit(X_train, y_train)

with open("my_model.pkl", "wb") as f:
    pickle.dump(bst, f)

You can delete this script once my_model.pkl has been created.

info

For future reference, the features in the sample Iris dataset are 4 floats (sepal_length, sepal_width, petal_length, petal_width) with an target class of 0, 1, or 2 corresponding to the Setosa, Versicolor, and Virginica species.

Creating source.py​

This file contains the function that'll get called for each request to the API. By convention we'll call the main function the same name as the deployment, xgb_iris.

deployments/xgb_iris/source.py
import pickle

with open("my_model.pkl", "rb") as f:
    my_model = pickle.load(f)

flower_class_names = ['setosa', 'versicolor', 'virginica']

# main function
def xgb_iris(sepal_length: float, sepal_width: float, petal_length: float, petal_width: float):
    class_id = my_model.predict([[sepal_length, sepal_width, petal_length, petal_width]])[0]
    return {
        "class_id": class_id,
        "class_name": flower_class_names[class_id]
    }

# for local testing
if __name__ == "__main__":
    print(xgb_iris(4.9, 2.4, 3.3, 1.0))

This deployment's code loads my_model from its pickle file and then executes inferences using four input parameters. Running this file locally runs the test code at the bottom, outputting the following:

{ "class_id": 1, "class_name": "versicolor" }

Creating requirements.txt​

In order for Modelbit to run this deployment it needs to know the packages and versions to install. These requirements get built into a Docker image that'll run source.py. In this case we only need xgboost:

deployments/xgb_iris/requirements.txt
xgboost==2.0.3

Creating metadata.yaml:​

The last file is deployment a configuration file telling Modelbit how to create the API. In this case we need to specify the four input arguments, the owner of the deployment (that's you!), and the Python version to use:

deployments/xgb_iris/metadata.yaml
owner: you@company.com
runtimeInfo:
  mainFunction: xgb_iris
  mainFunctionArgs:
    - sepal_length:float
    - sepal_width:float
    - petal_length:float
    - petal_width:float
  pythonVersion: "3.10"
schemaVersion: 2
tip

Make sure to update the owner field to your email address.

To validate the format of this file, run modelbit validate. It'll print out errors if something looks wrong.

At this point we're ready to send this deployment to Modelbit!

Deploy to Modelbit​

Run the usual git commands to send these files to Modelbit:

git add .
git commit -m "creating xgb_iris deployment"
git push

You'll see output like the following:

Enumerating objects: 21, done.
Counting objects: 100% (20/20), done.
Delta compression using up to 16 threads
Compressing objects: 100% (8/8), done.
Writing objects: 100% (9/9), 1.77 KiB | 1.77 MiB/s, done.
Total 9 (delta 2), reused 0 (delta 0), pack-reused 0
remote:
remote:
remote: 1 deployment had changes. Modelbit is deploying these changes to production:
remote:   - xgb_iris: https://<YOUR_WORKSPACE>/main/deployments/xgb_iris/overview
remote:

Click the link to view your deployment in Modelbit.

Call the deployment​

You can call the deployment several different ways. Sample code with your specific endpoint URL is available in the API Endpoints tab of your deployment. They'll look like the following:

Using modelbit.get_inference in a Python environment:

import modelbit

modelbit.get_inference(
  deployment="xgb_iris",
  workspace="<YOUR_WORKSPACE>",
  region="<YOUR_REGION>",
  data=[4.9, 2.4, 3.3, 1.0])

# return value
{"data": {"class_id": 1, "class_name": "versicolor"}}

Batch inference​

The simplest way to perform batch predictions with this deployment is to use the batch inference syntax.

However, Modelbit also supports sending DataFrames to deployments. Check out the batch classification with XGBoost example to see how to recreate this deployment using DataFrame mode.