C API
- 版权
Copyright (c) 2016 Microsoft Corporation. 保留所有权利。根据 MIT 许可证授权。有关许可证信息，请参阅项目根目录下的 LICENSE 文件。
注意
为了避免在大数据上进行类型转换，我们的大部分公开接口都支持 float32 和 float64，以下情况除外：
梯度和 Hessian；
训练和验证数据的当前分数。
定义
-
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_SPLIT或C_API_FEATURE_IMPORTANCE_GAINbuffer_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_type –
indptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_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)
获取训练数据和验证数据的评估结果。
注意
您应首先调用
LGBM_BoosterGetEvalNames来获取评估指标的名称。您应为
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_strs的char*指针数量。如果小于最大大小，则只复制这些数量的字符串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_strs的char*指针数量。如果小于最大大小，则只复制这些数量的字符串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_type –
col_ptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 指向行索引的指针
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64ncol_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_type –
indptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 指向列索引的指针
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nindptr – 矩阵中的行数 + 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_type –
indptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 指向列索引的指针
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nindptr – 矩阵中的行数 + 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_type –
indptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 指向列索引的指针
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_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64num_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_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nrow – 行数
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_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nrow – 行数
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_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64ncol – 列数
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_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64ncol – 列数
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_type –
indptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 对于 CSR，是指向列索引的指针；对于 CSC，是指向行索引的指针
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nindptr –
indptr中的条目数量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_CSR或C_API_MATRIX_TYPE_CSCout_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 – 指向预测叶子索引的指针
nrow –
leaf_preds的行数ncol –
leaf_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_SPLIT或C_API_FEATURE_IMPORTANCE_GAINfilename – 文件名
- 返回值:
成功时返回 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_SPLIT或C_API_FEATURE_IMPORTANCE_GAINbuffer_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 来更新模型（可用于支持自定义损失函数）。
注意
由
grad和hess引用的数组长度必须等于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_type –
col_ptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 指向行索引的指针
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64ncol_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_type –
indptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 指向列索引的指针
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nindptr – 矩阵中的行数 + 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_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nrow – 行数
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_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nrow – 行数
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_strs的char*指针数量。如果小于最大大小，则只复制这些数量的字符串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_FLOAT32或C_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_indices –
used_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_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nrow – 行数
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_type –
indptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 指向列索引的指针
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nindptr – 矩阵中的行数 + 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_type –
indptr的类型，可以是C_API_DTYPE_INT32或C_API_DTYPE_INT64indices – 指向列索引的指针
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nindptr – 矩阵中的行数 + 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)
将数据推送到现有数据集。流式传输场景的通用流程是
创建数据集“schema”（例如
LGBM_DatasetCreateFromSampledColumn）初始化它们以实现线程安全的流式传输（
LGBM_DatasetInitStreaming）推送数据（
LGBM_DatasetPushRowsWithMetadata或LGBM_DatasetPushRowsByCSRWithMetadata）调用
LGBM_DatasetMarkFinished
- 参数:
dataset – 数据集句柄
data – 指向数据空间的指针
data_type –
data指针的类型，可以是C_API_DTYPE_FLOAT32或C_API_DTYPE_FLOAT64nrow – 行数
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；label和weight仅适用于C_API_DTYPE_FLOAT32；init_score仅适用于C_API_DTYPE_FLOAT64。
- 参数:
handle – 数据集句柄
field_name – 字段名，可以是 label, weight, init_score, group
field_data – 指向数据向量的指针
num_element –
field_data中的元素数量type –
field_data指针的类型，可以是C_API_DTYPE_INT32,C_API_DTYPE_FLOAT32或C_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；label和weight将输入数据类型转换为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_cnt和data_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