工程实现

本章目标

理解 LightGBM 流水线的模块分层——数据生成层、模型训练层、流水线编排层、可视化层。
理清 run() 内部的函数调用链和数据流动路径。
理解 LightGBM 与 GBDT 在工程实现上的关键差异——可选依赖处理、num_leaves 替代 max_depth、无学习曲线、训练层有装饰器。

重点方法与概念速览

名称	类型	作用
`EnsembleData.lightgbm()`	方法	生成高维多类别分类数据——`make_classification(n_features=20, n_classes=4)`
`train_model(...)`	函数	构建并训练 `LGBMClassifier`——含可选依赖检查和装饰器（`@print_func_info`、`@timeit`）
`run()`	函数	端到端流水线编排——串联数据准备、标准化、训练、预测和三项可视化
`plot_confusion_matrix(...)`	函数	绘制测试集混淆矩阵（4×4 多分类热力图）
`plot_roc_curve(...)`	函数	绘制多分类 ROC 曲线（one-vs-rest）
`plot_feature_importance(...)`	函数	绘制特征重要性柱状图（20 个特征排序）

1. 模块分层总览

参数速览

层	文件	职责	输出
数据生成层	`data_generation/ensemble.py` → `data_generation/__init__.py`	生成四分类高维数据并导出 `lightgbm_data`	全局 `DataFrame`（1000 行 × 21 列）
模型训练层	`model_training/ensemble/lightgbm.py`	封装 `LGBMClassifier` 训练——含 `ImportError` 处理 + 装饰器	`LGBMClassifier` 模型对象
流水线编排层	`pipelines/ensemble/lightgbm.py`	串联数据准备、标准化、训练、预测和三项评估——端到端入口	终端日志 + 调用三个可视化函数
可视化层	`result_visualization/confusion_matrix.py`、`roc_curve.py`、`feature_importance.py`	生成三项评估图表	3 个 PNG 文件

理解重点

LightGBM 的可视化层与 GBDT 共享三个模块——但没有 learning_curve.py，评估项比 GBDT 少一项。
训练层有三重保护：try/except ImportError（可选依赖）+ @print_func_info（调用日志）+ @timeit（耗时日志）。
与 GBDT 的核心工程差异：（1）可选依赖处理；（2）num_leaves 替代 max_depth 控制复杂度；（3）内部直方图加速 + n_jobs=-1 特征级并行。

2. `run()` 内部的函数调用链

参数速览

序号	调用	输入	输出	目的
1	`lightgbm_data.copy()`	—	`DataFrame`，形状 `(1000, 21)`	避免修改全局变量
2	`data.drop(columns=["label"])`	`DataFrame`	`DataFrame`，形状 `(1000, 20)`	分离 20 维特征 X
3	`data["label"]`	`DataFrame`	`Series`，形状 `(1000,)`	分离四分类标签 y
4	`list(X.columns)`	`DataFrame`	`list[str]`，长度 20	提取特征名——供特征重要性图表使用
5	`train_test_split(X, y, test_size=0.2, stratify=y)`	`(DataFrame, Series)`	`(X_train, X_test, y_train, y_test)`	分层训练/测试切分
6	`scaler.fit_transform(X_train)`	`DataFrame`，形状 `(800, 20)`	`ndarray`，形状 `(800, 20)`	训练集标准化
7	`scaler.transform(X_test)`	`DataFrame`，形状 `(200, 20)`	`ndarray`，形状 `(200, 20)`	测试集标准化
8	`train_model(X_train_s, y_train)`	`(ndarray, Series)`	`LGBMClassifier`	训练 300 棵 Leaf-wise 直方图树
9	`model.predict(X_test_s)`	`ndarray`，形状 `(200, 20)`	`ndarray`，形状 `(200,)`	硬预测（加权累加 + softmax + argmax）
10	`plot_confusion_matrix(y_test, y_pred, ...)`	`(Series, ndarray)`	PNG 文件	4×4 混淆矩阵可视化
11	`model.predict_proba(X_test_s)`	`ndarray`，形状 `(200, 20)`	`ndarray`，形状 `(200, 4)`	软概率输出（softmax）
12	`plot_roc_curve(y_test, y_scores, ...)`	`(Series, ndarray)`	PNG 文件	多分类 ROC 曲线
13	`plot_feature_importance(model, feature_names, ...)`	`(model, list)`	PNG 文件	20 个特征重要性排序柱状图

