Version: 1.3.12

Predict API Reference

This document provides a detailed description of the API expected by Certifai when scanning models deployed as a prediction service.

Predict API: Request/Response

The predict endpoint takes either an array of instances or a single instance, containing an array of feature values.

curl -X POST \
http://localhost:5111/<route> \
-H 'Content-Type: application/json' \
-d '{
"payload": { "instances": [[7,107,74,0,0,29.6,0.254,31]] }
}'

Where:

route is the endpoint path (e.g. diabetes_dtree/predict).

The predict endpoint returns an array of predictions and/or scores with predicted values for each input row in the same order.

Example predict request with a single instance

curl -X POST \
http://localhost:5111/bank_marketing_logit/predict \
-H 'Content-Type: application/json' \
-d '{
"payload": {
"instances": [[
"age_25_or_above",
"job_admin.",
"marital_married",
"education_secondary",
"default_no",
2343,
"housing_yes",
"loan_no",
"contact_unknown",
"month_may",
1042,
1,
-1,
0,
"poutcome_unknown"
]]
}
}'

Example predict response:

{"payload":{"predictions":[1]}}

NOTE: When there are multiple predictions, they must be returned by the endpoint in the same order as the instances in the request.

Soft scores

Classification models may also provide soft scores for each row in one of two forms encoded via the optional fields scores and threshold. Both predictions and scores are optional, but at least one must be present.

The two forms of soft-scoring are as follows:

Form 1: For binary classification only, the scores array may be a simple list of scores for the positive class, and the threshold is the value at which the score causes the prediction to be considered positive (if omitted 0.5 is assumed).

{
"payload": {
"predictions": [1],
"scores": [0.7],
"threshold": 0.5
}
}

Form 2: For general classification (binary or multi-class) the scores array may be an array (one per input row) of arrays (one per class label) of scores; wherein it is assumed that the predicted label is the one with the highest score. threshold is ignored in this case. The model may optionally return the ordering of the scores array (label dimension) overriding anything specified in the Certifai scan definition. This allows models to assert whatever label ordering metadata is appropriate to them in a way that ensures compatibility with the particular deployed trained instance of the model.

The following is an example response for a request containing a single instance. The model is multi-class with three class labels. The prediction is "three" because this has the highest score (0.4).

{
"payload": {
"predictions": ["three"],
"scores": [[0.2, 0.2, 0.4]],
"labels": ["one", "two", "three"]
}
}