C API

版权

Copyright (c) 2016 Microsoft Corporation. 保留所有权利。根据 MIT 许可证授权。有关许可证信息,请参阅项目根目录下的 LICENSE 文件。

注意

为了避免在大数据上进行类型转换,我们的大部分公开接口都支持 float32 和 float64,以下情况除外:

  1. 梯度和 Hessian;

  2. 训练和验证数据的当前分数。

原因是它们会被频繁调用,对其进行类型转换可能耗费时间。

定义

C_API_DTYPE_FLOAT32 (0)

float32 (单精度浮点数)。

C_API_DTYPE_FLOAT64 (1)

float64 (双精度浮点数)。

C_API_DTYPE_INT32 (2)

int32。

C_API_DTYPE_INT64 (3)

int64。

C_API_FEATURE_IMPORTANCE_GAIN (1)

增益类型的特征重要性。

C_API_FEATURE_IMPORTANCE_SPLIT (0)

分裂类型的特征重要性。

C_API_MATRIX_TYPE_CSC (1)

CSC 稀疏矩阵类型。

C_API_MATRIX_TYPE_CSR (0)

CSR 稀疏矩阵类型。

C_API_PREDICT_CONTRIB (3)

预测特征贡献 (SHAP 值)。

C_API_PREDICT_LEAF_INDEX (2)

预测叶子索引。

C_API_PREDICT_NORMAL (0)

常规预测,带转换(如果需要)。

C_API_PREDICT_RAW_SCORE (1)

预测原始分数。

INLINE_FUNCTION inline

内联说明符。

THREAD_LOCAL thread_local

线程本地说明符。

类型定义

typedef void *BoosterHandle

booster 句柄。

typedef void *ByteBufferHandle

ByteBuffer 句柄。

typedef void *DatasetHandle

dataset 句柄。

typedef void *FastConfigHandle

FastConfig 句柄。

函数

static char *LastErrorMsg()

错误消息句柄。

返回值:

错误消息

LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle, const DatasetHandle valid_data)

向 booster 添加新的验证数据。

参数:
  • handle – booster 句柄

  • valid_data – 验证数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle, int num_row, int predict_type, int start_iteration, int num_iteration, int64_t *out_len)

获取预测数量。

参数:
  • handle – booster 句柄

  • num_row – 行数

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 用于预测的迭代次数,<= 0 表示无限制

  • out_len[out] 预测结果的长度

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data, const char *parameters, BoosterHandle *out)

创建一个新的 boosting 学习器。

参数:
  • train_data – 训练数据集

  • parameters – 参数,格式为 ‘key1=value1 key2=value2’

  • out[out] 创建的 booster 句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(const char *filename, int *out_num_iterations, BoosterHandle *out)

从模型文件加载现有的 booster。

参数:
  • filename – 模型文件名

  • out_num_iterations[out] 此 booster 的迭代次数

  • out[out] 创建的 booster 句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle, int start_iteration, int num_iteration, int feature_importance_type, int64_t buffer_len, int64_t *out_len, char *out_str)

将模型导出为 JSON。

参数:
  • handle – booster 句柄

  • start_iteration – 应导出的迭代的起始索引

  • num_iteration – 应导出的迭代索引,<= 0 表示导出所有迭代

  • feature_importance_type – 特征重要性类型,可以是 C_API_FEATURE_IMPORTANCE_SPLITC_API_FEATURE_IMPORTANCE_GAIN

  • buffer_len – 字符串缓冲区长度,如果 buffer_len < out_len,则应重新分配缓冲区

  • out_len[out] 实际输出长度

  • out_str[out] 模型的 JSON 格式字符串,应预分配内存

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle, int num_iteration, int importance_type, double *out_results)

获取模型特征重要性。

参数:
  • handle – booster 句柄

  • num_iteration – 计算特征重要性的迭代次数,<= 0 表示使用所有迭代

  • importance_type – 重要性计算方法

    • C_API_FEATURE_IMPORTANCE_SPLIT: 结果包含特征在模型中使用次数;

    • C_API_FEATURE_IMPORTANCE_GAIN: 结果包含使用该特征进行分裂的总增益

  • out_results[out] 包含特征重要性的结果数组

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle)

释放 booster 占用的空间。

参数:
  • handle – 待释放的 booster 句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterFreePredictSparse(void *indptr, int32_t *indices, void *data, int indptr_type, int data_type)

对应于 LGBM_BoosterPredictSparseOutput 的方法,用于释放已分配的数据。

参数:
  • indptr – 指向待释放的输出行头或列头的指针

  • indices – 指向待释放的稀疏索引的指针

  • data – 指向待释放的稀疏数据空间的指针

  • indptr_typeindptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle, int *out_iteration)

获取当前提升迭代的索引。

参数:
  • handle – booster 句柄

  • out_iteration[输出] 当前提升迭代的索引

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle, int data_idx, int *out_len, double *out_results)

获取训练数据和验证数据的评估结果。

注意

  1. 您应首先调用 LGBM_BoosterGetEvalNames 来获取评估指标的名称。

  2. 您应为 out_results 预分配内存,其长度可通过 LGBM_BoosterGetEvalCounts 获取。

参数:
  • handle – booster 句柄

  • data_idx – 数据的索引,0:训练数据,1:第1个验证数据,2:第2个验证数据,依此类推

  • out_len[输出] 输出结果的长度

  • out_results[输出] 包含评估结果的数组

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle, int *out_len)

