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 XGDMatrixCreateFromColumnar(char const *data, char const *config, DMatrixHandle *out)

从列式数据创建 DMatrix。（表格）

DMatrix的一种特殊输入是列式格式，它指的是基于列的数据帧。XGBoost 可以接受整数和浮点数等数值数据类型，以及分类类型（在 arrow 术语中称为字典）。分类类型是在 3.1.0 中引入的。数据帧由一个列表数组接口表示，每个列有一个对象。

分类类型由 3 个缓冲区表示：有效性掩码、类别的名称（对于大多数数据帧实现，称为索引）以及用于表示行中类别的代码。XGBoost 通过接受列表中两个 JSON 编码的 arrow 数组来使用分类列。列表中的第一项是一个 JSON 对象，包含 {"offsets": IntegerArray, "values": StringArray }，表示由 arrow 列式格式定义的字符串名称。第二个缓冲区是一个掩码整数数组，用于存储分类代码和有效性掩码。

[
  // categorical column, represented as an array (list)
  [
    {
      'offsets':
      {
        'data': (129412626415808, True),
        'typestr': '<i4', 'version': 3, 'strides': None, 'shape': (3,), 'mask': None
      },
      'values':
      {
        'data': (129412626416000, True),
        'typestr': '<i1', 'version': 3, 'strides': None, 'shape': (7,), 'mask': None
      }
    },
    {
      'data': (106200854378448, True),
      'typestr': '<i1', 'version': 3, 'strides': None, 'shape': (2,), 'mask': None
    }
  ],
  // numeric column, represented as an object, same number of rows as the previous column (2)
  {
    'data': (106200854378448, True),
    'typestr': '<f4', 'version': 3, 'strides': None, 'shape': (2,), 'mask': None
  }
]

对于数值输入，它与密集数组相同。

参数:

data – JSON 编码数组接口的列表。
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 – JSON 编码的 array_interface，指向 CSR 中的行指针。
indices – JSON 编码的 array_interface，指向 CSR 中的列索引。
data – JSON 编码的 array_interface，指向 CSR 中的值。
ncol – 列数。
config – 有关详细信息，请参阅XGDMatrixCreateFromDense。
out – 创建的 dmatrix

返回:

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

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

从密集数组创建 DMatrix。

数组接口定义在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 – JSON 编码的 array_interface，指向 CSC 中的列指针。
indices – JSON 编码的 array_interface，指向 CSC 中的行索引。
data – JSON 编码的 array_interface，指向 CSC 中的值。
nrow – 矩阵中的行数。
config – 有关详细信息，请参阅XGDMatrixCreateFromDense。
out – 创建的 dmatrix。

返回:

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

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 编码数组接口的列表。
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, char const *field, char const *data)

将数组接口中的内容设置为信息中的内容。

参数:

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

返回:

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

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

将浮点向量设置为信息中的内容

参数:

handle – 数据矩阵实例
field – 字段名，可以是标签、权重
array – 指向浮点向量的指针
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)

从矩阵获取浮点信息向量。

参数:

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

获取 DMatrix 中的预测器作为 CSR 矩阵进行测试。如果这是一个量化 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__ 表示。

流式传输

group Streaming

分位数 DMatrix 和外部内存 DMatrix 可以从批量数据创建。

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

XGBCallbackSetData
XGBCallbackDataIterNext
XGDMatrixCreateFromDataIter

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

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

工厂函数

用于外部内存的XGDMatrixCreateFromCallback
用于分位数 DMatrix 的XGQuantileDMatrixCreateFromCallback
用于外部内存分位数 DMatrix 的XGExtMemQuantileDMatrixCreateFromCallback

类型定义

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

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

typedef int XGBCallbackSetData(DataHolderHandle handle, XGBoostBatchCSR batch)

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

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

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

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

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

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

typedef int XGDMatrixCallbackNext(DataIterHandle iter)

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

Param iter:: 用户定义迭代器的句柄。
Return:: 成功时为 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：将迭代器句柄、代理句柄和两个方法以及其他参数（编码为 JSON 对象）传递给XGDMatrixCreateFromCallback。
步骤 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 树方法（tree method）的简要说明。

步骤 0：定义一个具有reset和next两个方法的迭代器。
步骤 1：通过XGProxyDMatrixCreate创建一个 DMatrix 代理并持有其句柄。
步骤2：将迭代器句柄、代理句柄和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。

cache_host_ratio (可选): 对于基于 GPU 的输入，XGBoost 可以将缓存分成主机和设备部分，以减少数据传输开销。此参数指定主机缓存相对于整个缓存的大小：host / (host + device)。

自: 3.0.0

注意

这是实验性功能，可能会更改。

参数:

out – 创建的Quantile DMatrix。
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（无限制）。

返回:

成功返回 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 – JSON 编码的数组接口字符串表示，以 null 结尾。

返回:

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

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

在DMatrix代理上设置数据。

参数:

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

返回:

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

struct XGBoostBatchCSR: #include <c_api.h>

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

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

