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"] }}