获取评估指标的数量。

参数:
  • handle – booster 句柄

  • out_len[输出] 评估指标的总数

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle, const int len, int *out_len, const size_t buffer_len, size_t *out_buffer_len, char **out_strs)

获取评估指标的名称。

参数:
  • handle – booster 句柄

  • len – 存储在 out_strschar* 指针数量。如果小于最大大小,则只复制这些数量的字符串

  • out_len[输出] 评估指标的总数

  • buffer_len – 预分配字符串的大小。内容将被复制到 buffer_len - 1 处并以 null 终止

  • out_buffer_len[输出] 执行完整字符串复制所需的字符串大小

  • out_strs[输出] 评估指标的名称,应预分配内存

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle, const int len, int *out_len, const size_t buffer_len, size_t *out_buffer_len, char **out_strs)

获取特征名称。

参数:
  • handle – booster 句柄

  • len – 存储在 out_strschar* 指针数量。如果小于最大大小,则只复制这些数量的字符串

  • out_len[输出] 特征总数

  • buffer_len – 预分配字符串的大小。内容将被复制到 buffer_len - 1 处并以 null 终止

  • out_buffer_len[输出] 执行完整字符串复制所需的字符串大小

  • out_strs[输出] 特征名称,应预分配内存

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle, int tree_idx, int leaf_idx, double *out_val)

获取叶子值。

参数:
  • handle – booster 句柄

  • tree_idx – 树的索引

  • leaf_idx – 叶子的索引

  • out_val[输出] 指定叶子的输出结果

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetLinear(BoosterHandle handle, int *out)

获取表示 booster 是否正在拟合线性树的整数值。

参数:
  • handle – booster 句柄

  • out[输出] 保存线性树指示符的地址

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetLoadedParam(BoosterHandle handle, int64_t buffer_len, int64_t *out_len, char *out_str)

获取作为 JSON 字符串的参数。

参数:
  • handle – booster 句柄

  • buffer_len – 为字符串分配的空间

  • out_len[输出] 字符串的实际大小

  • out_str[输出] 包含参数的 JSON 字符串

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetLowerBoundValue(BoosterHandle handle, double *out_results)

获取模型的下界值。

参数:
  • handle – booster 句柄

  • out_results[输出] 指向最小值的引用

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle, int *out_len)

获取类别数量。

参数:
  • handle – booster 句柄

  • out_len[输出] 类别数量

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle, int *out_len)

获取特征数量。

参数:
  • handle – booster 句柄

  • out_len[输出] 特征总数

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle, int data_idx, int64_t *out_len)

获取训练数据和验证数据的预测数量(可用于支持自定义评估函数)。

参数:
  • handle – booster 句柄

  • data_idx – 数据的索引,0:训练数据,1:第1个验证数据,2:第2个验证数据,依此类推

  • out_len[输出] 预测数量

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle, int data_idx, int64_t *out_len, double *out_result)

获取训练数据和验证数据的预测结果。

注意

您应为 out_result 预分配内存,其长度等于 num_class * num_data

参数:
  • handle – booster 句柄

  • data_idx – 数据的索引,0:训练数据,1:第1个验证数据,2:第2个验证数据,依此类推

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterGetUpperBoundValue(BoosterHandle handle, double *out_results)

获取模型的上界值。

参数:
  • handle – booster 句柄

  • out_results[输出] 指向最大值的引用

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(const char *model_str, int *out_num_iterations, BoosterHandle *out)

从字符串加载现有的 booster。

参数:
  • model_str – 模型字符串

  • out_num_iterations[out] 此 booster 的迭代次数

  • out[out] 创建的 booster 句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle, BoosterHandle other_handle)

将模型从 other_handle 合并到 handle 中。

参数:
  • handle – booster 句柄,将把另一个 booster 合并到此句柄中

  • other_handle – 其他 booster 句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterNumberOfTotalModel(BoosterHandle handle, int *out_models)

获取弱子模型的数量。

参数:
  • handle – booster 句柄

  • out_models[输出] 弱子模型的数量

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterNumModelPerIteration(BoosterHandle handle, int *out_tree_per_iteration)

获取每次迭代的树数量。

参数:
  • handle – booster 句柄

  • out_tree_per_iteration[输出] 每次迭代的树数量

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForArrow(BoosterHandle handle, int64_t n_chunks, const ArrowArray *chunks, const ArrowSchema *schema, int predict_type, int start_iteration, int num_iteration, const char *parameter, int64_t *out_len, double *out_result)

为新数据集进行预测。

注意

您应为 out_result 预分配内存

  • 对于常规和原始分数,其长度等于 num_class * num_data

  • 对于叶子索引,其长度等于 num_class * num_data * num_iteration

  • 对于特征贡献,其长度等于 num_class * num_data * (num_feature + 1)

参数:
  • handle – booster 句柄

  • n_chunks – 传递给此函数的 Arrow 数组数量

  • chunks – 指向 Arrow 数组列表的指针

  • schema – 指向所有 Arrow 数组的模式的指针

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle, const void *col_ptr, int col_ptr_type, const int32_t *indices, const void *data, int data_type, int64_t ncol_ptr, int64_t nelem, int64_t num_row, int predict_type, int start_iteration, int num_iteration, const char *parameter, int64_t *out_len, double *out_result)

为 CSC 格式的新数据集进行预测。

注意

