XGBoost C 包

XGBoost 实现了一套专为各种绑定设计的 C API，我们维护其稳定性和 CMake/make 构建接口。请参阅 C API 教程获取介绍，并查看 demo/c-api/ 获取相关示例。此外，可以在构建时向 CMake 提供参数 -DBUILD_C_DOC=ON 生成 doxygen 文档，或者直接查看 include/xgboost/c_api.h 中的函数注释。该参考文档借助 breathe 导出到 sphinx，它不包含示例链接，但可能更容易阅读。对于原始 doxygen 页面，请访问

C API 参考

库

group Library

这些函数用于获取关于 XGBoost 的一般信息，包括版本、构建信息和当前全局配置。

类型定义

typedef void *DMatrixHandle: DMatrix 句柄

typedef void *BoosterHandle: Booster 句柄

函数

void XGBoostVersion(int *major, int *minor, int *patch)

返回当前使用的 XGBoost 库的版本。

输出变量仅在不为 NULL 时写入。

参数:

major – 存储主版本号
minor – 存储次版本号
patch – 存储补丁 (修订) 号

int XGBuildInfo(char const **out)

获取共享库的编译信息。

参数:: out – 包含构建标志和依赖版本信息的 JSON 字符串对象。
返回:: 成功返回 0，失败返回 -1

const char *XGBGetLastError()

获取最后一个错误的字符串消息

此文件中的所有函数在成功时返回 0，在发生错误时返回 -1，可以调用 XGBGetLastError 检索错误信息

此函数是线程安全的，可由不同线程调用

返回:: const char* 错误信息

int XGBRegisterLogCallback(void (*callback)(const char*))

注册用于 LOG(INFO) 消息的回调函数 — 有用的非错误消息。注意：此函数可由多个线程调用。回调函数将在注册它的线程上运行

返回:: 成功返回 0，失败返回 -1

int XGBSetGlobalConfig(char const *config)

设置全局配置（适用于全局的参数集合）。此函数接受表示要配置的全局范围参数的键值对列表。键值对列表以 JSON 字符串形式传入。

参数:: config – 表示键值对列表的 JSON 字符串。JSON 对象应是扁平的：任何值都不能是 JSON 对象或数组。
返回:: 成功返回 0，失败返回 -1

int XGBGetGlobalConfig(char const **out_config)

获取当前全局配置（适用于全局的参数集合）。

参数:: out_config – 指向接收返回的全局配置的指针，以 JSON 字符串表示。
返回:: 成功返回 0，失败返回 -1

DMatrix

group DMatrix

DMatrix 是 XGBoost 的基本数据存储，用于所有 XGBoost 算法，包括训练、预测和解释。DMatrix 有几种变体，包括普通的 DMatrix（它是 CSR 矩阵）、基于直方图树方法用于节省内存的 QuantileDMatrix，以及最后实验性的基于外部内存的 DMatrix（在训练期间分批读取数据）。对于后两种变体，请参见 Streaming 组。

函数

int XGDMatrixCreateFromFile(const char *fname, int silent, DMatrixHandle *out)

加载数据矩阵

已弃用: 自 2.0.0 起

另请参阅

XGDMatrixCreateFromURI()

参数:

fname – 文件名
silent – 加载期间是否打印消息
out – 加载的数据矩阵

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromURI(char const *config, DMatrixHandle *out)

加载数据矩阵

参数:

config – 用于构建 DMatrix 的 JSON 编码参数。接受的字段有
- uri: 输入文件的 URI。加载文本数据时，URI 参数 format 是必需的。
  有关更多信息，请参阅 DMatrix 的文本输入格式。
- silent (可选): 加载期间是否打印消息。默认为 true。
- data_split_mode (可选): 对于分布式计算，文件是否事先按行或列分割。默认为按行分割。
out – 加载的数据矩阵

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromCSREx(const size_t *indptr, const unsigned *indices, const float *data, size_t nindptr, size_t nelem, size_t num_col, DMatrixHandle *out)

从 CSR 格式创建矩阵内容

已弃用: 自 2.0.0 起

另请参阅

XGDMatrixCreateFromCSR()

int XGDMatrixCreateFromColumnar(char const *data, char const *config, DMatrixHandle *out)

从列式数据创建 DMatrix。(表格)

输入到 DMatrix 的一种特殊类型是列式格式，它指的是基于 arrow 格式的列式数据框。

参数:

data – JSON 编码的 array 接口列表。
config – 详细信息请参阅 XGDMatrixCreateFromDense。
out – 创建的 DMatrix。

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromCSR(char const *indptr, char const *indices, char const *data, bst_ulong ncol, char const *config, DMatrixHandle *out)

从 CSR 矩阵创建 DMatrix。

参数:

indptr – 指向 CSR 中行指针的 JSON 编码 array_interface。
indices – 指向 CSR 中列索引的 JSON 编码 array_interface。
data – 指向 CSR 中值的 JSON 编码 array_interface。
ncol – 列数。
config – 详细信息请参阅 XGDMatrixCreateFromDense。
out – 创建的 dmatrix

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromDense(char const *data, char const *config, DMatrixHandle *out)

从密集数组创建 DMatrix。

array 接口在 https://numpy.com.cn/doc/2.1/reference/arrays.interface.html 中定义。我们将接口编码为 JSON 对象。

参数:

data – 指向数组值的 JSON 编码 array_interface。
config – JSON 编码配置。必需的值有
- missing: 表示缺失值的值。
- nthread (可选): 用于初始化 DMatrix 的线程数。
- data_split_mode (可选): 数据是否事先按行或列分割。默认为按行分割。
out – 创建的 DMatrix

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromCSC(char const *indptr, char const *indices, char const *data, bst_ulong nrow, char const *config, DMatrixHandle *out)

从 CSC 矩阵创建 DMatrix。

参数:

indptr – 指向 CSC 中列指针的 JSON 编码 array_interface。
indices – 指向 CSC 中行索引的 JSON 编码 array_interface。
data – 指向 CSC 中值的 JSON 编码 array_interface。
nrow – 矩阵中的行数。
config – 详细信息请参阅 XGDMatrixCreateFromDense。
out – 创建的 dmatrix。

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromCSCEx(const size_t *col_ptr, const unsigned *indices, const float *data, size_t nindptr, size_t nelem, size_t num_row, DMatrixHandle *out)

从 CSC 格式创建矩阵内容

已弃用: 自 2.0.0 起

另请参阅

XGDMatrixCreateFromCSC()

int XGDMatrixCreateFromMat(const float *data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle *out)

从密集矩阵创建矩阵内容

参数:

data – 指向数据空间的指针
nrow – 行数
ncol – 列数
missing – 表示缺失值的值
out – 创建的 dmatrix

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromMat_omp(const float *data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle *out, int nthread)

从密集矩阵创建矩阵内容

参数:

data – 指向数据空间的指针
nrow – 行数
ncol – 列数
missing – 表示缺失值的值
out – 创建的 dmatrix
nthread – 线程数 (最多可用核心数，如果 <=0 则使用所有核心)

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromCudaColumnar(char const *data, char const *config, DMatrixHandle *out)

从 CUDA 列式格式创建 DMatrix。(cuDF)

有关列式格式的简要说明，请参阅 XGDMatrixCreateFromColumnar。

参数:

data – JSON 编码的 array 接口列表。
config – 详细信息请参阅 XGDMatrixCreateFromDense。
out – 创建的 dmatrix

返回:

成功时为 0，失败时为 -1

int XGDMatrixCreateFromCudaArrayInterface(char const *data, char const *config, DMatrixHandle *out)

从 CUDA 数组创建 DMatrix。

参数:

data – 用于数组数据的 JSON 编码 cuda_array_interface。
config – JSON 编码配置。必需的值有
- missing: 表示缺失值的值。
- nthread (可选): 用于初始化 DMatrix 的线程数。
- data_split_mode (可选): 数据是否事先按行或列分割。默认为按行分割。
out – 创建的 dmatrix

返回:

成功时为 0，失败时为 -1

int XGDMatrixSliceDMatrix(DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out)

从现有矩阵的切片内容创建新的 dmatrix

参数:

handle – 待切片的数据矩阵实例
idxset – 索引集
len – 索引集长度
out – 切片生成的新矩阵

返回:

成功时为 0，失败时为 -1

int XGDMatrixSliceDMatrixEx(DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out, int allow_groups)

从现有矩阵的切片内容创建新的 dmatrix

参数:

handle – 待切片的数据矩阵实例
idxset – 索引集
len – 索引集长度
out – 切片生成的新矩阵
allow_groups – 允许对带有组的数组进行切片

返回:

成功时为 0，失败时为 -1

int XGDMatrixFree(DMatrixHandle handle)

释放数据矩阵中的空间

返回:: 成功时为 0，失败时为 -1

int XGDMatrixSaveBinary(DMatrixHandle handle, const char *fname, int silent)

将 DMatrix 对象保存到文件。不支持 QuantileDMatrix 和外部内存 DMatrix。

参数:

handle – 数据矩阵实例
fname – 文件名
silent – 保存时是否打印统计信息

返回:

成功时为 0，失败时为 -1

int XGDMatrixSetInfoFromInterface(DMatrixHandle handle, const char *field, char const *data)

将 array interface 中的内容设置到 info 中。

参数:

handle – 数据矩阵实例
field – 字段名。
data – 指向密集矩阵/向量中值的 JSON 编码 array_interface。

返回:

成功时为 0，失败时为 -1

int XGDMatrixSetFloatInfo(DMatrixHandle handle, const char *field, const float *array, bst_ulong len)

将 float 向量设置到 info 中的内容

参数:

handle – 数据矩阵实例
field – 字段名，可以是 label, weight
array – 指向 float 向量的指针
len – 数组长度

返回:

成功时为 0，失败时为 -1

int XGDMatrixSetUIntInfo(DMatrixHandle handle, const char *field, const unsigned *array, bst_ulong len)

已弃用: 自 2.1.0 起

请改用 XGDMatrixSetInfoFromInterface。

int XGDMatrixSetStrFeatureInfo(DMatrixHandle handle, const char *field, const char **features, const bst_ulong size)

设置所有特征的字符串编码信息。

接受的字段有

feature_name
feature_type

char const* feat_names [] {"feat_0", "feat_1"};
XGDMatrixSetStrFeatureInfo(handle, "feature_name", feat_names, 2);

// i for integer, q for quantitive, c for categorical.  Similarly "int" and "float"
// are also recognized.
char const* feat_types [] {"i", "q"};
XGDMatrixSetStrFeatureInfo(handle, "feature_type", feat_types, 2);

参数:

handle – 数据矩阵实例
field – 字段名
features – 指向字符串数组的指针。
size – features 指针的大小 (传入的字符串数量)。

返回:

成功时为 0，失败时为 -1

int XGDMatrixGetStrFeatureInfo(DMatrixHandle handle, const char *field, bst_ulong *size, const char ***out_features)

获取所有特征的字符串编码信息。

接受的字段有

feature_name
feature_type

调用者有责任在下次调用任何 XGBoost API 函数之前复制出数据。

char const **c_out_features = NULL;
bst_ulong out_size = 0;

// Asumming the feature names are already set by `XGDMatrixSetStrFeatureInfo`.
XGDMatrixGetStrFeatureInfo(handle, "feature_name", &out_size,
                           &c_out_features)

for (bst_ulong i = 0; i < out_size; ++i) {
  // Here we are simply printing the string.  Copy it out if the feature name is
  // useful after printing.
  printf("feature %lu: %s\n", i, c_out_features[i]);
}

参数:

handle – 数据矩阵实例
field – 字段名
size – 输出指针 features 的大小 (返回的字符串数量)。
out_features – 指向字符串数组指针的地址。结果存储在线程本地内存中。

返回:

成功时为 0，失败时为 -1

int XGDMatrixSetDenseInfo(DMatrixHandle handle, const char *field, void const *data, bst_ulong size, int type)

已弃用: 自 2.1.0 起

请改用 XGDMatrixSetInfoFromInterface。

int XGDMatrixGetFloatInfo(const DMatrixHandle handle, const char *field, bst_ulong *out_len, const float **out_dptr)

从矩阵获取 float 信息向量。

参数:

handle – 数据矩阵实例
field – 字段名
out_len – 用于设置结果长度
out_dptr – 指向结果的指针

返回:

成功时为 0，失败时为 -1

int XGDMatrixGetUIntInfo(const DMatrixHandle handle, const char *field, bst_ulong *out_len, const unsigned **out_dptr)

从矩阵获取 uint32 信息向量

参数:

handle – 数据矩阵实例
field – 字段名
out_len – 字段长度。
out_dptr – 指向结果的指针

返回:

成功时为 0，失败时为 -1

int XGDMatrixNumRow(DMatrixHandle handle, bst_ulong *out)

获取行数。

参数:

handle – DMatrix 句柄
out – 用于存储行数的地址。

返回:

成功时为 0，失败时为 -1

int XGDMatrixNumCol(DMatrixHandle handle, bst_ulong *out)

获取列数

参数:

handle – DMatrix 句柄
out – 输出的列数

返回:

成功时为 0，失败时为 -1

int XGDMatrixNumNonMissing(DMatrixHandle handle, bst_ulong *out)

从 DMatrix 获取有效值的数量。

参数:

handle – DMatrix 句柄
out – 输出的非缺失值数量

返回:

成功时为 0，失败时为 -1

int XGDMatrixDataSplitMode(DMatrixHandle handle, bst_ulong *out)

从 DMatrix 获取数据分割模式。

参数:

handle – DMatrix 句柄
out – 输出的数据分割模式

返回:

成功时为 0，失败时为 -1

int XGDMatrixGetDataAsCSR(DMatrixHandle const handle, char const *config, bst_ulong *out_indptr, unsigned *out_indices, float *out_data)

以 CSR 矩阵格式获取 DMatrix 中的预测器用于测试。如果这是量化 DMatrix，则返回量化值。

与大多数 XGBoost C 函数不同，调用 XGDMatrixGetDataAsCSR 的调用者需要自行分配返回缓冲区内存，而不是使用 XGBoost 的线程本地内存。这是为了避免分配无法在线程退出前释放的巨大内存缓冲区。

自: 1.7.0

参数:

handle – DMatrix 句柄
config – JSON 配置字符串。目前它应该是一个空文档，保留供将来使用。
out_indptr – 输出 CSR 矩阵的 indptr。
out_indices – 输出 CSR 矩阵的列索引。
out_data – CSR 矩阵的数据值。

返回:

成功时为 0，失败时为 -1

int XGDMatrixGetQuantileCut(DMatrixHandle const handle, char const *config, char const **out_indptr, char const **out_data)

导出用于训练基于直方图的模型（如 hist 和 approx）的分位数切分点。对于模型压缩很有用。

自: 2.0.0

参数:

handle – DMatrix 句柄
config – JSON 配置字符串。目前它应该是一个空文档，保留供将来使用。
out_indptr – 输出 CSC 矩阵的 indptr，由 JSON 编码的 __(cuda_)array_interface__ 表示。
out_data – CSC 矩阵的数据值，由 JSON 编码的 __(cuda_)array_interface__ 表示。

Streaming

group Streaming

Quantile DMatrix 和外部内存 DMatrix 可以从数据批次创建。

DMatrix 有两组数据回调函数。第一组目前仅由 JVM 包使用。它使用 XGBoostBatchCSR 接受 CSR 格式输入的批次数据，并将它们连接成一个最终的大型 CSR。相关函数有

XGBCallbackSetData
XGBCallbackDataIterNext
XGDMatrixCreateFromDataIter

另一组由外部数据迭代器使用。它接受外部数据迭代器作为回调。在两种不同场景下，用户可能希望传入回调函数而不是原始数据。首先是 hist 和基于 GPU 的 hist 树方法使用的 Quantile DMatrix。在这种情况下，数据首先通过分位数 sketching 进行压缩，然后合并。这对于分布式设置特别有用，因为它消除了两次数据复制。第一次是由外部库的 concat 将数据组合成一个块用于正常的 DMatrix 初始化，另一次是由 DMatrix 的内部 CSR 复制。

第二种用例是外部内存支持，用户可以将自定义数据迭代器传入 XGBoost 以分批加载数据。对于这两种情况，迭代器仅在构建 DMatrix 期间使用，并在构建完成后可以安全释放。在相应的 DMatrix 工厂函数中，对每种用例都有简要说明。

工厂函数

用于外部内存的 XGDMatrixCreateFromCallback
用于 quantile DMatrix 的 XGQuantileDMatrixCreateFromCallback
用于外部内存 Quantile DMatrix 的 XGExtMemQuantileDMatrixCreateFromCallback

类型定义

typedef void *DataIterHandle: 外部数据迭代器的句柄

typedef void *DataHolderHandle: 内部数据持有者的句柄。

typedef int XGBCallbackSetData(DataHolderHandle handle, XGBoostBatchCSR batch)

用于将数据设置到句柄的回调函数。

参数 handle:: 回调函数的句柄。
参数 batch:: 要设置的数据内容。

typedef int XGBCallbackDataIterNext(DataIterHandle data_handle, XGBCallbackSetData *set_function, DataHolderHandle set_function_handle)

数据读取回调函数。迭代器将能够提供数据批次的子集。

如果存在数据，函数将调用 set_function 来设置数据。

参数 data_handle:: 回调函数的句柄。
参数 set_function:: 迭代器返回的批次
参数 set_function_handle:: 要传递给 set 函数的句柄。
返回:: 如果到达末尾且未返回批次，则返回 0。

typedef int XGDMatrixCallbackNext(DataIterHandle iter)

获取下一批数据的回调函数原型。

参数 iter:: 用户定义迭代器的句柄。
返回:: 成功时为 0，失败时为 -1。

typedef void DataIterResetCallback(DataIterHandle handle): 重置外部迭代器的回调函数原型。

函数

int XGDMatrixCreateFromDataIter(DataIterHandle data_handle, XGBCallbackDataIterNext *callback, const char *cache_info, float missing, DMatrixHandle *out)

从数据迭代器创建 DMatrix。

参数:

data_handle – 数据的句柄。
callback – 获取数据的回调函数。
cache_info – 关于缓存文件的附加信息，可以为 null。
missing – 表示缺失值的值。
out – 创建的 DMatrix

返回:

成功时为 0，失败时为 -1。

int XGProxyDMatrixCreate(DMatrixHandle *out)

创建一个用于设置数据的 DMatrix 代理，可以使用 XGDMatrixFree 释放。

第二组回调函数，用于使用自定义迭代器构建 Quantile DMatrix 或外部内存 DMatrix。

DMatrix 代理只是实际用户数据的临时引用（包装器）。例如，如果通过 XGProxyDMatrixSetDataDense 方法将密集矩阵（如 numpy 数组）传入代理 DMatrix，则代理 DMatrix 仅持有引用，并且在下一次迭代开始（由 XGBoost 调用 XGDMatrixCallbackNext 发出信号）之前，输入数组不能被释放。它被称为 ProxyDMatrix 是因为它重用了 XGBoost 中 DMatrix 类的接口，但它只是 XGDMatrixCreateFromCallback 和相关构造函数用于消费各种用户输入类型的一个中间接口。

User inputs -> Proxy DMatrix (wrapper) -> Actual DMatrix

参数:: out – 创建的代理 DMatrix。
返回:: 成功时为 0，失败时为 -1。

int XGDMatrixCreateFromCallback(DataIterHandle iter, DMatrixHandle proxy, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)

使用数据迭代器创建外部内存 DMatrix。

关于如何使用第二组回调支持外部内存数据的简短说明

步骤 0: 定义一个包含 reset 和 next 两个方法的数据迭代器。
步骤 1: 通过 XGProxyDMatrixCreate 创建一个 DMatrix 代理并持有句柄。
步骤 2: 将迭代器句柄、代理句柄和两个方法传入 XGDMatrixCreateFromCallback，以及编码为 JSON 对象的其他参数。
步骤 3: 在 next 函数中调用适当的数据设置器。

参数:

iter – 外部数据迭代器的句柄。
proxy – 通过 XGProxyDMatrixCreate 创建的 DMatrix 代理句柄。
reset – 重置迭代器状态的回调函数。
next – 生成下一批数据的回调函数。
config – 用于构建 DMatrix 的 JSON 编码参数。接受的字段有
- missing: 表示缺失值的值
- cache_prefix: 缓存文件的路径，调用者必须初始化该路径中的所有目录。
- nthread (可选): 用于初始化 DMatrix 的线程数。
out – [out] 创建的外部内存 DMatrix

返回:

成功时为 0，失败时为 -1

int XGQuantileDMatrixCreateFromCallback(DataIterHandle iter, DMatrixHandle proxy, DataIterHandle ref, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)

使用数据迭代器创建 Quantile DMatrix。

关于如何使用第二组回调支持 (GPU)Hist 树方法的简短说明

步骤 0: 定义一个包含 reset 和 next 两个方法的数据迭代器。
步骤 1: 通过 XGProxyDMatrixCreate 创建一个 DMatrix 代理并持有句柄。
步骤 2: 将迭代器句柄、代理句柄和两个方法传入 XGQuantileDMatrixCreateFromCallback。
步骤 3: 在 next 函数中调用适当的数据设置器。

请参阅 test_iterative_dmatrix.cu 或 Python 接口以获取示例。

参数:

iter – 外部数据迭代器的句柄。
proxy – 通过 XGProxyDMatrixCreate 创建的 DMatrix 代理句柄。
ref – 提供分位数信息的参考 DMatrix。
reset – 重置迭代器状态的回调函数。
next – 生成下一批数据的回调函数。
config – 用于构建 DMatrix 的 JSON 编码参数。接受的字段有
- missing: 表示缺失值的值
- nthread (可选): 用于初始化 DMatrix 的线程数。
- max_bin (可选): 构建直方图的最大 bin 数。必须与相应的 booster 训练参数一致。
- max_quantile_blocks (可选): 对于基于 GPU 的输入，XGBoost 使用多个增长的子流处理传入的批次。此参数设置 XGBoost 切断子流并创建一个新子流之前的最大批次数。这有助于限制内存使用。默认情况下，XGBoost 会指数级地增长新的子流，直到批次耗尽。仅用于训练数据集，默认值为 None (无界限)。
out – 创建的 Quantile DMatrix。

返回:

成功时为 0，失败时为 -1

int XGExtMemQuantileDMatrixCreateFromCallback(DataIterHandle iter, DMatrixHandle proxy, DataIterHandle ref, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)

创建由外部内存支持的 Quantile DMatrix。

自: 3.0.0

注意

这是一个实验性功能，可能会发生变化。

参数:

iter – 外部数据迭代器的句柄。
proxy – 通过 XGProxyDMatrixCreate 创建的 DMatrix 代理句柄。
ref – 提供分位数信息的参考 DMatrix。
reset – 重置迭代器状态的回调函数。
next – 生成下一批数据的回调函数。
config – 用于构建 DMatrix 的 JSON 编码参数。接受的字段有
- missing: 表示缺失值的值
- cache_prefix: 缓存文件的路径，调用者必须初始化该路径中的所有目录。
- nthread (可选): 用于初始化 DMatrix 的线程数。
- max_bin (可选): 构建直方图的最大 bin 数。必须与相应的 booster 训练参数一致。
- on_host (可选): 数据是否应放置在主机内存中。由 GPU 输入使用。
- min_cache_page_bytes (可选): 每个内部 GPU 页的最小字节数。设置为 0 可禁用页面串联。如果未提供或设置为 None，则自动配置。
- max_quantile_blocks (可选): 对于基于 GPU 的输入，XGBoost 使用多个增长的子流处理传入的批次。此参数设置 XGBoost 切断子流并创建一个新子流之前的最大批次数。这有助于限制内存使用。默认情况下，XGBoost 会指数级地增长新的子流，直到批次耗尽。仅用于训练数据集，默认值为 None (无界限)。
out – 创建的 Quantile DMatrix。

返回:

成功时为 0，失败时为 -1

int XGProxyDMatrixSetDataCudaArrayInterface(DMatrixHandle handle, const char *data)

在 DMatrix 代理上设置数据。

参数:

handle – 由 XGProxyDMatrixCreate 创建的 DMatrix 代理
data – 表示 CUDA 数组接口的以 Null 终止的 JSON 文档字符串。

返回:

成功时为 0，失败时为 -1

int XGProxyDMatrixSetDataColumnar(DMatrixHandle handle, char const *data)

在 DMatrix 代理上设置列式（表）数据。

参数:

handle – 由 XGProxyDMatrixCreate 创建的 DMatrix 代理
data – 有关详细信息，请参阅 XGDMatrixCreateFromColumnar。

返回:

成功时为 0，失败时为 -1

int XGProxyDMatrixSetDataCudaColumnar(DMatrixHandle handle, const char *data)

在 DMatrix 代理上设置基于 CUDA 的列式（表）数据。

参数:

handle – 由 XGProxyDMatrixCreate 创建的 DMatrix 代理
data – 有关详细信息，请参阅 XGDMatrixCreateFromColumnar。

返回:

成功时为 0，失败时为 -1

int XGProxyDMatrixSetDataDense(DMatrixHandle handle, char const *data)

在 DMatrix 代理上设置数据。

参数:

handle – 由 XGProxyDMatrixCreate 创建的 DMatrix 代理
data – 表示数组接口的以 Null 终止的 JSON 文档字符串。

返回:

成功时为 0，失败时为 -1

int XGProxyDMatrixSetDataCSR(DMatrixHandle handle, char const *indptr, char const *indices, char const *data, bst_ulong ncol)

在 DMatrix 代理上设置数据。

参数:

handle – 由 XGProxyDMatrixCreate 创建的 DMatrix 代理
indptr – CSR 中行指针的 JSON 编码 **array_interface**。
indices – 指向 CSR 中列索引的 JSON 编码 array_interface。
data – CSR 中值的 JSON 编码 **array_interface**。
ncol – 输入 CSR 矩阵的列数。

返回:

成功时为 0，失败时为 -1

struct XGBoostBatchCSR: #include <c_api.h>

XGBoost 数据迭代中使用的迷你批次。

Booster

group Booster

Booster 类是 XGBoost 的梯度提升模型。

在训练期间，booster 对象有许多缓存以提高性能。除了梯度和预测之外，它还包括像叶子分区这样的运行时缓冲区。这些缓冲区会随 Booster 对象一直存在，直到调用 XGBoosterReset() 或通过 XGBoosterFree() 删除 booster。

函数

int XGBoosterCreate(const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out)

创建 XGBoost 学习器 (booster)

参数:

dmats – 被设置为由 booster 缓存的矩阵。
len – dmats 的长度
out – 结果 booster 的句柄

返回:

成功时为 0，失败时为 -1

int XGBoosterFree(BoosterHandle handle)

删除 booster。

参数:: handle – 要释放的句柄。
返回:: 成功时为 0，失败时为 -1

