Serialization

There are multiple ways to serialize a Booster object depending on the use case. More...

Collaboration diagram for Serialization:

Functions
int	XGBoosterLoadModel (BoosterHandle handle, const char *fname)
	Load model from existing file. More...
int	XGBoosterSaveModel (BoosterHandle handle, const char *fname)
	Save model into existing file. More...
int	XGBoosterLoadModelFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len)
	load model from in memory buffer More...
int	XGBoosterSaveModelToBuffer (BoosterHandle handle, char const *config, bst_ulong *out_len, char const **out_dptr)
	Save model into raw bytes, return header of the array. User must copy the result out, before next xgboost call. More...
int	XGBoosterGetModelRaw (BoosterHandle handle, bst_ulong *out_len, const char **out_dptr)
	Save booster to a buffer with in binary format. More...
int	XGBoosterSerializeToBuffer (BoosterHandle handle, bst_ulong *out_len, const char **out_dptr)
	Memory snapshot based serialization method. Saves everything states into buffer. More...
int	XGBoosterUnserializeFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len)
	Memory snapshot based serialization method. Loads the buffer returned from XGBoosterSerializeToBuffer. More...
int	XGBoosterLoadRabitCheckpoint (BoosterHandle handle, int *version)
	Initialize the booster from rabit checkpoint. This is used in distributed training API. More...
int	XGBoosterSaveRabitCheckpoint (BoosterHandle handle)
	Save the current checkpoint to rabit. More...
int	XGBoosterSaveJsonConfig (BoosterHandle handle, bst_ulong *out_len, char const **out_str)
	Save XGBoost's internal configuration into a JSON document. Currently the support is experimental, function signature may change in the future without notice. More...
int	XGBoosterLoadJsonConfig (BoosterHandle handle, char const *config)
	Load XGBoost's internal configuration from a JSON document. Currently the support is experimental, function signature may change in the future without notice. More...

Detailed Description

There are multiple ways to serialize a Booster object depending on the use case.

Short note for serialization APIs. There are 3 different sets of serialization API.

• Functions with the term "Model" handles saving/loading XGBoost model like trees or linear weights. Striping out parameters configuration like training algorithms or CUDA device ID. These functions are designed to let users reuse the trained model for different tasks, examples are prediction, training continuation or model interpretation.
• Functions with the term "Config" handles save/loading configuration. It helps user to study the internal of XGBoost. Also user can use the load method for specifying parameters in a structured way. These functions are introduced in 1.0.0, and are not yet stable.
• Functions with the term "Serialization" are combined of above two. They are used in situations like check-pointing, or continuing training task in distributed environment. In these cases the task must be carried out without any user intervention.

Function Documentation

XGBoosterGetModelRaw()

int XGBoosterGetModelRaw	(	BoosterHandle	handle,
		bst_ulong *	out_len,
		const char **	out_dptr
	)

Save booster to a buffer with in binary format.

Deprecated:

since 1.6.0

See also

XGBoosterSaveModelToBuffer()

XGBoosterLoadJsonConfig()

int XGBoosterLoadJsonConfig	(	BoosterHandle	handle,
		char const *	config
	)

Load XGBoost's internal configuration from a JSON document. Currently the support is experimental, function signature may change in the future without notice.

Parameters

handle	handle to Booster object.
config	string representation of a JSON document.

Returns

0 when success, -1 when failure happens

XGBoosterLoadModel()

int XGBoosterLoadModel	(	BoosterHandle	handle,
		const char *	fname
	)

Load model from existing file.

Parameters

handle	handle
fname	File URI or file name.

Returns

0 when success, -1 when failure happens

Examples

inference.c.

XGBoosterLoadModelFromBuffer()

int XGBoosterLoadModelFromBuffer	(	BoosterHandle	handle,
		const void *	buf,
		bst_ulong	len
	)

load model from in memory buffer

Parameters

handle	handle
buf	pointer to the buffer
len	the length of the buffer

Returns

0 when success, -1 when failure happens

XGBoosterLoadRabitCheckpoint()

int XGBoosterLoadRabitCheckpoint	(	BoosterHandle	handle,
		int *	version
	)

Initialize the booster from rabit checkpoint. This is used in distributed training API.

Parameters

handle	handle
version	The output version of the model.

Returns

0 when success, -1 when failure happens

XGBoosterSaveJsonConfig()

int XGBoosterSaveJsonConfig	(	BoosterHandle	handle,
		bst_ulong *	out_len,
		char const **	out_str
	)

Save XGBoost's internal configuration into a JSON document. Currently the support is experimental, function signature may change in the future without notice.

Parameters

handle	handle to Booster object.
out_len	length of output string
out_str	A valid pointer to array of characters. The characters array is allocated and managed by XGBoost, while pointer to that array needs to be managed by caller.

Returns

0 when success, -1 when failure happens

XGBoosterSaveModel()

int XGBoosterSaveModel	(	BoosterHandle	handle,
		const char *	fname
	)

Save model into existing file.

Parameters

handle	handle
fname	File URI or file name.

Returns

0 when success, -1 when failure happens

Examples

external_memory.c, and inference.c.

XGBoosterSaveModelToBuffer()

int XGBoosterSaveModelToBuffer	(	BoosterHandle	handle,
		char const *	config,
		bst_ulong *	out_len,
		char const **	out_dptr
	)

Save model into raw bytes, return header of the array. User must copy the result out, before next xgboost call.

Parameters

handle	handle
config	JSON encoded string storing parameters for the function. Following keys are expected in the JSON document:

"format": str

• json: Output booster will be encoded as JSON.
• ubj: Output booster will be encoded as Univeral binary JSON.
• deprecated: Output booster will be encoded as old custom binary format. Do not use this format except for compatibility reasons.

Parameters

out_len	The argument to hold the output length
out_dptr	The argument to hold the output data pointer

Returns

0 when success, -1 when failure happens

XGBoosterSaveRabitCheckpoint()

int XGBoosterSaveRabitCheckpoint

(

BoosterHandle

handle

)

Save the current checkpoint to rabit.

Parameters

handle

handle

Returns

0 when success, -1 when failure happens

XGBoosterSerializeToBuffer()

int XGBoosterSerializeToBuffer	(	BoosterHandle	handle,
		bst_ulong *	out_len,
		const char **	out_dptr
	)

Memory snapshot based serialization method. Saves everything states into buffer.

Parameters

handle	handle
out_len	the argument to hold the output length
out_dptr	the argument to hold the output data pointer

Returns

0 when success, -1 when failure happens

XGBoosterUnserializeFromBuffer()

int XGBoosterUnserializeFromBuffer	(	BoosterHandle	handle,
		const void *	buf,
		bst_ulong	len
	)

Memory snapshot based serialization method. Loads the buffer returned from XGBoosterSerializeToBuffer.

Parameters

handle	handle
buf	pointer to the buffer
len	the length of the buffer

Returns

0 when success, -1 when failure happens