您应为 out_result 预分配内存

  • 对于常规和原始分数,其长度等于 num_class * num_data

  • 对于叶子索引,其长度等于 num_class * num_data * num_iteration

  • 对于特征贡献,其长度等于 num_class * num_data * (num_feature + 1)

参数:
  • handle – booster 句柄

  • col_ptr – 指向列头的指针

  • col_ptr_typecol_ptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 指向行索引的指针

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • ncol_ptr – 矩阵中的列数 + 1

  • nelem – 矩阵中的非零元素数量

  • num_row – 行数

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle, const void *indptr, int indptr_type, const int32_t *indices, const void *data, int data_type, int64_t nindptr, int64_t nelem, int64_t num_col, int predict_type, int start_iteration, int num_iteration, const char *parameter, int64_t *out_len, double *out_result)

为 CSR 格式的新数据集进行预测。

注意

您应为 out_result 预分配内存

  • 对于常规和原始分数,其长度等于 num_class * num_data

  • 对于叶子索引,其长度等于 num_class * num_data * num_iteration

  • 对于特征贡献,其长度等于 num_class * num_data * (num_feature + 1)

参数:
  • handle – booster 句柄

  • indptr – 指向行头的指针

  • indptr_typeindptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 指向列索引的指针

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nindptr – 矩阵中的行数 + 1

  • nelem – 矩阵中的非零元素数量

  • num_col – 列数

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 用于预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRow(BoosterHandle handle, const void *indptr, int indptr_type, const int32_t *indices, const void *data, int data_type, int64_t nindptr, int64_t nelem, int64_t num_col, int predict_type, int start_iteration, int num_iteration, const char *parameter, int64_t *out_len, double *out_result)

为 CSR 格式的新数据集进行预测。此方法重用先前调用中的内部预测器结构,并针对单行调用进行了优化。

注意

您应为 out_result 预分配内存

  • 对于常规和原始分数,其长度等于 num_class * num_data

  • 对于叶子索引,其长度等于 num_class * num_data * num_iteration

  • 对于特征贡献,其长度等于 num_class * num_data * (num_feature + 1)

参数:
  • handle – booster 句柄

  • indptr – 指向行头的指针

  • indptr_typeindptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 指向列索引的指针

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nindptr – 矩阵中的行数 + 1

  • nelem – 矩阵中的非零元素数量

  • num_col – 列数

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 用于预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRowFast(FastConfigHandle fastConfig_handle, const void *indptr, const int indptr_type, const int32_t *indices, const void *data, const int64_t nindptr, const int64_t nelem, int64_t *out_len, double *out_result)

LGBM_BoosterPredictForCSRSingleRow 的更快变体。

在使用 LGBM_BoosterPredictForCSRSingleRowFastInit 设置后对单行进行评分。

通过从此调用中移除设置步骤,可以进行额外的优化,例如仅初始化一次配置,而不是每次调用都初始化。

注意

线程数量的设置仅在 LGBM_BoosterPredictForCSRSingleRowFastInit 调用时完成一次,而不是每次预测时都完成。如果您在其他调用中使用不同的线程数量,则需要重新开始设置过程,否则这些调用也将使用该数量的线程。

注意

您应为 out_result 预分配内存

  • 对于常规和原始分数,其长度等于 num_class * num_data

  • 对于叶子索引,其长度等于 num_class * num_data * num_iteration

  • 对于特征贡献,其长度等于 num_class * num_data * (num_feature + 1)

参数:
  • fastConfig_handle – 由 LGBM_BoosterPredictForCSRSingleRowFastInit 返回的 FastConfig 对象句柄

  • indptr – 指向行头的指针

  • indptr_typeindptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 指向列索引的指针

  • data – 指向数据空间的指针

  • nindptr – 矩阵中的行数 + 1

  • nelem – 矩阵中的非零元素数量

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSRSingleRowFastInit(BoosterHandle handle, const int predict_type, const int start_iteration, const int num_iteration, const int data_type, const int64_t num_col, const char *parameter, FastConfigHandle *out_fastConfig)

初始化并返回一个 FastConfigHandle,用于 LGBM_BoosterPredictForCSRSingleRowFast

不再需要时,通过将其句柄传递给 LGBM_FastConfigFree 来释放 FastConfig

参数:
  • handle – Booster 句柄

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 用于预测的迭代次数,<= 0 表示无限制

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • num_col – 列数

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_fastConfig[输出] FastConfig 对象,您可以使用它调用 LGBM_BoosterPredictForCSRSingleRowFast

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle, const char *data_filename, int data_has_header, int predict_type, int start_iteration, int num_iteration, const char *parameter, const char *result_filename)

对文件进行预测。

参数:
  • handle – booster 句柄

  • data_filename – 包含数据的文件名

  • data_has_header – 文件是否包含头

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 用于预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • result_filename – 将写入预测结果的文件名

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle, const void *data, int data_type, int32_t nrow, int32_t ncol, int is_row_major, int predict_type, int start_iteration, int num_iteration, const char *parameter, int64_t *out_len, double *out_result)

为新数据集进行预测。

注意

您应为 out_result 预分配内存

  • 对于常规和原始分数,其长度等于 num_class * num_data

  • 对于叶子索引,其长度等于 num_class * num_data * num_iteration

  • 对于特征贡献,其长度等于 num_class * num_data * (num_feature + 1)