int XGBoosterReset(BoosterHandle handle)

重置 booster 对象以释放训练中使用的数据缓存。

自: 3.0.0

返回:: 成功时为 0，失败时为 -1

int XGBoosterSlice(BoosterHandle handle, int begin_layer, int end_layer, int step, BoosterHandle *out)

使用 boosting 索引切片模型。切片 m:n 表示获取在 boosting 轮次 m, (m+1), (m+2), …, (n-1) 期间训练的所有树。

参数:

handle – 要切片的 Booster。
begin_layer – 切片的开始索引
end_layer – 切片的结束索引；end_layer=0 等同于 end_layer=num_boost_round
step – 切片的步长
out – 切片后的 booster。

返回:

成功时返回 0，发生失败时返回 -1，索引超出范围时返回 -2。

int XGBoosterBoostedRounds(BoosterHandle handle, int *out)

从梯度 booster 获取提升轮次数量。当 process_type 为 update 时，由于删除树，此数量可能会减少。

参数:

handle – booster 的句柄。
out – 指向输出整数的指针。

返回:

成功时为 0，失败时为 -1

int XGBoosterSetParam(BoosterHandle handle, const char *name, const char *value)

设置参数

参数:

handle – 句柄
name – 参数名称
value – 参数值

返回:

成功时为 0，失败时为 -1

int XGBoosterGetNumFeature(BoosterHandle handle, bst_ulong *out)

获取特征数量

参数:

handle – booster 的句柄。
out – 特征数量

返回:

成功时为 0，失败时为 -1

int XGBoosterUpdateOneIter(BoosterHandle handle, int iter, DMatrixHandle dtrain)

使用 dtrain 更新模型一轮

参数:

handle – 句柄
iter – 当前迭代轮次
dtrain – 训练数据

返回:

成功时为 0，失败时为 -1

int XGBoosterBoostOneIter(BoosterHandle handle, DMatrixHandle dtrain, float *grad, float *hess, bst_ulong len)

已弃用: 自 2.1.0 起

int XGBoosterTrainOneIter(BoosterHandle handle, DMatrixHandle dtrain, int iter, char const *grad, char const *hess)

使用梯度和 Hessian 更新模型。这用于使用自定义目标函数进行训练。

自: 2.0.0

参数:

handle – 句柄
dtrain – 训练数据。
iter – 当前迭代轮次。使用训练继续时，计数应重新开始。
grad – 梯度的 Json 编码 __(cuda)_array_interface__。
hess – Hessian 的 Json 编码 __(cuda)_array_interface__。

返回:

成功时为 0，失败时为 -1

int XGBoosterEvalOneIter(BoosterHandle handle, int iter, DMatrixHandle dmats[], const char *evnames[], bst_ulong len, const char **out_result)

获取 xgboost 的评估统计信息

参数:

handle – 句柄
iter – 当前迭代轮次
dmats – 指向要评估的数据的指针
evnames – 指向每个数据名称的指针
len – dmats 的长度
out_result – 包含评估统计信息的字符串

返回:

成功时为 0，失败时为 -1

int XGBoosterDumpModel(BoosterHandle handle, const char *fmap, int with_stats, bst_ulong *out_len, const char ***out_dump_array)

转储模型，返回表示模型转储的字符串数组

参数:

handle – 句柄
fmap – fmap 的名称，可以是空字符串
with_stats – 是否转储统计信息
out_len – 输出数组的长度
out_dump_array – 用于保存表示每个模型转储的指针

返回:

成功时为 0，失败时为 -1

int XGBoosterDumpModelEx(BoosterHandle handle, const char *fmap, int with_stats, const char *format, bst_ulong *out_len, const char ***out_dump_array)

转储模型，返回表示模型转储的字符串数组

参数:

handle – 句柄
fmap – fmap 的名称，可以是空字符串
with_stats – 是否转储统计信息
format – 转储模型的格式
out_len – 输出数组的长度
out_dump_array – 用于保存表示每个模型转储的指针

返回:

成功时为 0，失败时为 -1

int XGBoosterDumpModelWithFeatures(BoosterHandle handle, int fnum, const char **fname, const char **ftype, int with_stats, bst_ulong *out_len, const char ***out_models)

转储模型，返回表示模型转储的字符串数组

参数:

handle – 句柄
fnum – 特征数量
fname – 特征名称
ftype – 特征类型
with_stats – 是否转储统计信息
out_len – 输出数组的长度
out_models – 用于保存表示每个模型转储的指针

返回:

成功时为 0，失败时为 -1

int XGBoosterDumpModelExWithFeatures(BoosterHandle handle, int fnum, const char **fname, const char **ftype, int with_stats, const char *format, bst_ulong *out_len, const char ***out_models)

转储模型，返回表示模型转储的字符串数组

参数:

handle – 句柄
fnum – 特征数量
fname – 特征名称
ftype – 特征类型
with_stats – 是否转储统计信息
format – 转储模型的格式
out_len – 输出数组的长度
out_models – 用于保存表示每个模型转储的指针

返回:

成功时为 0，失败时为 -1

int XGBoosterGetAttr(BoosterHandle handle, const char *key, const char **out, int *success)

从 Booster 获取字符串属性。

参数:

handle – 句柄
key – 属性的键。
out – 结果属性，如果属性不存在则为 NULL。
success – 结果是否包含在 out 中。

返回:

成功时为 0，失败时为 -1

int XGBoosterSetAttr(BoosterHandle handle, const char *key, const char *value)

设置或删除字符串属性。

参数:

handle – 句柄
key – 属性的键。
value – 要保存的值。如果为 nullptr，则删除该属性。

返回:

成功时为 0，失败时为 -1

int XGBoosterGetAttrNames(BoosterHandle handle, bst_ulong *out_len, const char ***out)

获取 Booster 中所有属性的名称。

参数:

handle – 句柄
out_len – 保存输出长度的参数
out – 用于保存输出属性字符串的指针

返回:

成功时为 0，失败时为 -1

int XGBoosterSetStrFeatureInfo(BoosterHandle handle, const char *field, const char **features, const bst_ulong size)

在 Booster 中设置字符串编码的特征信息，类似于 DMatrix 中的特征信息。

接受的字段有

feature_name
feature_type

参数:

handle – 一个 Booster 实例
field – 字段名
features – 指向字符串数组的指针。
size – features 指针的大小 (传入的字符串数量)。

返回:

成功时为 0，失败时为 -1

int XGBoosterGetStrFeatureInfo(BoosterHandle handle, const char *field, bst_ulong *len, const char ***out_features)

从 Booster 获取字符串编码的特征信息，类似于 DMatrix 中的特征信息。

接受的字段有

feature_name
feature_type

调用者有责任在下次调用任何 XGBoost API 函数之前复制出数据。

参数:

