dmlc / dmlc/xgboost

[RFC] Unifying prediction API.

Open
#6,632 10 comments 0 reactions 0 assignees View on GitHub
type: roadmap
Dominant language
C++
Stars
28.8k
Forks
8.9k
Avg merge
1d 12h
Merged PRs (30d)
54

Description

## Background

XGBoost has a number of prediction functions exposed on C API and various language bindings. Including prediction on DMatrix and inplace prediction. Inside these prediction functions, we also have a number of prediction types, including `value`, `margin`, `leaf`, `contribs` and `interaction`. The outputs of them have different meanings and shapes. Right now language bindings are responsible for figuring that out, which has became a burden since we have introduced dask interface on top of Python (https://github.com/dmlc/xgboost/pull/6614). Also, the output shape is quite complicated, I have difficult time on figuring out how to slice up the output array from `pred_leaf`. Aside from these, there are also different prediction parameters, including `ntree_limit`, `n_layers`, `is_training`, also a never used parameter `tree_begin`. Lastly if the prediction is carried inplace, some more information like `missing` and `base_margin` needs to be carried into implementation.

## Requirments

We unify the prediction functions of C API in a consistent manner. The new prediction functions should be able to figure out the output shape for language bindings, and should be extensible to future feature addition. At the same time, we need to look into what are the parameters that we don't want, like `ntree_limit`. Since this is designing at C API level, we should try to comply to some C programming practices on API design.

At the same time, we are not near next major release (2.0), so old API should be kept for compatibility.

## Proposal

1. Define a public prediction parameter struct:
``` c
enum PredictType { // should not use enum, just for demo
kValue,
kMargin,
kContribution,
kInteraction,
kLeaf
};

typedef struct _PredictParam {
bool is_training;
int32_t begin_iteration;
int32_t end_iteration;
PredictType type;

// Unused if input is DMatrix.
void* base_margin;
int base_margin_shape;
float missing;
} PredictParam;
```

2. Define a set of public functions with consistent semantic:
``` c
int XGBoosterPredictFromDMatrix(BoosterHandle booster, DMatrixHandle dmatrix, PredictParam param, bst_ulong **out_shape, bst_float **out_result);

int XGBoosterPredictFromDense(BoosterHandle booster, void* data, DataType type, int* shape, PredictParam param, bst_ulong **out_shape, bst_float **out_result);

...
```

The functions should output correct shape on `out_shape` parameter, and `PredictParam` will be responsible for future extensibility. Additionally we can cooperate more information into input and output, like device ordinal, data slicing etc. This RFC is for whether should we be carrying out this refactor.

## Brief notes
Some more notes on the prediction function:
- The output shape for contribution and interaction is not unified. It depends on whether multi-class is used.
- Predict leaf is always returning 2 dim array, num class and forest are not considered.
- When output_margin is set, the output array is still 1 dim vector, but it should be 2 dim matrix for multi-class.
- The output shape for softmax and softprob are both 1 dim vector, should be make softprob output a 2 dim matrix?
- Maybe we should add a parameter to let user choose a stricter output shape?

@hcho3 @RAMitchell

Contributor guide

No contributing guide indexed for this repository

Research direction

Review the existing C API prediction entry points, especially XGBoosterPredictFromDMatrix and the proposed XGBoosterPredictFromDense, along with current DMatrix and inplace prediction behavior. Compare prediction types, parameters, and output shapes across the listed cases; done means an agreed extensible API design that preserves the old API for compatibility.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, python
Domain
api, backend-api-design, machine-learning
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.