参数:
  • handle – booster 句柄

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nrow – 行数

  • ncol – 列数

  • is_row_major – 1 表示行优先,0 表示列优先

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMats(BoosterHandle handle, const void **data, int data_type, int32_t nrow, int32_t ncol, int predict_type, int start_iteration, int num_iteration, const char *parameter, int64_t *out_len, double *out_result)

为以行指针数组形式呈现的新数据集进行预测。

注意

您应为 out_result 预分配内存

  • 对于常规和原始分数,其长度等于 num_class * num_data

  • 对于叶子索引,其长度等于 num_class * num_data * num_iteration

  • 对于特征贡献,其长度等于 num_class * num_data * (num_feature + 1)

参数:
  • handle – booster 句柄

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nrow – 行数

  • ncol – 列数

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRow(BoosterHandle handle, const void *data, int data_type, int ncol, int is_row_major, int predict_type, int start_iteration, int num_iteration, const char *parameter, int64_t *out_len, double *out_result)

为新数据集进行预测。此方法重用先前调用中的内部预测器结构,并针对单行调用进行了优化。

注意

您应为 out_result 预分配内存

  • 对于常规和原始分数,其长度等于 num_class * num_data

  • 对于叶子索引,其长度等于 num_class * num_data * num_iteration

  • 对于特征贡献,其长度等于 num_class * num_data * (num_feature + 1)

参数:
  • handle – booster 句柄

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • ncol – 列数

  • is_row_major – 1 表示行优先,0 表示列优先

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRowFast(FastConfigHandle fastConfig_handle, const void *data, int64_t *out_len, double *out_result)

LGBM_BoosterPredictForMatSingleRow 的更快变体。

在使用 LGBM_BoosterPredictForMatSingleRowFastInit 设置后对单行进行评分。

通过从此调用中移除设置步骤,可以进行额外的优化,例如仅初始化一次配置,而不是每次调用都初始化。

注意

线程数量的设置仅在 LGBM_BoosterPredictForMatSingleRowFastInit 调用时完成一次,而不是每次预测时都完成。如果您在其他调用中使用不同的线程数量,则需要重新开始设置过程,否则这些调用也将使用该数量的线程。

参数:
  • fastConfig_handle – 由 LGBM_BoosterPredictForMatSingleRowFastInit 返回的 FastConfig 对象句柄

  • data – 单行数组数据(只能是行优先形式)。

  • out_len[输出] 输出结果的长度

  • out_result[输出] 指向包含预测结果的数组的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMatSingleRowFastInit(BoosterHandle handle, const int predict_type, const int start_iteration, const int num_iteration, const int data_type, const int32_t ncol, const char *parameter, FastConfigHandle *out_fastConfig)

初始化并返回一个 FastConfigHandle,用于 LGBM_BoosterPredictForMatSingleRowFast

不再需要时,通过将其句柄传递给 LGBM_FastConfigFree 来释放 FastConfig

参数:
  • handle – Booster 句柄

  • predict_type – 要预测的内容

    • C_API_PREDICT_NORMAL: 常规预测,带转换(如果需要);

    • C_API_PREDICT_RAW_SCORE: 原始分数;

    • C_API_PREDICT_LEAF_INDEX: 叶子索引;

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 用于预测的迭代次数,<= 0 表示无限制

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • ncol – 列数

  • parameter – 预测的其他参数,例如预测的提前停止

  • out_fastConfig[输出] FastConfig 对象,您可以使用它调用 LGBM_BoosterPredictForMatSingleRowFast

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterPredictSparseOutput(BoosterHandle handle, const void *indptr, int indptr_type, const int32_t *indices, const void *data, int data_type, int64_t nindptr, int64_t nelem, int64_t num_col_or_row, int predict_type, int start_iteration, int num_iteration, const char *parameter, int matrix_type, int64_t *out_len, void **out_indptr, int32_t **out_indices, void **out_data)

为 CSR 或 CSC 格式的新数据集进行稀疏预测。目前仅用于特征贡献。

注意

输出是预分配的,因为它们可能随每次调用而变化,但形状应相同

  • 对于特征贡献,稀疏矩阵的形状将是 num_class * num_data * (num_feature + 1)。稀疏矩阵的输出 indptr_type 将与给定的输入 indptr_type 相同。调用 LGBM_BoosterFreePredictSparse 来释放资源。

参数:
  • handle – booster 句柄

  • indptr – 对于 CSR,是指向行头的指针;对于 CSC,是指向列头的指针

  • indptr_typeindptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 对于 CSR,是指向列索引的指针;对于 CSC,是指向行索引的指针

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nindptrindptr 中的条目数量

  • nelem – 矩阵中的非零元素数量

  • num_col_or_row – 对于 CSR,是列数;对于 CSC,是行数

  • predict_type – 应预测什么,目前仅支持特征贡献

    • C_API_PREDICT_CONTRIB: 特征贡献 (SHAP 值)

  • start_iteration – 用于预测的迭代起始索引

  • num_iteration – 用于预测的迭代次数,<= 0 表示无限制

  • parameter – 预测的其他参数,例如预测的提前停止

  • matrix_type – 矩阵输入和输出的类型,可以是 C_API_MATRIX_TYPE_CSRC_API_MATRIX_TYPE_CSC

  • out_len[输出] 输出数据和输出 indptr 的长度(指向一个包含两个条目的数组的指针,用于写入它们)

  • out_indptr[输出] 对于 CSR,是指向输出行头的指针;对于 CSC,是指向输出列头的指针

  • out_indices[输出] 对于 CSR,是指向稀疏列索引的指针;对于 CSC,是指向稀疏行索引的指针

  • out_data[输出] 指向稀疏数据空间的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterRefit(BoosterHandle handle, const int32_t *leaf_preds, int32_t nrow, int32_t ncol)