handle – 一个 Booster 实例
field – 字段名
len – 输出指针 features 的大小（返回的字符串数量）。
out_features – 指向字符串数组指针的地址。结果存储在线程本地内存中。

返回:

成功时为 0，失败时为 -1

int XGBoosterFeatureScore(BoosterHandle handle, const char *config, bst_ulong *out_n_features, char const ***out_features, bst_ulong *out_dim, bst_ulong const **out_shape, float const **out_scores)

计算树模型的特征分数。当用于线性模型时，仅定义了 weight 重要性类型，对于多类别模型，输出分数为形状为 [n_features, n_classes] 的行主矩阵。对于树模型，out_n_feature 总是等于 out_n_scores 并有多种重要性类型定义。

参数:

handle – 一个 Booster 实例
config – 编码为 JSON 的计算分数的参数。接受的 JSON 键包括
- importance_type: 一个 JSON 字符串，其值可以是以下之一
  - ’weight’: 特征在所有树中用于分割数据的次数。
  - ’gain’: 特征在所有使用它的分割中的平均增益。
  - ’cover’: 特征在所有使用它的分割中的平均覆盖范围。
  - ’total_gain’: 特征在所有使用它的分割中的总增益。
  - ’total_cover’: 特征在所有使用它的分割中的总覆盖范围。
- feature_map: 一个可选的 JSON 字符串，包含特征映射文件的 URI 或路径。
- feature_names: 一个可选的 JSON 数组，包含每个特征的字符串名称。
out_n_features – 输出特征名称的长度。
out_features – 特征名称字符串数组，顺序与输出分数相同。
out_dim – 输出特征分数的维度。
out_shape – 输出特征分数的形状，长度为 out_dim。
out_scores – 形状为 out_shape 的浮点数数组，作为特征分数。

返回:

成功时为 0，失败时为 -1

预测

group Prediction

这些函数用于运行预测和解释算法。

函数

int XGBoosterPredict(BoosterHandle handle, DMatrixHandle dmat, int option_mask, unsigned ntree_limit, int training, bst_ulong *out_len, const float **out_result)

根据 dmat 进行预测（已弃用，请改用 XGBoosterPredictFromDMatrix）

已弃用

另请参阅

XGBoosterPredictFromDMatrix()

参数:

handle – 句柄
dmat – 数据矩阵
option_mask – 预测中使用的选项的位掩码，可能的值包括 0:正常预测 1:输出 margin 而非转换后的值 2:输出树的叶子索引而非叶子值，请注意叶子索引在每棵树中是唯一的 4:输出特征对个体预测的贡献
ntree_limit – 用于预测的树数量限制，仅对 boosted trees 有效，当参数设置为 0 时，将使用所有树
training – 预测函数是否作为训练循环的一部分使用。预测可以在两种场景下运行
1. 给定数据矩阵 X，从模型获取预测 y_pred。
2. 获取用于计算梯度的预测。例如，DART booster 在训练期间执行 dropout，由于丢弃的树，预测结果将与正常推断步骤获得的结果不同。对于第一种场景设置 training=false。对于第二种场景设置 training=true。第二种场景适用于定义自定义目标函数时。
out_len – 用于存储返回结果的长度
out_result – 用于设置指向数组的指针

返回:

成功时为 0，失败时为 -1

int XGBoosterPredictFromDMatrix(BoosterHandle handle, DMatrixHandle dmat, char const *config, bst_ulong const **out_shape, bst_ulong *out_dim, float const **out_result)

从 DMatrix 进行预测，替换 XGBoosterPredict。

“type”: [0, 6]

0: 正常预测
1: 输出 margin
2: 预测贡献
3: 预测近似贡献
4: 预测特征交互
5: 预测近似特征交互
6: 预测叶子 “training”: bool 预测函数是否作为训练循环的一部分使用。**不用于 inplace prediction**。

预测可以在两种场景下运行

给定数据矩阵 X，从模型获取预测 y_pred。
获取用于计算梯度的预测。例如，DART booster 在训练期间执行 dropout，由于丢弃的树，预测结果将与正常推断步骤获得的结果不同。对于第一种场景设置 training=false。对于第二种场景设置 training=true。第二种场景适用于定义自定义目标函数时。“iteration_begin”: int 预测的起始迭代。“iteration_end”: int 预测的结束迭代。设置为 0 则将成为树模型的尺寸（所有树）。“strict_shape”: bool 是否应使用更严格的规则重塑输出。如果设置为 true，normal/margin/contrib/interaction 预测将输出一致的形状，无论是否使用多类别模型，并且 leaf 预测将输出表示为 (n_samples, n_iterations, n_classes, n_trees_in_forest) 的 4 维数组。

运行带有严格输出形状的正常预测的 JSON 输入示例，对于 softprob 为 2 维，对于其他为 1 维。

 {
    "type": 0,
    "training": false,
    "iteration_begin": 0,
    "iteration_end": 0,
    "strict_shape": true
}

另请参阅

XGBoosterPredictFromDense XGBoosterPredictFromCSR XGBoosterPredictFromCudaArray XGBoosterPredictFromCudaColumnar

参数:

handle – Booster 句柄
dmat – DMatrix 句柄
config – JSON 格式的字符串编码预测配置，JSON 对象包含以下可用字段
out_shape – 输出预测的形状（使用前复制）。
out_dim – 输出预测的维度。
out_result – 存储预测值的缓冲区（使用前复制）。

返回:

成功时为 0，失败时为 -1

int XGBoosterPredictFromDense(BoosterHandle handle, char const *values, char const *config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)

从 CPU 密集矩阵进行原地（Inplace）预测。

注意

如果 booster 配置为在 CUDA 设备上运行，XGBoost 将回退到使用 DMatrix 运行预测，并发出性能警告。

参数:

handle – Booster 句柄。
values – JSON 编码的表示值的 **array_interface**。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。inplace prediction 的附加字段包括
- ”missing”: float
m – 一个可选的（如果不可用则为 NULL）存储元信息的代理 DMatrix 实例。
out_shape – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_dim – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_result – 更多信息请参阅 XGBoosterPredictFromDMatrix。

返回:

成功时为 0，失败时为 -1

int XGBoosterPredictFromColumnar(BoosterHandle handle, char const *values, char const *config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)

从 CPU 列式数据进行原地（Inplace）预测。(表格)

注意

如果 booster 配置为在 CUDA 设备上运行，XGBoost 将回退到使用 DMatrix 运行预测，并发出性能警告。

参数:

handle – Booster 句柄。
data – 更多信息请参阅 XGDMatrixCreateFromColumnar。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。inplace prediction 的附加字段包括
- ”missing”: float
m – 一个可选的（如果不可用则为 NULL）存储元信息的代理 DMatrix 实例。
out_shape – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_dim – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_result – 更多信息请参阅 XGBoosterPredictFromDMatrix。

返回:

成功时为 0，失败时为 -1

