LightGBM C API 完全指南从 Dataset 构建到模型训练与预测的底层编程实战【免费下载链接】LightGBMA fast, distributed, high performance gradient boosting (GBT, GBDT, GBRT, GBM or MART) framework based on decision tree algorithms, used for ranking, classification and many other machine learning tasks.项目地址: https://gitcode.com/GitHub_Trending/li/LightGBM本文以 LightGBM 仓库的 C-API.rst 为索引完整展开其指向的核心头文件 include/LightGBM/c_api.h约 1700 行、80 个导出函数所定义的 C 语言接口并结合 src/c_api.cpp 的实现细节与 tests/c_api_test/test_.py 的完整测试流程讲解如何在 C/C、ctypes、FFI 等场景下直接调用 LightGBM包括 Dataset 的多种创建方式、Booster 的训练推进、四种预测模式、快速单行预测FastConfig、错误处理与线程控制以及分布式网络初始化。读者读完可掌握不依赖 Python 封装、直接以 C 接口驱动 LightGBM 完整生命周期建集→训练→评估→保存→加载→预测的实战能力。C API 的设计定位与头文件结构C API 是 LightGBM 面向所有下游语言绑定的地基。仓库中的 Python 包python-package/lightgbm/basic.py正是通过ctypes加载lib_lightgbm.soWindows 下为lib_lightgbm.dllmacOS 为lib_lightgbm.dylib后逐一声明这些函数才得以工作的其库查找逻辑见 python-package/lightgbm/libpath.py。从 c_api.h 头部注释可以读出两个关键设计决策同时支持 float32 与 float64为避免大数据上的类型转换开销绝大多数接口同时接受两种精度但**梯度gradient与 Hessian、以及训练/验证数据的当前得分score**除外——这两类数据被高频调用类型转换代价过高因此只支持 float32/float64 的固定约定。线程局部错误信息文件末尾定义了THREAD_LOCAL修饰的LastErrorMsg()c_api.h错误字符串保存在线程局部缓冲区中配合LGBM_GetLastError()即可在多线程环境下安全获取错误详情。API 按功能划分为三大块与头文件中的注释分区一致Dataset 接口/* --- start Dataset interface */数据集的创建、加载、推送与元数据管理Booster 接口/* --- start Booster interfaces */模型训练、评估、保存、加载与预测工具与网络接口错误获取、日志回调、参数别名导出、线程控制、分布式网络初始化。核心类型与常量约定所有句柄均为不透明指针void*由头文件 typedef 定义typedef void* DatasetHandle; /*! Dataset 句柄 */ typedef void* BoosterHandle; /*! Booster 句柄 */ typedef void* FastConfigHandle; /*! FastConfig 句柄单行快速预测配置 */ typedef void* ByteBufferHandle; /*! ByteBuffer 句柄二进制序列化缓冲 */数据类型常量贯穿 Dataset 创建与预测的全部入口常量值含义C_API_DTYPE_FLOAT320单精度浮点C_API_DTYPE_FLOAT641双精度浮点C_API_DTYPE_INT32232 位整型C_API_DTYPE_INT64364 位整型预测类型常量predict_type参数常量值语义C_API_PREDICT_NORMAL0普通预测按需做逆变换如 sigmoidC_API_PREDICT_RAW_SCORE1原始得分C_API_PREDICT_LEAF_INDEX2叶子索引C_API_PREDICT_CONTRIB3特征贡献SHAP 值稀疏矩阵类型C_API_MATRIX_TYPE_CSR (0)与C_API_MATRIX_TYPE_CSC (1)特征重要性类型C_API_FEATURE_IMPORTANCE_SPLIT (0)被使用的次数与C_API_FEATURE_IMPORTANCE_GAIN (1)分裂总增益。这些常量在 tests/c_api_test/test_.py 中被原样复刻dtype_float32 0等说明它们是绑定层与 C 库之间的共享契约。构建与加载获取 lib_lightgbm 动态库C API 以动态库形式对外导出。Linux/macOS 构建产物为lib_lightgbm.so/lib_lightgbm.dylibWindows 为lib_lightgbm.dll搜索路径参见 python-package/lightgbm/libpath.py依次为python-package/上级目录、bin/、lib/、Release/等。C/C 调用只需包含LightGBM/c_api.h并链接该库ctypes 调用示例见 tests/c_api_test/test_.py——若无法导入 Python 包它会直接定位仓库根目录的lib_lightgbm.so并加载。一个重要约定所有返回值为 0 表示成功-1 表示失败。失败后用LGBM_GetLastError()获取错误信息测试中也将其restype声明为ctypes.c_char_p以便直接打印tests/c_api_test/test_.py。Dataset 接口五种创建路径与元数据管理Dataset 是训练与验证数据的载体C API 提供了多种创建方式以适应不同数据布局。所有创建函数都带reference参数可为NULL用于让新数据集对齐已有数据集的 bin mapper保证特征分箱一致这正是训练集与验证集必须共用的原因。从文件加载LGBM_DatasetCreateFromFile与 CLI 版完全一致parameters为keyvalue key2value2空格分隔的字符串。其实现位于 src/c_api.cpp先Config::Str2Map(parameters)解析参数并设置 OpenMP 线程数再构造DatasetLoader加载在分布式场景Network::num_machines() 1下会自动按rank与机器数切分数据。测试中调用示例LIB.LGBM_DatasetCreateFromFile(c_str(binary.train), c_str(max_bin15), ref, ctypes.byref(handle))从稠密矩阵创建LGBM_DatasetCreateFromMat接受连续内存指针支持行主序is_row_major1与列主序is_row_major0两种布局LGBM_DatasetCreateFromMats是其多矩阵变体。测试中的用法tests/c_api_test/test_.pyLIB.LGBM_DatasetCreateFromMat( data.ctypes.data_as(ctypes.POINTER(ctypes.c_double)), # 展平后的数据 ctypes.c_int(dtype_float64), # 数据类型 ctypes.c_int32(mat.shape[0]), ctypes.c_int32(mat.shape[1]), ctypes.c_int(1), # 行主序 c_str(max_bin15), ref, ctypes.byref(handle))从稀疏矩阵创建CSR / CSCLGBM_DatasetCreateFromCSR与LGBM_DatasetCreateFromCSC接收indptr/indices/data三件套且indptr的类型C_API_DTYPE_INT32或C_API_DTYPE_INT64可独立指定便于直接对接 scipy 等生态。测试用scipy.sparse.csr_matrix演示了完整链路tests/c_api_test/test_.py先取csr.indptr、csr.indices、csr.data的内存指针创建数据集后再用LGBM_DatasetSetField单独设置 label。另有LGBM_DatasetCreateFromCSRFunc支持以回调函数逐行喂数据。按参考集创建与子集提取LGBM_DatasetCreateByReference基于已有数据集的结构创建空数据集用于验证集LGBM_DatasetGetSubset按行索引抽取子集LGBM_DatasetCreateFromSerializedReference从序列化的 schema 二进制LGBM_DatasetSerializeReferenceToBinary产出重建数据集可在另一进程中复用特征分箱结构。流式推送Streaming针对超大数据的流式加载C API 提供了完整的四步流程头文件注释明示LGBM_DatasetCreateFromSampledColumn或按参考集创建 Dataset 的schemaLGBM_DatasetInitStreaming初始化线程安全的流式写入指定是否含 weights/init_scores/queries、类别数与外部线程数用LGBM_DatasetPushRows/LGBM_DatasetPushRowsWithMetadata稠密或LGBM_DatasetPushRowsByCSR/LGBM_DatasetPushRowsByCSRWithMetadata稀疏推送数据start_row指定插入起点并支持同时写入 label、weight、init_score、query 与线程 IDtidLGBM_DatasetMarkFinished手动收尾。LGBM_DatasetSetWaitForManualFinish控制是否等待手动MarkFinished流式场景设为 1。从实现看src/c_api.cpp若未开启手动等待推送恰好填满num_data时会自动调用FinishLoad()。元数据与特征信息LGBM_DatasetSetField/LGBM_DatasetGetField读写 label、weight、init_score、group、position 等字段注意字段与类型的对应关系——group/position 只支持 INT32label/weight 只支持 FLOAT32init_score 只支持 FLOAT64见 c_api.h。LGBM_DatasetSetFieldFromArrowStream则允许从 Arrow 流直接写入字段旧的LGBM_DatasetSetFieldFromArrow已标记废弃。LGBM_DatasetSetFeatureNames/LGBM_DatasetGetFeatureNames特征名读写后者需要先查询所需缓冲长度再分配内存。LGBM_DatasetGetNumData/LGBM_DatasetGetNumFeature/LGBM_DatasetGetFeatureNumBin行数、特征数、某特征分箱数。LGBM_DatasetSaveBinary保存为二进制格式下次加载更快LGBM_DatasetDumpText导出文本仅调试用LGBM_DatasetAddFeaturesFrom将源数据集特征合并进目标数据集LGBM_DatasetUpdateParamChecking校验参数更新是否合法。LGBM_DatasetFree释放数据集训练/验证数据集的生命周期由调用方管理Booster 并不接管。Booster 接口创建、训练与评估创建与加载LGBM_BoosterCreate(const DatasetHandle train_data, const char* parameters, BoosterHandle* out);parameters同样是key1value1 key2value2格式。测试中的训练配置为appbinary metricauc num_leaves31 verbose0tests/c_api_test/test_.py与 examples/binary_classification/train.conf 中 CLI 配置的关键参数一一对应objective binary、metric binary_logloss,auc、num_leaves 63、learning_rate 0.1、feature_fraction 0.8等——C API 与 CLI、Python 共用同一套参数体系均由 src/io/config.cpp 解析。加载既有模型有两个入口LGBM_BoosterCreateFromModelfile(filename, out_num_iterations, out)LGBM_BoosterLoadModelFromString(model_str, out_num_iterations, out)后者免去临时文件便于从数据库/网络读取模型文本。LGBM_BoosterGetLoadedParam可把模型实际生效的参数以 JSON 字符串导出LGBM_BoosterGetLinear返回该 Booster 是否在拟合线性树linear_tree模式。迭代推进训练核心训练函数是LGBM_BoosterUpdateOneIter它推进一轮 boosting 迭代并通过produced_empty_tree输出本轮是否产生了空树空树通常意味着训练已经收敛继续调用不会改变预测结果但若配置了随机性如feature_fraction_bynode 1.0的列采样后续调用仍可能产生非空树因此空树并不绝对代表结束见 c_api.h。测试中的典型训练循环tests/c_api_test/test_.py每轮调用后即用LGBM_BoosterGetEval取训练集指标并打印 AUC。其余训练控制函数还包括LGBM_BoosterUpdateOneIterCustom(grad, hess, ...)直接喂入自定义损失的一阶/二阶导数长度必须为num_class * num_train_data库不校验、调用方需保证LGBM_BoosterRollbackOneIter回退一轮早停后用于撤销多余迭代LGBM_BoosterRefit基于新的叶子索引数据对树做再拟合在线学习LGBM_BoosterMerge将另一个 Booster 的模型并入当前 Booster多折交叉训练的常见手法LGBM_BoosterShuffleModels打乱指定迭代区间内的模型顺序。验证集与评估LGBM_BoosterAddValidData(handle, valid_data); // 可多次调用添加多个验证集 LGBM_BoosterGetEval(handle, data_idx, out_len, out_results); // 0训练集,1第1个验证集...使用LGBM_BoosterGetEval前必须先用LGBM_BoosterGetEvalNames获取指标名、用LGBM_BoosterGetEvalCounts获取结果长度并预分配内存。此外LGBM_BoosterGetNumPredict/LGBM_BoosterGetPredict可获取训练/验证集上的预测值用于自定义评估函数。其他信息查询LGBM_BoosterGetNumClasses、LGBM_BoosterNumModelPerIteration每轮子树数多分类即类别数、LGBM_BoosterNumberOfTotalModel总弱模型数、LGBM_BoosterGetCurrentIteration、LGBM_BoosterGetNumFeature、LGBM_BoosterGetFeatureNames以及LGBM_BoosterValidateFeatureNames校验数据特征名与训练时是否一致用于防止预测时特征错位。重置与运行期调整LGBM_BoosterResetTrainingData换训练数据、LGBM_BoosterResetParameter重设超参数支持在已创建的 Booster 上动态调整适合在线学习与超参搜索。预测接口四种模式 × 三种数据布局预测家族是 C API 中函数最密集的部分。输出长度规则预分配内存的依据头文件多处\note明示NORMAL / RAW_SCORE长度为num_class * num_dataLEAF_INDEX长度为num_class * num_data * num_iterationCONTRIBSHAP长度为num_class * num_data * (num_feature 1)。按数据布局划分的预测入口数据布局批量预测单行快速预测稠密矩阵LGBM_BoosterPredictForMat/LGBM_BoosterPredictForMatsLGBM_BoosterPredictForMatSingleRow→...SingleRowFastInit→...SingleRowFastCSR 稀疏LGBM_BoosterPredictForCSRLGBM_BoosterPredictForCSRSingleRow→...SingleRowFastInit→...SingleRowFastCSC 稀疏LGBM_BoosterPredictForCSC—文本文件LGBM_BoosterPredictForFile写结果到文件—Arrow 流LGBM_BoosterPredictForArrowStream旧的...ForArrow已废弃—所有预测函数共享predict_type / start_iteration / num_iteration / parameter四参数num_iteration 0表示不限制迭代数parameter可传预测期参数如预测阶段早停pred_early_stop。测试中用LGBM_BoosterPredictForMat预测并对比了LGBM_BoosterPredictForFile两种路径tests/c_api_test/test_.py。稀疏输出SparseOutputLGBM_BoosterPredictSparseOutput专门用于 SHAP 贡献值的稀疏输出结果形状恒为num_class * num_data * (num_feature 1)且输出indptr的类型与输入一致INT32 或 INT64。注意它目前仅支持C_API_PREDICT_CONTRIB矩阵类型由matrix_typeC_API_MATRIX_TYPE_CSR/C_API_MATRIX_TYPE_CSC指定返回的out_indptr / out_indices / out_data三块内存必须用LGBM_BoosterFreePredictSparse释放。FastConfig单行预测的低延迟方案对在线推理每请求单样本打分场景C API 提供了专用的两阶段快速接口LGBM_BoosterPredictForCSRSingleRowFastInit或...MatSingleRowFastInit一次性完成配置初始化返回FastConfigHandle初始化的预测类型、起止迭代、数据类型、特征数与预测参数都被固化LGBM_BoosterPredictForCSRSingleRowFast或...MatSingleRowFast后续只需传入单行数据即可打分省去每次调用都重建配置的开销如只初始化一次配置、线程数只设置一次LGBM_FastConfigFree释放FastConfig。头文件特别提醒线程数只在 Init 阶段设置一次。若其他调用改变了线程数设置必须重新走一遍 Init 流程否则这些调用将沿用 FastConfig 固化时的线程数c_api.h。模型导出文件、字符串与 JSONLGBM_BoosterSaveModel保存文本模型到文件可指定start_iteration、num_iteration0保存全部与特征重要性类型LGBM_BoosterSaveModelToString输出到字符串需先传buffer_len若buffer_len out_len需重新分配out_len会给出实际所需长度LGBM_BoosterDumpModel导出 JSON 格式的完整树结构LGBM_BoosterGetLeafValue/LGBM_BoosterSetLeafValue按(tree_idx, leaf_idx)读写叶子值LGBM_BoosterFeatureImportance按num_iteration与重要性类型输出特征重要性数组LGBM_BoosterGetUpperBoundValue/LGBM_BoosterGetLowerBoundValue模型输出上下界可用于单调性约束或量化部署的边界估算。工具函数日志、参数、线程与错误处理LGBM_RegisterLogCallback(void (*)(const char*))把库内部日志重定向到自定义回调Python 包正是借此把 C 日志桥接到logging见 python-package/lightgbm/basic.py 附近的_LIB.LGBM_RegisterLogCallback用法LGBM_DumpParamAliases以 JSON 导出全部参数名及其别名可用于做参数校验与文档生成LGBM_GetSampleCount/LGBM_SampleIndices根据bin_construct_sample_cnt与data_random_seed计算并生成建直方图用的采样行索引供外部实现自定义分箱流程LGBM_ByteBufferGetAt/LGBM_ByteBufferFree读写二进制序列化缓冲配合LGBM_DatasetSerializeReferenceToBinaryLGBM_SetMaxThreads/LGBM_GetMaxThreads进程级线程数控制。-1表示默认omp_get_num_threads()。测试 tests/c_api_test/test_.py 验证了完整行为初始为-1设置为6后读取为6设置为任意负数如-123会重置回-1LGBM_GetLastError/LGBM_SetLastError线程局部的错误信息读写前者是调用方在函数返回-1后必须执行的诊断步骤。分布式与网络初始化C API 为分布式训练暴露了三个函数LGBM_NetworkInit(const char* machines, // ip1:port1,ip2:port2,... int local_listen_port, int listen_time_out, // 单位分钟 int num_machines); LGBM_NetworkFree(); LGBM_NetworkInitWithFunctions(int num_machines, int rank, void* reduce_scatter_ext_fun, void* allgather_ext_fun);LGBM_NetworkInit走内置的 socket 通信实现见 src/network/network.cppLGBM_NetworkInitWithFunctions则注入外部实现的 reduce-scatter 与 allgather 集合通信原语便于对接 MPI 等框架相关实现见 src/network/linkers_mpi.cpp。网络初始化后LGBM_DatasetCreateFromFile在num_machines 1时即会按 rank 分片加载数据src/c_api.cpp。完整实战流程从测试用例提炼的标准调用链仓库测试 tests/c_api_test/test_.py 本身就是一份可直接运行的 C API 使用范式。其test_dataset与test_booster串联起的标准生命周期为建训练集LGBM_DatasetCreateFromMat或FromFile/FromCSR/FromCSCLGBM_DatasetSetField设 label建验证集以训练集为reference调用LGBM_DatasetCreateFromMat保证分箱对齐创建 BoosterLGBM_BoosterCreate(train, appbinary metricauc num_leaves31 verbose0, booster)挂验证集LGBM_BoosterAddValidData(booster, test)迭代训练循环LGBM_BoosterUpdateOneIter每轮用LGBM_BoosterGetEval(booster, 0, ...)观察指标保存与释放LGBM_BoosterSaveModel(...)、LGBM_BoosterFree、LGBM_DatasetFree加载并预测LGBM_BoosterCreateFromModelfile→LGBM_BoosterPredictForMat/LGBM_BoosterPredictForFile多线程场景用LGBM_SetMaxThreads全局限制线程数。工程实践要点内存管理DatasetHandle、BoosterHandle、FastConfigHandle、稀疏输出内存均由调用方负责释放必须严格配对Free调用防止泄漏预分配与两段式查询凡带字符串或数组输出的函数普遍采用先查长度、再分配、再调用或传入buffer_len不满足时由out_len告知实际大小的约定如LGBM_BoosterSaveModelToString、LGBM_BoosterGetEvalNames、LGBM_DatasetGetFeatureNames编码时应始终检查返回长度并做好重分配参数格式统一所有parameters均为空格分隔的keyvalue字符串与 examples/binary_classification/train.conf 中 CLI 配置的键完全一致可直接照搬配置项精度纪律严格遵循各接口的精度约定——label/weight 传 float32、init_score 传 float64、group/position 传 int32、梯度与 Hessian 仅 float32错误检查每个调用都检查返回值-1时立即用LGBM_GetLastError()取错误信息这是定位参数拼写错误如num_leaves写成num_leaf的最直接手段。小结LightGBM 的 C API 以 include/LightGBM/c_api.h 为契约、以 src/c_api.cpp约 3000 行为实现覆盖了从 Dataset 构建文件/稠密/CSR/CSC/流式/Arrow、Booster 训练迭代推进、自定义梯度、回退、合并、四种预测模式、快速单行推理到分布式网络初始化的全部能力并被 Python 包与测试用例tests/c_api_test/test_.py充分验证。无论是为生产系统编写 C/C 推理服务、用 Rust/Go 等语言通过 FFI 对接 LightGBM还是深入理解 Python 封装背后的调用链这份头文件都是最权威、最完整的参考手册。【免费下载链接】LightGBMA fast, distributed, high performance gradient boosting (GBT, GBDT, GBRT, GBM or MART) framework based on decision tree algorithms, used for ranking, classification and many other machine learning tasks.项目地址: https://gitcode.com/GitHub_Trending/li/LightGBM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考