Explaining Object Detection model with Amazon SageMaker Clarify

This notebook's CI test result for us-west-2 is as follows. CI test results in other regions can be found at the end of the notebook.

In this notebook, we deploy a pre-trained image detection model to showcase how you can use Amazon SagemaMaker Clarify explainability features for Computer Vision, specifically for object detection models including your own ones.

1. We first import a model from the Gluon model zoo locally on the notebook, that we then compress and send to S3
2. We then use the SageMaker MXNet Serving feature to deploy the model to a managed SageMaker endpoint. It uses the model artifact that we previously loaded to S3.
3. We query the endpoint and visualize detection results
4. We explain the predictions of the model using Amazon SageMaker Clarify.

This notebook can be run with the conda_python3 Kernel.

More on Amazon SageMaker Clarify:

Amazon SageMaker Clarify helps improve your machine learning models by detecting potential bias and helping explain how these models make predictions. The fairness and explainability functionality provided by SageMaker Clarify takes a step towards enabling AWS customers to build trustworthy and understandable machine learning models. The product comes with the tools to help you with the following tasks.

Measure biases that can occur during each stage of the ML lifecycle (data collection, model training and tuning, and monitoring of ML models deployed for inference). Generate model governance reports targeting risk and compliance teams and external regulators. Provide explanations of the data, models, and monitoring used to assess predictions for input containing data of various modalities like numerical data, categorical data, text, and images. Learn more about SageMaker Clarify here: https://aws.amazon.com/sagemaker/clarify/.

More on Gluon and Gluon CV:

• Gluon is the imperative python front-end of the Apache MXNet deep learning framework. Gluon notably features specialized toolkits helping reproducing state-of-the-art architectures: Gluon-CV, Gluon-NLP, Gluon-TS. Gluon also features a number of excellent end-to-end tutorials mixing science with code such as D2L.ai and The Straight Dope
• Gluon-CV is an efficient computer vision toolkit written on top of Gluon and MXNet aiming to make state-of-the-art vision research reproducible.

This sample is provided for demonstration purposes, make sure to conduct appropriate testing if derivating this code for your own use-cases!

Index:

1. Test a pre-trained detection model, locally
2. Instantiate model
3. Create endpoint and get predictions (optional)
4. Run Clarify and interpret predictions

Let's start by installing the latest version of the SageMaker Python SDK, boto, and AWS CLI.

Constants

Test a pre-trained detection model, locally

Gluon model zoo contains a variety of models. In this demo we use a YoloV3 detection model (Redmon et Farhadi). More about YoloV3:

• Paper https://pjreddie.com/media/files/papers/YOLOv3.pdf
• Website https://pjreddie.com/darknet/yolo/

Gluon CV model zoo contains a number of architectures with different tradeoffs in terms of speed and accuracy. If you are looking for speed or accuracy, don't hesitate to change the model

The model we downloaded above is trained on the COCO dataset and can detect 80 classes. In this demo, we restrict the model to detect only specific classes of interest. This idea is derived from the official Gluon CV tutorial: https://gluon-cv.mxnet.io/build/examples_detection/skip_fintune.html

COCO contains the following classes:

Get RGB images from the Caltech 256 dataset [Griffin, G. Holub, AD. Perona, P. The Caltech 256. Caltech Technical Report.]

Test locally

gluoncv comes with built-in pre-processing logic for popular detectors, including YoloV3:

https://gluon-cv.mxnet.io/_modules/gluoncv/data/transforms/presets/yolo.html

https://gluon-cv.mxnet.io/build/examples_detection/demo_yolo.html

Let's see how the network computes detections in a single image, we have to first resize and reshape, since the original image is loaded with channels in the last dimension and MXNet will expect a shape of (num_batches, channels, width, height)

The network returns 3 tensors: class_ids, scores and bounding boxes. The default is up to 100 detections, so we get tensor with shape (num batches, detections, ...) where the last dimension is 4 for the bounding boxes as we have upper right corner, and lower right corner coordinates.

Deploy the detection server

