Implementation:Pytorch Serve XGBoost Iris Handler

Overview

XGBoost_Iris_Handler implements a TorchServe handler for serving an XGBoost Iris classifier. The XGBIrisHandler class extends BaseHandler, providing model initialization with XGBClassifier loading and label mapping, CSV-to-numpy preprocessing, XGBoost prediction inference, and label postprocessing. This demonstrates TorchServe's capability to serve non-PyTorch models.

Field	Value
Page Type	Implementation
Implementation Type	API Doc
Domains	Non_PyTorch_Serving, Classification
Knowledge Sources	Pytorch_Serve
Workflow	Non_PyTorch_Model_Deployment
Last Updated	2026-02-13 18:52 GMT

Description

The XGBIrisHandler demonstrates how TorchServe can serve models beyond the PyTorch ecosystem. By extending BaseHandler and overriding the core pipeline methods, it integrates XGBoost's XGBClassifier into TorchServe's standard inference workflow. The handler loads a pre-trained XGBoost model, accepts CSV-formatted input data, converts it to numpy arrays for prediction, and maps numeric class indices back to Iris species labels.

Key Responsibilities

• Model Loading: Loads a pre-trained XGBClassifier model file and sets up label mapping for Iris species
• CSV Parsing: Converts incoming CSV-formatted request data into numpy arrays suitable for XGBoost
• XGBoost Inference: Calls XGBClassifier.predict() instead of PyTorch's forward pass
• Label Mapping: Maps numeric predictions (0, 1, 2) to Iris species names (setosa, versicolor, virginica)

Code Reference

Source Location

File	Lines	Repository
examples/xgboost_classfication/xgboost_iris_handler.py	L1-54	pytorch/serve

Signature

class XGBIrisHandler(BaseHandler):
    """
    TorchServe handler for XGBoost Iris classification.

    Serves an XGBClassifier model through TorchServe's
    standard handler interface.
    """

    def initialize(self, context):
        """
        Load XGBClassifier model and configure label mapping.

        Loads the pre-trained XGBoost model from the model directory
        and sets up the mapping from numeric class indices to
        Iris species names.

        Args:
            context: TorchServe context with system_properties
                     containing model_dir path.
        """
        ...

    def preprocess(self, data):
        """
        Convert CSV input data to numpy array.

        Parses the request body as CSV-formatted data and converts
        it to a numpy array suitable for XGBoost prediction.

        Args:
            data (list): List of request input dictionaries.

        Returns:
            numpy.ndarray: Feature array for XGBoost prediction.
        """
        ...

    def inference(self, data, *args, **kwargs):
        """
        Run XGBoost prediction on preprocessed data.

        Calls XGBClassifier.predict() on the numpy input array.

        Args:
            data (numpy.ndarray): Feature array from preprocess.

        Returns:
            numpy.ndarray: Predicted class indices.
        """
        ...

    def postprocess(self, data):
        """
        Map predicted class indices to Iris species labels.

        Converts numeric predictions to human-readable
        species names using the label mapping.

        Args:
            data (numpy.ndarray): Predicted class indices.

        Returns:
            list: Iris species label strings.
        """
        ...

Import

from xgboost_iris_handler import XGBIrisHandler

# External dependencies:
import numpy as np
from xgboost import XGBClassifier
from ts.torch_handler.base_handler import BaseHandler

I/O Contract

Method	Input	Output	Notes
initialize(context)	context: TorchServe Context	None (sets self.model, label mapping)	Loads XGBClassifier and species label map
preprocess(data)	data: list of request dicts with CSV body	numpy.ndarray: feature array	Parses CSV to numpy; expects 4 features (sepal/petal length/width)
inference(data)	data: numpy.ndarray	numpy.ndarray: predicted class indices	Calls XGBClassifier.predict()
postprocess(data)	data: numpy.ndarray class indices	list: species label strings	Maps 0/1/2 to setosa/versicolor/virginica

Request Format

5.1,3.5,1.4,0.2

The four values correspond to sepal length, sepal width, petal length, and petal width.

Usage Examples

Example 1: Model Archive Creation

# Create model archive for XGBoost Iris classifier
torch-model-archiver --model-name xgboost_iris \
    --version 1.0 \
    --serialized-file xgboost_iris.model \
    --handler xgboost_iris_handler.py \
    --extra-files "index_to_name.json"

Example 2: Inference Request

# Send a classification request with Iris features
curl -X POST http://localhost:8080/predictions/xgboost_iris \
    -H "Content-Type: text/plain" \
    -d "5.1,3.5,1.4,0.2"

# Expected response: ["setosa"]

Example 3: Handler Pipeline Flow

# The handler follows the standard TorchServe pipeline:

# 1. initialize: Load XGBClassifier
model = XGBClassifier()
model.load_model("xgboost_iris.model")
label_map = {0: "setosa", 1: "versicolor", 2: "virginica"}

# 2. preprocess: CSV to numpy
features = np.array([[5.1, 3.5, 1.4, 0.2]])

# 3. inference: XGBoost predict
predictions = model.predict(features)  # [0]

# 4. postprocess: Map to labels
result = [label_map[p] for p in predictions]  # ["setosa"]

Related Pages

• Principle:Pytorch_Serve_Non_PyTorch_Model_Serving - The principle for serving non-PyTorch models through TorchServe
• Implementation:Pytorch_Serve_BaseHandler - Base handler class that XGBIrisHandler extends
• Implementation:Pytorch_Serve_Generate_Model_Archive - Packages the handler into a .mar archive
• Implementation:Pytorch_Serve_Service_Predict - The Service.predict() method that invokes handle()