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

Functions
XGB_DLL int	XGBoosterLoadModel (BoosterHandle handle, const char *fname)
	Load model from existing file.

XGB_DLL int	XGBoosterSaveModel (BoosterHandle handle, const char *fname)
	Save model into existing file.

XGB_DLL int	XGBoosterLoadModelFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len)
	load model from in memory buffer

XGB_DLL 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.

XGB_DLL int	XGBoosterGetModelRaw (BoosterHandle handle, bst_ulong out_len, const char *out_dptr)
	Save booster to a buffer with in binary format.

XGB_DLL int	XGBoosterSerializeToBuffer (BoosterHandle handle, bst_ulong out_len, const char *out_dptr)
	Memory snapshot based serialization method. Saves everything states into buffer.

XGB_DLL int	XGBoosterUnserializeFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len)
	Memory snapshot based serialization method. Loads the buffer returned from XGBoosterSerializeToBuffer.

XGB_DLL int	XGBoosterLoadRabitCheckpoint (BoosterHandle handle, int *version)
	Initialize the booster from rabit checkpoint. This is used in distributed training API.

XGB_DLL int	XGBoosterSaveRabitCheckpoint (BoosterHandle handle)
	Save the current checkpoint to rabit.

XGB_DLL 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.

XGB_DLL 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.

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()

XGB_DLL 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()

XGB_DLL 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()

XGB_DLL int XGBoosterLoadModel	(	BoosterHandle	handle,
		const char *	fname
	)

Load model from existing file.

Parameters

handle	handle
fname	File URI or file name. The string must be UTF-8 encoded.

Returns: 0 when success, -1 when failure happens

Examples: inference.c.

◆ XGBoosterLoadModelFromBuffer()

XGB_DLL 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()

XGB_DLL 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()

XGB_DLL 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()

XGB_DLL int XGBoosterSaveModel	(	BoosterHandle	handle,
		const char *	fname
	)

Save model into existing file.

Parameters

handle	handle
fname	File URI or file name. The string must be UTF-8 encoded.

Returns: 0 when success, -1 when failure happens

Examples: external_memory.c, and inference.c.

◆ XGBoosterSaveModelToBuffer()

XGB_DLL 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()

XGB_DLL int XGBoosterSaveRabitCheckpoint ( BoosterHandle handle )

Save the current checkpoint to rabit.

Parameters

handle handle

Returns: 0 when success, -1 when failure happens

◆ XGBoosterSerializeToBuffer()

XGB_DLL 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()

XGB_DLL 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

Functions

Detailed Description

Function Documentation

◆ XGBoosterGetModelRaw()

◆ XGBoosterLoadJsonConfig()

◆ XGBoosterLoadModel()

◆ XGBoosterLoadModelFromBuffer()

◆ XGBoosterLoadRabitCheckpoint()

◆ XGBoosterSaveJsonConfig()

◆ XGBoosterSaveModel()

◆ XGBoosterSaveModelToBuffer()

◆ XGBoosterSaveRabitCheckpoint()

◆ XGBoosterSerializeToBuffer()

◆ XGBoosterUnserializeFromBuffer()