int XGBoosterPredictFromCSR(BoosterHandle handle, char const *indptr, char const *indices, char const *values, bst_ulong ncol, char const *config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)

从 CPU CSR 矩阵进行原地（Inplace）预测。

注意

如果 booster 配置为在 CUDA 设备上运行，XGBoost 将回退到使用 DMatrix 运行预测，并发出性能警告。

参数:

handle – Booster 句柄。
indptr – CSR 中行指针的 JSON 编码 **array_interface**。
indices – 指向 CSR 中列索引的 JSON 编码 array_interface。
values – CSR 中值的 JSON 编码 **array_interface**。
ncol – 数据中的特征数量。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。inplace prediction 的附加字段包括
- ”missing”: float
m – 一个可选的（如果不可用则为 NULL）存储元信息的代理 DMatrix 实例。
out_shape – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_dim – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_result – 更多信息请参阅 XGBoosterPredictFromDMatrix。

返回:

成功时为 0，失败时为 -1

int XGBoosterPredictFromCudaArray(BoosterHandle handle, char const *values, char const *config, DMatrixHandle proxy, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)

从 CUDA 密集矩阵（Python 中的 cupy）进行原地（Inplace）预测。

注意

如果 booster 配置为在 CPU 上运行，XGBoost 将回退到使用 DMatrix 运行预测，并发出性能警告。

参数:

handle – Booster 句柄
values – JSON 编码的表示值的 **cuda_array_interface**。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。inplace prediction 的附加字段包括
- ”missing”: float
proxy – 一个可选的（如果不可用则为 NULL）存储元信息的代理 DMatrix 实例。
out_shape – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_dim – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_result – 更多信息请参阅 XGBoosterPredictFromDMatrix。

返回:

成功时为 0，失败时为 -1

int XGBoosterPredictFromCudaColumnar(BoosterHandle handle, char const *data, char const *config, DMatrixHandle proxy, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)

从 CUDA 密集 dataframe（Python 中的 cuDF）进行原地（Inplace）预测。

注意

如果 booster 配置为在 CPU 上运行，XGBoost 将回退到使用 DMatrix 运行预测，并发出性能警告。

参数:

handle – Booster 句柄
data – 更多信息请参阅 XGDMatrixCreateFromColumnar。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。inplace prediction 的附加字段包括
- ”missing”: float
proxy – 一个可选的（如果不可用则为 NULL）存储元信息的代理 DMatrix 实例。
out_shape – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_dim – 更多信息请参阅 XGBoosterPredictFromDMatrix。
out_result – 更多信息请参阅 XGBoosterPredictFromDMatrix。

返回:

成功时为 0，失败时为 -1

序列化

group Serialization

根据用例，有多种方法可以序列化 Booster 对象。

序列化 API 的简短说明。共有 3 组不同的序列化 API。

带有术语“Model”的函数处理 XGBoost 模型的保存/加载，例如树或线性权重。它们剥离了诸如训练算法或 CUDA 设备 ID 之类的参数配置。这些函数旨在允许用户将训练好的模型用于不同的任务，例如预测、训练继续或模型解释。
带有术语“Config”的函数处理配置的保存/加载。它有助于用户研究 XGBoost 的内部结构。用户还可以使用加载方法以结构化的方式指定参数。这些函数在 1.0.0 中引入，目前尚不稳定。
包含术语“序列化”（Serialization）的函数结合了以上两点。它们用于诸如检查点（check-pointing）或在分布式环境中继续训练任务的情况。在这些情况下，任务必须在没有任何用户干预的情况下执行。

函数

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

从现有文件加载模型。

参数:

handle – 句柄
fname – 文件 URI 或文件名。字符串必须是 UTF-8 编码。

返回:

成功时为 0，失败时为 -1

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

将模型保存到现有文件。

参数:

handle – 句柄
fname – 文件 URI 或文件名。字符串必须是 UTF-8 编码。

返回:

成功时为 0，失败时为 -1

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

从内存缓冲区加载模型

参数:

handle – 句柄
buf – 指向缓冲区的指针
len – 缓冲区的长度

返回:

成功时为 0，失败时为 -1

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

将模型保存为原始字节，返回数组头部。用户在下次调用 xgboost 之前必须将结果复制出来。

参数:

handle – 句柄
config – 存储函数参数的 JSON 编码字符串。JSON 文档中应包含以下键
- ”format”: str
  - json: 输出的 booster 将编码为 JSON。
  - ubj: 输出的 booster 将编码为 Universal binary JSON。出于兼容性原因保留此格式。
out_len – 用于存放输出长度的参数
out_dptr – 用于存放输出数据指针的参数

返回:

成功时为 0，失败时为 -1

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

基于内存快照的序列化方法。将所有状态保存到缓冲区。

参数:

handle – 句柄
out_len – 保存输出长度的参数
out_dptr – 用于存放输出数据指针的参数

返回:

成功时为 0，失败时为 -1

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

基于内存快照的序列化方法。加载 XGBoosterSerializeToBuffer 返回的缓冲区。

参数:

handle – 句柄
buf – 指向缓冲区的指针
len – 缓冲区的长度

返回:

成功时为 0，失败时为 -1

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

将 XGBoost 的内部配置保存为 JSON 文档。目前此支持处于实验阶段，将来可能会更改函数签名而不另行通知。

参数:

handle – Booster 对象的句柄。
out_len – 输出字符串的长度
out_str – 指向字符数组的有效指针。字符数组由 XGBoost 分配和管理，而指向该数组的指针需要由调用方管理。

返回:

成功时为 0，失败时为 -1

int XGBoosterLoadJsonConfig(BoosterHandle handle, char const *config)

从 JSON 文档加载 XGBoost 的内部配置。目前此支持处于实验阶段，将来可能会更改函数签名而不另行通知。

参数:

handle – Booster 对象的句柄。
config – JSON 文档的字符串表示。

返回:

成功时为 0，失败时为 -1

集体操作（Collective）

group Collective

暴露 XGBoost 内部通信器的实验性支持。

XGBoost 中的集体通信器从 dmlc 的 rabit 项目演变而来，但在采用后发生了显著变化。它由一个跟踪器 (tracker) 和一组工作进程 (worker) 组成。跟踪器负责启动通信组并处理诸如日志记录等集中式任务。工作进程是实际执行集体任务（如 allreduce）的通信器。

要使用集体实现，首先需要用相应的参数创建一个跟踪器，然后使用 XGTrackerWorkerArgs() 获取工作进程的参数。获得的参数可以传递给 XGCommunicatorInit() 函数。XGCommunicatorInit() 的调用必须伴随 XGCommunicatorFinalize() 调用进行清理。请注意，通信器在 C++ 中使用 std::thread，由于运行时关闭序列，在 C++ 析构函数中存在未定义行为。最好在运行时关闭之前调用 XGCommunicatorFinalize()。此要求类似于 Python 的线程或套接字，在 __del__ 函数中不应依赖它们。