使用新数据(在线学习)重新拟合树模型。

参数:
  • handle – booster 句柄

  • leaf_preds – 指向预测叶子索引的指针

  • nrowleaf_preds 的行数

  • ncolleaf_preds 的列数

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle, const char *parameters)

重置 booster 的配置。

参数:
  • handle – booster 句柄

  • parameters – 参数,格式为 ‘key1=value1 key2=value2’

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle, const DatasetHandle train_data)

重置 booster 的训练数据。

参数:
  • handle – booster 句柄

  • train_data – 训练数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle)

回滚一次迭代。

参数:
  • handle – booster 句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle, int start_iteration, int num_iteration, int feature_importance_type, const char *filename)

将模型保存到文件。

参数:
  • handle – booster 句柄

  • start_iteration – 应保存的迭代的起始索引

  • num_iteration – 应保存的迭代数量,<= 0 表示保存所有迭代

  • feature_importance_type – 特征重要性类型,可以是 C_API_FEATURE_IMPORTANCE_SPLITC_API_FEATURE_IMPORTANCE_GAIN

  • filename – 文件名

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle, int start_iteration, int num_iteration, int feature_importance_type, int64_t buffer_len, int64_t *out_len, char *out_str)

将模型保存到字符串。

参数:
  • handle – booster 句柄

  • start_iteration – 应保存的迭代的起始索引

  • num_iteration – 应保存的迭代数量,<= 0 表示保存所有迭代

  • feature_importance_type – 特征重要性类型,可以是 C_API_FEATURE_IMPORTANCE_SPLITC_API_FEATURE_IMPORTANCE_GAIN

  • buffer_len – 字符串缓冲区长度,如果 buffer_len < out_len,则应重新分配缓冲区

  • out_len[out] 实际输出长度

  • out_str[输出] 模型字符串,应预分配内存

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle, int tree_idx, int leaf_idx, double val)

设置叶子值。

参数:
  • handle – booster 句柄

  • tree_idx – 树的索引

  • leaf_idx – 叶子的索引

  • val – 叶子值

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterShuffleModels(BoosterHandle handle, int start_iter, int end_iter)

打乱模型。

参数:
  • handle – booster 句柄

  • start_iter – 将被打乱的第一个迭代

  • end_iter – 将被打乱的最后一个迭代

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle, int *is_finished)

更新模型一次迭代。

参数:
  • handle – booster 句柄

  • is_finished[输出] 1 表示更新成功完成(无法再分裂),0 表示失败

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle, const float *grad, const float *hess, int *is_finished)

通过直接指定梯度和 Hessian 来更新模型(可用于支持自定义损失函数)。

注意

gradhess 引用的数组长度必须等于 num_class * num_train_data,库不会验证这一点,调用者必须确保。

参数:
  • handle – booster 句柄

  • grad – 一阶导数(梯度)统计信息

  • hess – 二阶导数(Hessian)统计信息

  • is_finished[输出] 1 表示更新成功完成(无法再分裂),0 表示失败

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_BoosterValidateFeatureNames(BoosterHandle handle, const char **data_names, int data_num_features)

检查数据的特征名称是否与用于训练 booster 的特征名称匹配。

参数:
  • handle – booster 句柄

  • data_names – 包含数据中特征名称的数组

  • data_num_features – 数据中的特征数量

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_ByteBufferFree(ByteBufferHandle handle)

释放字节缓冲区空间。

参数:
  • handle – 要释放的字节缓冲区的句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_ByteBufferGetAt(ByteBufferHandle handle, int32_t index, uint8_t *out_val)

获取 ByteBuffer 中指定索引处的值。

参数:
  • handle – 要读取的字节缓冲区的句柄

  • index – 要返回的值的索引

  • out_val[输出] 指定索引处要返回的字节值

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target, DatasetHandle source)

将特征从 source 添加到 target

参数:
  • target – 要添加特征的数据集的句柄

  • source – 要从中获取特征的数据集的句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateByReference(const DatasetHandle reference, int64_t num_total_row, DatasetHandle *out)

根据参考数据集分配数据集空间和特征分箱。

参数:
  • reference – 用于将分箱映射器与其他数据集对齐

  • num_total_row – 总行数

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromArrow(int64_t n_chunks, const ArrowArray *chunks, const ArrowSchema *schema, const char *parameters, const DatasetHandle reference, DatasetHandle *out)

从 Arrow 创建数据集。

参数:
  • n_chunks – 传递给此函数的 Arrow 数组数量

  • chunks – 指向 Arrow 数组列表的指针

  • schema – 指向所有 Arrow 数组的模式的指针

  • parameters – 附加参数

  • reference – 用于将分箱映射器与其他数据集对齐,nullptr 表示未使用

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void *col_ptr, int col_ptr_type, const int32_t *indices, const void *data, int data_type, int64_t ncol_ptr, int64_t nelem, int64_t num_row, const char *parameters, const DatasetHandle reference, DatasetHandle *out)

从 CSC 格式创建数据集。