理解重点

步骤 8 内部触发 lightgbm 可选依赖检查——如果未安装会抛出 ImportError。
步骤 9-12 与 GBDT 完全一致——说明 LightGBM 的 scikit-learn 兼容接口与 GradientBoostingClassifier 的方法签名一致（predict/predict_proba）。
与 GBDT 对比：LightGBM 流水线少了一步（无学习曲线），但数据规模更大（1000 样本 vs 500 样本）。

3. 数据依赖关系

lightgbm_data (全局 DataFrame)
    │
    ├─→ X = data.drop(columns=["label"])  ──→ feature_names = list(X.columns) ──┐
    ├─→ y = data["label"]                                                        │
    │                                                                             │
    ├─→ train_test_split(X, y, test_size=0.2, stratify=y)                        │
    │   ├─→ X_train (800, 20) ──→ scaler.fit_transform() ──→ X_train_s ──┐      │
    │   ├─→ y_train (800,) ─────────────────────────────────────────────┤      │
    │   │                                                                 │      │
    │   ├─→ X_test (200, 20) ──→ scaler.transform() ──→ X_test_s ──┐    │      │
    │   └─→ y_test (200,) ─────────────────────────────────┐       │    │      │
    │                                                       │       │    │      │
    │   ┌───────────────────────────────────────────────────┘       │    │      │
    │   │                                                           │    │      │
    │   │  train_model(X_train_s, y_train) ──→ model               │    │      │
    │   │      │                                                     │    │      │
    │   │      ├─→ model.predict(X_test_s) ──→ y_pred ──┐          │    │      │
    │   │      │                                         │          │    │      │
    │   │      ├─→ model.predict_proba(X_test_s) ──→ y_scores ──┐  │    │      │
    │   │      │                                                  │  │    │      │
    │   │      ├─→ model.feature_importances_ ──→ + feature_names ──┼──┼──────┘  │
    │   │      │                                                  │  │          │
    │   │      plot_confusion_matrix(y_test, y_pred, ...) ←───────┘  │          │
    │   │      plot_roc_curve(y_test, y_scores, ...) ←───────────────┘          │
    │   │      plot_feature_importance(model, feature_names, ...) ←─────────────┘
    │   │
    │   └──────────────────────────────────────────────────────────────────────┘

理解重点

数据流比 GBDT 少一个 plot_learning_curve 分支——结构更简洁。
y_train 仅参与训练——与 GBDT 不同（GBDT 的 y_train 还参与学习曲线）。
特征重要性依赖 model.feature_importances_ 和 feature_names——两个数据来自不同阶段，在可视化层交汇。

4. 输出文件一览

参数速览

输出项	路径	格式	说明
混淆矩阵	`outputs/lightgbm/confusion_matrix.png`	PNG	测试集 4×4 混淆矩阵热力图
ROC 曲线	`outputs/lightgbm/roc_curve.png`	PNG	多分类 ROC（one-vs-rest，4 类）
特征重要性	`outputs/lightgbm/feature_importance.png`	PNG	20 个特征的重要性排序柱状图
终端日志	标准输出	文本	训练超参数 + 运行耗时

示例代码

bash

python -m pipelines.ensemble.lightgbm

输出

text

============================================================
LightGBM 分类流水线
============================================================
模型训练完成
n_estimators: 300
learning_rate: 0.05
num_leaves: 31
max_depth: -1
subsample: 0.9
colsample_bytree: 0.9
模型训练耗时: 0.43s

============================================================
LightGBM 流水线完成！
============================================================

理解重点

LightGBM 输出 3 个 PNG 文件——比 GBDT 少 1 个（无学习曲线），比 Bagging 多 1 个（有特征重要性）。
训练耗时通常显著短于 GBDT（~0.4s vs ~2s）——直方图加速 + n_jobs=-1 特征级并行。
终端日志多了 num_leaves、subsample、colsample_bytree——反映 LightGBM 更细粒度的控制参数。