删除增强器。

参数:: 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)

获取梯度增强器中增强轮次数量。当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:输出边距而非转换值 2:输出树的叶子索引而非叶子值，注意叶子索引每棵树都是唯一的 4:输出特征对个体预测的贡献
ntree_limit – 限制用于预测的树的数量，仅对增强树有效，当参数设置为0时，将使用所有树
training – 预测函数是否作为训练循环的一部分使用。预测可以在两种情况下运行
1. 给定数据矩阵 X，从模型中获取预测 y_pred。
2. 获取用于计算梯度的预测。例如，DART增强器在训练期间执行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: 输出边距
2: 预测贡献
3: 预测近似贡献
4: 预测特征交互
5: 预测近似特征交互
6: 预测叶子 “training”: bool 预测函数是否作为训练循环的一部分使用。不用于就地预测。

预测可以在两种情况下运行

给定数据矩阵 X，从模型中获取预测 y_pred。
获取用于计算梯度的预测。例如，DART增强器在训练期间执行dropout，并且由于丢弃的树，预测结果将与正常推理步骤获得的结果不同。第一种情况设置为training=false。第二种情况设置为training=true。第二种情况适用于您定义自定义目标函数时。“iteration_begin”: int 预测的开始迭代。“iteration_end”: int 预测的结束迭代。设置为0将成为树模型的大小（所有树）。“strict_shape”: bool 是否应使用更严格的规则重塑输出。如果设置为true，normal/margin/contrib/interaction预测将输出一致的形状，无论是否使用多类别模型，并且叶子预测将输出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稠密矩阵进行就地预测。

注意

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

参数:

handle – Booster 句柄。
values – JSON 编码的 array_interface 到值。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。就地预测的附加字段是
- ”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 列式数据（表）进行就地预测。

注意

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

参数:

handle – Booster 句柄。
data – 详情请参阅 XGDMatrixCreateFromColumnar。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。就地预测的附加字段是
- ”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 矩阵进行就地预测。

注意

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

参数:

handle – Booster 句柄。
indptr – JSON 编码的 array_interface 到 CSR 中的行指针。
indices – JSON 编码的 array_interface，指向 CSR 中的列索引。
values – JSON 编码的 array_interface 到 CSR 中的值。
ncol – 数据中的特征数量。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。就地预测的附加字段是
- ”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）进行就地预测。

注意

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

参数:

handle – Booster 句柄
values – JSON 编码的 cuda_array_interface 到值。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。就地预测的附加字段是
- ”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 稠密数据帧（Python 中的 cuDF）进行就地预测。

注意

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

参数:

handle – Booster 句柄
data – 详情请参阅 XGDMatrixCreateFromColumnar。
config – 更多信息请参阅 XGBoosterPredictFromDMatrix。就地预测的附加字段是
- ”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”一词的函数是上述两者的结合。它们用于检查点或在分布式环境中继续训练任务等情况。在这些情况下，任务必须在没有任何用户干预的情况下执行。

函数

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

从现有文件加载模型。

参数:

handle – 句柄
fname – 文件名。字符串必须采用 UTF-8 编码。

返回:

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

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

将模型保存到现有文件。

参数:

handle – 句柄
fname – 文件名。字符串必须采用 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: 输出增强器将编码为 JSON。
  - ubj: 输出增强器将编码为通用二进制 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

集体

group Collective

XGBoost 中公开内部通信器的实验性支持。

XGBoost 中的集体通信器从 dmlc 的 rabit 项目演变而来，但自采用以来已发生显著变化。它由一个追踪器和一组工作器组成。追踪器负责引导通信组并处理日志记录等集中任务。工作器是执行 allreduce 等集体任务的实际通信器。

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

由于它作为 XGBoost 的一部分使用，因此当调用 XGBoost 函数时会返回错误，例如，训练增强器可能会返回连接错误。

注意

这仍在开发中。

类型定义

typedef void *TrackerHandle

追踪器的句柄。

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

函数

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

创建新的追踪器。

dmlc_communicator: 字符串，要创建的追踪器类型。可用选项为 rabit 和 federated。有关详细信息，请参见 TrackerHandle。
n_workers: 整数，工作器数量。
port: (可选) 整数，此追踪器应监听的端口。
timeout: (可选) 整数，各种网络操作的超时时间（秒）。默认值为 300 秒。

某些配置是 rabit 特定的

host: (可选) 字符串，由 rabit 追踪器使用，用于指定主机地址。当通信器无法可靠获取主机地址时，这可能很有用。
sortby: (可选) 整数。
- 0: 按主机名对工作器进行排序。
- 1: 按任务 ID 对工作器进行排序。

某些 federated 特定的配置

federated_secure: 布尔值，这是否是安全服务器。测试时为 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 – 要约简的元素数量。
data_type – 数据类型枚举，参见 communicator.h 中的 xgboost::collective::DataType。
op – 操作类型枚举，参见 communicator.h 中的 xgboost::collective::Operation。

返回:

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