参数:
  • col_ptr – 指向列头的指针

  • col_ptr_typecol_ptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 指向行索引的指针

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • ncol_ptr – 矩阵中的列数 + 1

  • nelem – 矩阵中的非零元素数量

  • num_row – 行数

  • parameters – 附加参数

  • reference – 用于将分箱映射器与其他数据集对齐,nullptr 表示未使用

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void *indptr, int indptr_type, const int32_t *indices, const void *data, int data_type, int64_t nindptr, int64_t nelem, int64_t num_col, const char *parameters, const DatasetHandle reference, DatasetHandle *out)

从 CSR 格式创建数据集。

参数:
  • indptr – 指向行头的指针

  • indptr_typeindptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 指向列索引的指针

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nindptr – 矩阵中的行数 + 1

  • nelem – 矩阵中的非零元素数量

  • num_col – 列数

  • parameters – 附加参数

  • reference – 用于将分箱映射器与其他数据集对齐,nullptr 表示未使用

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSRFunc(void *get_row_funptr, int num_rows, int64_t num_col, const char *parameters, const DatasetHandle reference, DatasetHandle *out)

通过回调从 CSR 格式创建数据集。

参数:
  • get_row_funptr – 指向 std::function<void(int idx, std::vector<std::pair<int, double>>& ret)> 的指针(为每行调用,并预期清除和填充 ret

  • num_rows – 行数

  • num_col – 列数

  • parameters – 附加参数

  • reference – 用于将分箱映射器与其他数据集对齐,nullptr 表示未使用

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char *filename, const char *parameters, const DatasetHandle reference, DatasetHandle *out)

从文件加载数据集(如 LightGBM CLI 版本)。

参数:
  • filename – 文件名

  • parameters – 附加参数

  • reference – 用于将分箱映射器与其他数据集对齐,nullptr 表示未使用

  • out[out] 加载的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void *data, int data_type, int32_t nrow, int32_t ncol, int is_row_major, const char *parameters, const DatasetHandle reference, DatasetHandle *out)

从密集矩阵创建数据集。

参数:
  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nrow – 行数

  • ncol – 列数

  • is_row_major – 1 表示行优先,0 表示列优先

  • parameters – 附加参数

  • reference – 用于将分箱映射器与其他数据集对齐,nullptr 表示未使用

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMats(int32_t nmat, const void **data, int data_type, int32_t *nrow, int32_t ncol, int *is_row_major, const char *parameters, const DatasetHandle reference, DatasetHandle *out)

从密集矩阵数组创建数据集。

参数:
  • nmat – 密集矩阵的数量

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nrow – 行数

  • ncol – 列数

  • is_row_major – 指向数据布局的指针。1 表示行主序,0 表示列主序

  • parameters – 附加参数

  • reference – 用于将分箱映射器与其他数据集对齐,nullptr 表示未使用

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledColumn(double **sample_data, int **sample_indices, int32_t ncol, const int *num_per_col, int32_t num_sample_row, int32_t num_local_row, int64_t num_dist_row, const char *parameters, DatasetHandle *out)

根据采样数据分配数据集空间和特征分箱。

参数:
  • sample_data – 采样数据,按列分组

  • sample_indices – 采样数据的索引

  • ncol – 列数

  • num_per_col – 每个采样列的大小

  • num_sample_row – 采样行数

  • num_local_row – 本地机器的总行数

  • num_dist_row – 分布式总行数

  • parameters – 附加参数

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSerializedReference(const void *ref_buffer, int32_t ref_buffer_size, int64_t num_row, int32_t num_classes, const char *parameters, DatasetHandle *out)

根据序列化的参考数据集分配数据集空间和特征分箱。

参数:
  • ref_buffer – 数据集 schema 的二进制表示(特征组、分箱等)

  • ref_buffer_size – 参考数组的大小(字节)

  • num_row – 数据集将包含的总行数

  • num_classes – 类别数(仅在多分类和指定初始分数时使用)

  • parameters – 附加参数

  • out[out] 创建的数据集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetDumpText(DatasetHandle handle, const char *filename)

将数据集保存为文本文件,仅用于调试。

参数:
  • handle – 数据集句柄

  • filename – 文件名

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetFree(DatasetHandle handle)

释放数据集空间。

参数:
  • handle – 要释放的数据集句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(DatasetHandle handle, const int len, int *num_feature_names, const size_t buffer_len, size_t *out_buffer_len, char **feature_names)

获取数据集的特征名称。

参数:
  • handle – 数据集句柄

  • len – 存储在 out_strschar* 指针数量。如果小于最大大小,则只复制这些数量的字符串

  • num_feature_names[out] 特征名称数量

  • buffer_len – 预分配字符串的大小。内容将被复制到 buffer_len - 1 处并以 null 终止

  • out_buffer_len[输出] 执行完整字符串复制所需的字符串大小

  • feature_names[out] 特征名称,应预先分配内存

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNumBin(DatasetHandle handle, int feature, int *out)

获取特征的分箱数量。

参数:
  • handle – 数据集句柄

  • feature – 特征索引

  • out[out] 存储分箱数量的地址

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle, const char *field_name, int *out_len, const void **out_ptr, int *out_type)

从数据集获取信息向量。

参数:
  • handle – 数据集句柄

  • field_name – 字段名

  • out_len[out] 用于设置结果长度

  • out_ptr[out] 指向结果的指针

  • out_type[out] 结果指针的类型,可以是 C_API_DTYPE_INT32, C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle, int *out)