1. We first need to send the model to S3, as we will provide the S3 model path to Amazon SageMaker endpoint creation API
2. We create a serving script containing model deserialization code and inference logic. This logic is in the repo folder.
3. We deploy the endpoint with a SageMaker SDK call

Save local model, compress and send to S3

Clarify needs a model since it will spin up its own inference endpoint to get explanations. We will now export the local model, archieve it and then create a SageMaker model from this archieve which allows to create other resources that depend on this model.

Instantiate model

We use batching of images on the predictor entry_point in order to achieve higher performance as utilization of resources is better than one image at a time.

(Optional) Create endpoint and get predictions, model IO in depth

In this optional section we deploy an endpoint to get predictions and dive deep into details that can be helpful to troubleshot issues related to expected model IO format of predictions, serialization and tensor shapes.

Common pitfalls are usually solved by making sure we are using the right serializer and deserializer and that the model output conforms to the expectations of Clarify in terms of shapes and semantics of the output tensors.

In general, Clarify expectes that our model receieves a batch of images and outputs a batch of image detections with a tensor having the following elements: class id, prediction score and normalized bounding box of the detection.

Delete any previous enpoint

Delete any stale endpoint config

Deploy the model in a SageMaker endpoint

Let's go in detail on how the detection server works, let's take the following test image as an example:

Since we overrode the transform_fn making it support batches and normalizing the detection boxes, we feed a tensor with a single batch, H, W and the 3 color channels as input

Send the image to the predictor and get detections

Our prediction has one batch, 3 detections and 6 elements containing class_id, score and normalized box with upper left corner, and lower left corner.

To display the detections we undo the normalization and split the detection format that clarify uses so we use the gluon plot_bbox function with the non-normalized boxes and separate scores and class ids from detections

We can group the logic above in a function to make it more convenient to use

There's a single detection of a dog which is class index 0 as in the beginning of the notebook where we called reset_class

Amazon Sagemaker Clarify

We will now showcase how to use SageMaker Clarify to explain detections by the model, for that we have already done some work in detection_server_batch.py to filter out missing detections with index -1 and we have normalized the boxes to the image dimensions. We only need to upload the data to s3, provide the configuration for Clarify in the analysis_config.json describing the explainability job parameters and execute the processing job with the data and configuration as inputs. As a result, we will get in S3 the explanation for the detections of the model.

Clarify expects detections to be in the format explored in the cells above. Detections should come in a tensor of shape (num_images, batch, detections, 6). The first number of each detection is the predicted class label. The second number is the associated confidence score for the detection. The last four numbers represent the bounding box coordinates [xmin / w, ymin / h, xmax / w, ymax / h]. These output bounding box corner indices are normalized by the overall image size dimensions, where w is the width of the image, and h is the height.

Upload some test images to get explanations

We use this noise image as a baseline to mask different segments of the image during the explainability process

It's very important that predictor.content_type and predictor.accept_type in the json fields below match the sagemaker python sdk predictor.serializer and predictor.deserializer class instances above such as sagemaker.serializers.NumpySerializer so Clarify job can use the right (de)serializer.

Clarify job configuration for object detection type of models

We will configure important parameters of the Clarify job for object detection under image_config:

• num_samples: This number determines the size of the generated synthetic dataset to compute the SHAP values. More samples will produce more accurate explanations but will consume more computational resources
• baseline: image that will be used to mask segments during Kernel SHAP
• num_segments: number of segments to partition the detection image into
• max_objects: maximum number of objects starting from the first that will be considered sorted by predicted score
• iou_threshold: minimum IOU for considering predictions against the original detections, as detection boxes will shift during masking
• context: whether to mask the image background when running SHAP, takes values 0 or 1

Below we use the Sagemaker Python SDK which helps create an Analysis configuration but using higher level Python classes.

Configure parameters of the Clarify Processing job. The job has one input, the config file and one output, the resulting analysis of the model.

Now run the processing job, it will take approximately 6 minutes.

We download the results of the Clarify job and inspect the attributions

Cleanup of resources

We delete the previous endpoint

Notebook CI Test Results

This notebook was tested in multiple regions. The test results are as follows, except for us-west-2 which is shown at the top of the notebook.