5. 训练层细节：与 GBDT 的对比

工程维度	GBDT (sklearn)	LightGBM
依赖	sklearn 内置——无需额外安装	可选依赖——`try/except ImportError`
基学习器	内部自动 `DecisionTreeRegressor`	内部直方图回归树（Leaf-wise 生长）
复杂度控制	`max_depth=3`（深度限制）	`num_leaves=31` + `max_depth=-1`（叶子数限制）
树数量	200	300
学习率	0.1	0.05
行采样	`subsample=1.0`（不使用）	`subsample=0.9`（行采样 + GOSS 思想）
列采样	无	`colsample_bytree=0.9`（列采样）
并行	无（纯串行）	`n_jobs=-1`（直方图构建和特征扫描级并行）
日志	`n_estimators, learning_rate, max_depth, subsample`	`n_estimators, learning_rate, num_leaves, max_depth, subsample, colsample_bytree`
装饰器	`timer`	`@print_func_info` + `@timeit` + `timer`
训练耗时	~2s	~0.4s

理解重点

LightGBM 的 max_depth=-1 不是"无限深度"——Leaf-wise 生长下，复杂度由 num_leaves 控制，max_depth=-1 表示不额外限制最大深度。
n_estimators=300 + learning_rate=0.05 的总修正量（15）小于 GBDT 的 200 × 0.1 = 20——但步子更多更稳。
LightGBM 的列采样（colsample_bytree=0.9）是 sklearn GBDT 不支持的——这是微软实现的独有正则化手段。

阅读顺序

data_generation/ensemble.py — 了解 lightgbm() 的数据生成逻辑（高维四分类）
model_training/ensemble/lightgbm.py — 理解 LGBMClassifier 的构建、可选依赖和 Leaf-wise 训练
pipelines/ensemble/lightgbm.py — 看清端到端流程和三项评估的串联
result_visualization/confusion_matrix.py — 了解混淆矩阵实现
result_visualization/roc_curve.py — 了解多分类 ROC 实现
result_visualization/feature_importance.py — 了解特征重要性图表实现

常见坑

在不含 lightgbm 的环境中直接 from model_training.ensemble.lightgbm import train_model——会触发 ImportError，需先 pip install lightgbm。
把 num_leaves=31 和 max_depth=-1 当成"树可以无限深"——叶子数限制实际上限定了树复杂度。
直接修改 lightgbm_data 而不先 copy()——会污染其他模块引用的同一全局变量。
在测试集上使用 fit_transform 而非 transform——标准信息泄露。

小结

LightGBM 工程实现遵循本仓库标准四层架构：数据生成层 → 模型训练层 → 流水线编排层 → 可视化层（含 3 个模块）。
run() 是薄编排函数——13 步调用串联数据准备、标准化、训练、预测和三项评估。
与 GBDT 的四个关键工程差异：（1）可选依赖 try/except；（2）num_leaves 替代 max_depth；（3）多了 colsample_bytree 列采样；（4）少一项评估（无学习曲线）。

工程实现 ​

本章目标 ​

重点方法与概念速览 ​

1. 模块分层总览 ​

参数速览 ​

理解重点 ​

2. run() 内部的函数调用链 ​

参数速览 ​

理解重点 ​

3. 数据依赖关系 ​

理解重点 ​

4. 输出文件一览 ​

参数速览 ​

示例代码 ​

输出 ​

理解重点 ​

5. 训练层细节：与 GBDT 的对比 ​

理解重点 ​

阅读顺序 ​

常见坑 ​

小结 ​

工程实现

本章目标

重点方法与概念速览

1. 模块分层总览

参数速览

理解重点

2. `run()` 内部的函数调用链

参数速览

理解重点

3. 数据依赖关系

理解重点

4. 输出文件一览

参数速览

示例代码

输出

理解重点

5. 训练层细节：与 GBDT 的对比

理解重点

阅读顺序

常见坑

小结