由于它是 XGBoost 的一部分，调用 XGBoost 函数时会返回错误，例如，训练一个 booster 可能会返回连接错误。

注意

此功能仍在开发中。

类型定义

typedef void *TrackerHandle

跟踪器的句柄。

XGBoost 中目前有两种类型的跟踪器，第一种是 rabit，另一种是 federated。rabit 用于常规的集体通信，而 federated 用于联邦学习。

函数

int XGTrackerCreate(char const *config, TrackerHandle *handle)

创建一个新的跟踪器。

dmlc_communicator: String，要创建的跟踪器类型。可用选项为 rabit 和 federated。更多信息请参阅 TrackerHandle。
n_workers: Integer，工作进程数量。
port: (可选) Integer，此跟踪器应监听的端口。
timeout: (可选) Integer，各种网络操作的超时时间（秒）。默认为 300 秒。

一些配置是 rabit 特定的

host: (可选) String，由 rabit 跟踪器使用，用于指定主机地址。当通信器无法可靠地获取主机地址时，这会很有用。
sortby: (可选) Integer。
- 0: 按主机名对工作进程排序。
- 1: 按任务 ID 对工作进程排序。

一些 federated 特定的配置

federated_secure: Boolean，是否是安全服务器。为 False 表示用于测试。
server_key_path: 服务器密钥的路径。仅在是安全服务器时使用。
server_cert_path: 服务器证书的路径。仅在是安全服务器时使用。
client_cert_path: 客户端证书的路径。仅在是安全服务器时使用。

参数:

config – JSON 编码参数。
handle – 创建的跟踪器的句柄。

返回:

0 表示成功，-1 表示失败。

int XGTrackerWorkerArgs(TrackerHandle handle, char const **args)

获取运行工作进程所需的参数。这应该在调用 XGTrackerRun() 后调用。

参数:

handle – 跟踪器的句柄。
args – 作为 JSON 文档返回的参数。

返回:

0 表示成功，-1 表示失败。

int XGTrackerRun(TrackerHandle handle, char const *config)

启动跟踪器。跟踪器在后台运行，此函数在跟踪器启动后立即返回。

参数:

handle – 跟踪器的句柄。
config – 目前未使用，保留供将来使用。

返回:

0 表示成功，-1 表示失败。

int XGTrackerWaitFor(TrackerHandle handle, char const *config)

等待跟踪器完成，应在调用 XGTrackerRun() 后调用。此函数将阻塞，直到跟踪器任务完成或达到超时。

参数:

handle – 跟踪器的句柄。
config – JSON 编码配置。目前不需要参数，保留供将来使用。

返回:

0 表示成功，-1 表示失败。

int XGTrackerFree(TrackerHandle handle)

释放跟踪器实例。这应在调用 XGTrackerWaitFor() 后调用。如果跟踪器没有正确等待，此函数将关闭与跟踪器的所有连接，可能导致未定义行为。

参数:: handle – 跟踪器的句柄。
返回:: 0 表示成功，-1 表示失败。

int XGCommunicatorInit(char const *config)

初始化集体通信器。

目前通信器 API 处于实验阶段，将来可能会更改函数签名而不另行通知。

在使用任何功能之前，在工作进程中调用此函数一次。请确保在使用后调用 XGCommunicatorFinalize()。初始化的通信器是全局线程局部变量。

仅适用于 rabit 通信器

dmlc_tracker_uri: 跟踪器的主机名或 IP 地址。
dmlc_tracker_port: 跟踪器的端口号。
dmlc_task_id: 当前任务的 ID，可用于获取确定性的秩分配。
dmlc_retry: 连接失败的重试次数。
dmlc_timeout: 超时时间（秒）。
dmlc_nccl_path: nccl 共享库 libnccl.so 的路径。

仅适用于 federated 通信器（环境变量使用大写，运行时配置使用小写）

federated_server_address: 联邦服务器的地址。
federated_world_size: 联邦工作进程的数量。
federated_rank: 当前工作进程的秩。
federated_server_cert_path: 服务器证书文件路径。仅在 SSL 模式下需要。
federated_client_key_path: 客户端密钥文件路径。仅在 SSL 模式下需要。
federated_client_cert_path: 客户端证书文件路径。仅在 SSL 模式下需要。

参数:

config – JSON 编码配置。接受的 JSON 键包括

dmlc_communicator: 通信器的类型，应与跟踪器类型匹配。
- rabit: 使用 Rabit。如果未指定类型，则这是默认值。
- federated: 使用 gRPC 接口进行联邦学习。

返回:

0 表示成功，-1 表示失败。

int XGCommunicatorFinalize(void)

结束集体通信器。

完成所有任务后调用此函数。

返回:: 0 表示成功，-1 表示失败。

int XGCommunicatorGetRank(void)

获取当前进程的秩。

返回:: 工作进程的秩。

int XGCommunicatorGetWorldSize(void)

获取总进程数。

返回:: 总世界大小（进程数）。

int XGCommunicatorIsDistributed(void)

获取通信器是否是分布式的。

返回:: 如果通信器是分布式模式，则为 True。

int XGCommunicatorPrint(char const *message)

向跟踪器打印消息。

此函数可用于向监视跟踪器的用户传递进度信息。

参数:: message – 要打印的消息。
返回:: 0 表示成功，-1 表示失败。

int XGCommunicatorGetProcessorName(const char **name_str)

获取处理器的名称。

参数:: name_str – 指向接收到的返回处理器名称的指针。
返回:: 0 表示成功，-1 表示失败。

int XGCommunicatorBroadcast(void *send_receive_buffer, size_t size, int root)

从根进程向所有其他进程广播内存区域。此函数不是线程安全的。

示例

int a = 1;
Broadcast(&a, sizeof(a), root);

参数:

send_receive_buffer – 发送或接收缓冲区的指针。
size – 数据的大小（字节）。
root – 进行广播的进程秩。

返回:

0 表示成功，-1 表示失败。

int XGCommunicatorAllreduce(void *send_receive_buffer, size_t count, int data_type, int op)

执行就地 allreduce。此函数不是线程安全的。

示例用法：以下代码计算结果的总和

enum class Op {
    kMax = 0, kMin = 1, kSum = 2, kBitwiseAND = 3, kBitwiseOR = 4, kBitwiseXOR = 5
};
std::vector<int> data(10);
...
Allreduce(data.data(), data.size(), DataType:kInt32, Op::kSum);
...

参数:

send_receive_buffer – 用于发送和接收数据的缓冲区。
count – 要归约（reduce）的元素数量。
data_type – 数据类型枚举，请参阅 communicator.h 中的 xgboost::collective::DataType。
op – 操作类型枚举，请参阅 communicator.h 中的 xgboost::collective::Operation。

返回:

0 表示成功，-1 表示失败。