获取数据点数量。

参数:
  • handle – 数据集句柄

  • out[out] 存储数据点数量的地址

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle, int *out)

获取特征数量。

参数:
  • handle – 数据集句柄

  • out[out] 存储特征数量的地址

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetGetSubset(const DatasetHandle handle, const int32_t *used_row_indices, int32_t num_used_row_indices, const char *parameters, DatasetHandle *out)

创建数据子集。

参数:
  • handle – 完整数据集句柄

  • used_row_indices – 子集中使用的索引

  • num_used_row_indicesused_row_indices 的长度

  • parameters – 附加参数

  • out[out] 数据子集

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetInitStreaming(DatasetHandle dataset, int32_t has_weights, int32_t has_init_scores, int32_t has_queries, int32_t nclasses, int32_t nthreads, int32_t omp_max_threads)

初始化数据集以进行流式传输。

参数:
  • dataset – 数据集句柄

  • has_weights – 数据集是否包含 Metadata 权重

  • has_init_scores – 数据集是否包含 Metadata 初始分数

  • has_queries – 数据集是否包含 Metadata 查询/组

  • nclasses – 初始分数类别数

  • nthreads – 将使用 PushRows API 的外部线程数

  • omp_max_threads – OpenMP 最大线程数(-1 表示默认)

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetMarkFinished(DatasetHandle dataset)

通过调用 dataset->FinishLoad 将数据集标记为完成。

参数:
  • dataset – 数据集句柄

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset, const void *data, int data_type, int32_t nrow, int32_t ncol, int32_t start_row)

将数据推送到现有数据集,如果 nrow + start_row == num_total_row,将调用 dataset->FinishLoad

参数:
  • dataset – 数据集句柄

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nrow – 行数

  • ncol – 列数

  • start_row – 行起始索引

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset, const void *indptr, int indptr_type, const int32_t *indices, const void *data, int data_type, int64_t nindptr, int64_t nelem, int64_t num_col, int64_t start_row)

将数据推送到现有数据集,如果 nrow + start_row == num_total_row,将调用 dataset->FinishLoad

参数:
  • dataset – 数据集句柄

  • indptr – 指向行头的指针

  • indptr_typeindptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 指向列索引的指针

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nindptr – 矩阵中的行数 + 1

  • nelem – 矩阵中的非零元素数量

  • num_col – 列数

  • start_row – 行起始索引

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSRWithMetadata(DatasetHandle dataset, const void *indptr, int indptr_type, const int32_t *indices, const void *data, int data_type, int64_t nindptr, int64_t nelem, int64_t start_row, const float *label, const float *weight, const double *init_score, const int32_t *query, int32_t tid)

将 CSR 数据推送到现有数据集。(更多详情请参阅 LGBM_DatasetPushRowsWithMetadata。)

参数:
  • dataset – 数据集句柄

  • indptr – 指向行头的指针

  • indptr_typeindptr 的类型,可以是 C_API_DTYPE_INT32C_API_DTYPE_INT64

  • indices – 指向列索引的指针

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nindptr – 矩阵中的行数 + 1

  • nelem – 矩阵中的非零元素数量

  • start_row – 行起始索引

  • label – 指向包含 nindptr-1 个标签的数组的指针

  • weight – 可选指针,指向包含 nindptr-1 个权重的数组

  • init_score – 可选指针,指向包含 (nindptr-1)*nclasses 个初始分数的数组,列格式

  • query – 可选指针,指向包含 nindptr-1 个查询值的数组

  • tid – 调用线程的 ID,从 0 到 N-1

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsWithMetadata(DatasetHandle dataset, const void *data, int data_type, int32_t nrow, int32_t ncol, int32_t start_row, const float *label, const float *weight, const double *init_score, const int32_t *query, int32_t tid)

