📚 课程目录第3章环境搭建

3. 环境搭建：安装LightGBM、SHAP库、Jupyter Notebook及依赖包配置

在开始模型训练与可解释性分析之前，必须搭建一个稳定、兼容的Python环境。本章将指导你完成LightGBM、SHAP、Jupyter Notebook及核心依赖库的安装与验证。推荐使用虚拟环境隔离项目依赖，避免与系统全局包冲突。

3.1 环境总览与版本兼容性

以下表格列出了本课程所需的核心库及其推荐版本。请确保各库版本满足兼容性要求，否则可能导致SHAP值计算异常或LightGBM训练报错。

库名称	推荐版本	主要用途	依赖关系
Python	3.8 – 3.11	运行环境基础	—
lightgbm	≥ 3.3.5	梯度提升树模型训练	numpy, scipy
shap	≥ 0.41.0	SHAP值计算与可视化	numpy, pandas, scipy, matplotlib
jupyter	≥ 1.0.0	交互式编程与演示	ipykernel, nbformat
pandas	≥ 1.4.0	数据处理与特征工程	numpy
numpy	≥ 1.21.0	数值计算基础	—
matplotlib	≥ 3.5.0	基础图表绘制	numpy
scikit-learn	≥ 1.0.0	数据集切分、评估指标	numpy, scipy

版本提示： 如果你使用Python 3.12或更高版本，部分旧版LightGBM和SHAP可能尚未提供预编译wheel包。建议使用Python 3.10以获得最稳定的兼容性。

3.2 安装步骤（基于pip）

以下步骤在终端或命令行中执行。假设你已经安装了Python 3.8+ 和 pip。

创建并激活虚拟环境（推荐）

# 创建虚拟环境
python -m venv lgbm_shap_env

# Windows激活
lgbm_shap_env\Scripts\activate

# macOS / Linux激活
source lgbm_shap_env/bin/activate

升级pip并安装核心库

pip install --upgrade pip
pip install numpy pandas matplotlib scikit-learn jupyter

安装LightGBM
```
pip install lightgbm
```
如果安装速度慢，可添加国内镜像源，例如：pip install lightgbm -i https://pypi.tuna.tsinghua.edu.cn/simple
安装SHAP
```
pip install shap
```

验证安装

python -c "import lightgbm as lgb; print('LightGBM version:', lgb.__version__)"
python -c "import shap; print('SHAP version:', shap.__version__)"
python -c "import jupyter; print('Jupyter version:', jupyter.__version__)"

如果上述命令均打印出版本号且无报错，则环境搭建成功。

一键安装命令（复制整段执行）：

pip install numpy pandas matplotlib scikit-learn jupyter lightgbm shap

3.3 环境依赖关系与数据流

下图展示了各库之间的依赖关系以及数据在模型训练与SHAP解释流程中的传递路径。理解这一架构有助于后续调试环境问题。

3.4 常见安装问题与解决方案

错误现象	可能原因	解决方案
`ModuleNotFoundError: No module named 'lightgbm'`	未安装或安装到错误环境	确认虚拟环境已激活，重新执行 `pip install lightgbm`
`OSError: [WinError 126] 找不到指定的模块`	Windows下缺少Visual C++运行时	安装 VC++ Redistributable 或使用conda安装：`conda install lightgbm`
`ImportError: cannot import name 'TreeExplainer' from 'shap'`	SHAP版本过旧	升级SHAP：`pip install --upgrade shap`
`Jupyter notebook 启动后内核报错`	ipykernel未正确注册	执行 `python -m ipykernel install --user --name=lgbm_shap_env`
`pip install 速度极慢或超时`	默认源在国外	使用国内镜像：`pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名`

3.5 验证环境：快速运行测试脚本

将以下代码保存为 test_env.py 并执行，若输出“环境验证通过”则说明所有组件正常工作。

import numpy as np
import pandas as pd
import lightgbm as lgb
import shap
import matplotlib.pyplot as plt
from sklearn.model_selection import train_test_split

# 生成测试数据
X, y = shap.datasets.boston()
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# 训练LightGBM模型
model = lgb.LGBMRegressor(n_estimators=50, max_depth=4, random_state=42)
model.fit(X_train, y_train)

# 计算SHAP值
explainer = shap.TreeExplainer(model)
shap_values = explainer.shap_values(X_test)

# 验证输出形状
assert shap_values.shape == X_test.shape, "SHAP值形状不匹配"
print("环境验证通过：LightGBM + SHAP 安装正确，可正常计算SHAP值。")

注意： 如果使用 shap.datasets.boston() 提示数据集已弃用，请替换为 shap.datasets.california() 或自行构造随机数据。本课程后续章节将使用真实业务数据集。

3.6 推荐开发工具配置

除了核心库，以下工具能显著提升开发效率：

Jupyter Lab（推荐替代传统Notebook）：pip install jupyterlab，启动命令 jupyter lab
VS Code + Jupyter扩展：支持直接在编辑器内运行单元格，调试更方便
conda（可选）：如果pip安装遇到二进制依赖问题，可使用 conda install -c conda-forge lightgbm shap

至此，环境搭建全部完成。你已经拥有了运行本课程所有实战案例的基础设施。