将数据推送到现有数据集。流式传输场景的通用流程是

  1. 创建数据集“schema”(例如 LGBM_DatasetCreateFromSampledColumn

  2. 初始化它们以实现线程安全的流式传输(LGBM_DatasetInitStreaming

  3. 推送数据(LGBM_DatasetPushRowsWithMetadataLGBM_DatasetPushRowsByCSRWithMetadata

  4. 调用 LGBM_DatasetMarkFinished

参数:
  • dataset – 数据集句柄

  • data – 指向数据空间的指针

  • data_typedata 指针的类型,可以是 C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

  • nrow – 行数

  • ncol – 特征列数

  • start_row – 行起始索引,即开始插入数据的索引

  • label – 指向包含 nrow 个标签的数组的指针

  • weight – 可选指针,指向包含 nrow 个权重的数组

  • init_score – 可选指针,指向包含 nrow*nclasses 个初始分数的数组,列格式

  • query – 可选指针,指向包含 nrow 个查询值的数组

  • tid – 调用线程的 ID,从 0 到 N-1

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetSaveBinary(DatasetHandle handle, const char *filename)

将数据集保存为二进制文件。

参数:
  • handle – 数据集句柄

  • filename – 文件名

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetSerializeReferenceToBinary(DatasetHandle handle, ByteBufferHandle *out, int32_t *out_len)

创建数据集 schema 的二进制字节数组表示(不包括数据)。

参数:
  • handle – 数据集句柄

  • out[out] 输出字节数组

  • out_len[out] 输出字节数组的长度(为方便起见返回)

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(DatasetHandle handle, const char **feature_names, int num_feature_names)

将特征名称保存到数据集。

参数:
  • handle – 数据集句柄

  • feature_names – 特征名称

  • num_feature_names – 特征名称数量

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle, const char *field_name, const void *field_data, int num_element, int type)

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

注意

  • group 仅适用于 C_API_DTYPE_INT32

  • labelweight 仅适用于 C_API_DTYPE_FLOAT32

  • init_score 仅适用于 C_API_DTYPE_FLOAT64

参数:
  • handle – 数据集句柄

  • field_name – 字段名,可以是 label, weight, init_score, group

  • field_data – 指向数据向量的指针

  • num_elementfield_data 中的元素数量

  • typefield_data 指针的类型,可以是 C_API_DTYPE_INT32, C_API_DTYPE_FLOAT32C_API_DTYPE_FLOAT64

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetSetFieldFromArrow(DatasetHandle handle, const char *field_name, int64_t n_chunks, const ArrowArray *chunks, const ArrowSchema *schema)

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

注意

  • group 将输入数据类型转换为 int32

  • labelweight 将输入数据类型转换为 float32

  • init_score 将输入数据类型转换为 float64

参数:
  • handle – 数据集句柄

  • field_name – 字段名,可以是 label, weight, init_score, group

  • n_chunks – 传递给此函数的 Arrow 数组数量

  • chunks – 指向 Arrow 数组列表的指针

  • schema – 指向所有 Arrow 数组的模式的指针

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetSetWaitForManualFinish(DatasetHandle dataset, int wait)

设置数据集是等待手动调用 MarkFinished 还是自动调用 FinishLoad。对于流式传输场景,将其设置为 1,并使用 LGBM_DatasetMarkFinished 手动完成数据集。

参数:
  • dataset – 数据集句柄

  • wait – 是否等待(1 或 0)

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DatasetUpdateParamChecking(const char *old_parameters, const char *new_parameters)

对尝试更新数据集参数的操作引发错误。

参数:
  • old_parameters – 当前数据集参数

  • new_parameters – 新数据集参数

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_DumpParamAliases(int64_t buffer_len, int64_t *out_len, char *out_str)

将所有参数名称及其别名转储为 JSON。

参数:
  • buffer_len – 字符串缓冲区长度,如果 buffer_len < out_len,则应重新分配缓冲区

  • out_len[out] 实际输出长度

  • out_str[out] 参数的 JSON 格式字符串,应预先分配内存

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_FastConfigFree(FastConfigHandle fastConfig)

释放 FastConfig 对象。

参数:
  • fastConfig – 通过 *FastInit() 方法获得的 FastConfig 对象句柄。

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT const char *LGBM_GetLastError()

获取上次错误的字符串消息。

返回值:

错误信息

LIGHTGBM_C_EXPORT int LGBM_GetMaxThreads(int *out)

获取此进程中 LightGBM 例程当前使用的最大线程数。

参数:
  • out[out] LightGBM 当前使用的最大线程数。-1 表示默认为 omp_get_num_threads()。

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_GetSampleCount(int32_t num_total_row, const char *parameters, int *out)

根据参数和数据总行数获取样本数量。

参数:
  • num_total_row – 总行数

  • parameters – 附加参数,即使用 bin_construct_sample_cnt 计算返回值

  • out[out] 样本数量。此值用于在调用 LGBM_SampleIndices 时预先分配内存以存储样本索引

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_NetworkFree()

终结网络。

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char *machines, int local_listen_port, int listen_time_out, int num_machines)

初始化网络。

参数:
  • machines – 机器列表,格式为 'ip1:port1,ip2:port2'

  • local_listen_port – 本地机器的 TCP 监听端口

  • listen_time_out – Socket 超时时间(分钟)

  • num_machines – 机器总数

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_NetworkInitWithFunctions(int num_machines, int rank, void *reduce_scatter_ext_fun, void *allgather_ext_fun)

使用外部集合函数初始化网络。

参数:
  • num_machines – 机器总数

  • rank – 本地机器的等级

  • reduce_scatter_ext_fun – 外部 reduce-scatter 函数

  • allgather_ext_fun – 外部 allgather 函数

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_RegisterLogCallback(void (*callback)(const char*))

注册一个用于日志重定向的回调函数。

参数:
  • callback – 要注册的回调函数

返回值:

成功时返回 0,失败时返回 -1

LIGHTGBM_C_EXPORT int LGBM_SampleIndices(int32_t num_total_row, const char *parameters, void *out, int32_t *out_len)

为总行数创建样本索引。

注意

您应该为 out 预先分配内存,您可以通过 LGBM_GetSampleCount 获取其长度。

参数:
  • num_total_row – 总行数

  • parameters – 附加参数,即使用 bin_construct_sample_cntdata_random_seed 生成输出

  • out[out] 创建的索引,类型为 int32_t

  • out_len[out] 索引数量

返回值:

成功时返回 0,失败时返回 -1

inline void LGBM_SetLastError(const char *msg)

设置上次错误的字符串消息。

注意

当使用 C99 之前的 C 标准编译时,这将调用不安全的 sprintf

参数:
  • msg – 错误消息

LIGHTGBM_C_EXPORT int LGBM_SetMaxThreads(int num_threads)

设置此进程中 LightGBM 例程使用的最大线程数。

参数:
  • num_threads – LightGBM 使用的最大线程数。-1 表示默认为 omp_get_num_threads()。

返回值:

成功时返回 0,失败时返回 -1