2. 项目环境搭建：Python虚拟环境配置、依赖库安装与项目目录结构设计
在开始开发可解释评分接口之前，必须搭建一个隔离、可复现的Python开发环境。本章将指导你完成从虚拟环境创建、核心依赖库安装到项目目录结构设计的全过程，确保后续开发工作在一个干净、标准化的环境中进行。
2.1 Python虚拟环境配置
虚拟环境是Python项目开发的基石，它能够为每个项目创建独立的依赖包空间，避免不同项目间的版本冲突。本课程统一使用Python 3.9+版本，推荐使用venv模块（Python 3.3+内置）进行环境管理。
2.1.1 创建虚拟环境
在项目根目录下执行以下命令，创建一个名为.venv的虚拟环境（.venv是行业惯例，表示隐藏的虚拟环境目录）：
# Linux / macOS
python3 -m venv .venv
# Windows
python -m venv .venv2.1.2 激活虚拟环境
激活后，终端提示符前会出现(.venv)标识，表示当前已进入隔离环境：
# Linux / macOS (bash/zsh)
source .venv/bin/activate
# Windows (CMD)
.venv\Scripts\activate.bat
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
💡 最佳实践： 将
.venv目录添加到.gitignore文件中，避免将虚拟环境提交到版本控制系统。团队成员只需通过requirements.txt即可重建完全一致的环境。
2.2 核心依赖库安装
本案例涉及数据处理、机器学习建模、模型解释和API服务四个技术栈。下表列出了核心依赖库及其在本项目中的具体用途：
| 库名称 | 版本要求 | 核心用途 | 安装命令 |
|---|---|---|---|
| pandas | ≥1.4.0 | 数据加载、清洗、特征工程与评分卡数据预处理 | pip install pandas |
| scikit-learn | ≥1.1.0 | 逻辑回归模型训练、特征分箱、评分卡刻度转换 | pip install scikit-learn |
| flask | ≥2.3.0 | RESTful API接口开发，接收请求并返回拒贷原因解释 | pip install flask |
| shap | ≥0.42.0 | 基于Shapley值的全局/局部特征重要性解释 | pip install shap |
| lime | ≥0.2.0 | 局部可解释模型，为单笔拒贷样本生成解释 | pip install lime |
执行批量安装命令：
# 确保虚拟环境已激活
pip install pandas scikit-learn flask shap lime
# 验证安装版本
pip list | grep -E "pandas|scikit-learn|flask|shap|lime"
⚠️ 版本兼容性注意： SHAP库对
numpy和scikit-learn的版本有较强依赖。如果安装过程中出现依赖冲突，建议使用pip install --upgrade numpy scipy先升级基础科学计算库，再重新安装SHAP。
2.3 项目目录结构设计
良好的目录结构是项目可维护性的关键。本案例采用分层架构设计，将数据、模型、API逻辑和解释模块清晰分离。下图展示了完整的项目目录树：
2.4 各模块职责说明
下表详细描述了每个目录和核心文件的职责，帮助你在后续开发中快速定位代码位置：
| 目录/文件 | 职责描述 | 关键产出物 |
|---|---|---|
| data/raw/ | 存放原始风控数据集（CSV格式），包含用户特征和逾期标签 | 原始数据文件 |
| data/processed/ | 存放经过清洗、分箱、WOE编码后的建模数据 | 训练集、测试集 |
| data/features.json | 特征元数据配置文件，定义特征类型、分箱边界和业务含义 | 特征字典 |
| models/lr_model.pkl | 训练好的逻辑回归模型序列化文件，用于评分和解释 | 模型对象 |
| models/scorecard.py | 评分卡刻度转换逻辑，将模型预测概率转换为标准分数 | 评分函数 |
| models/binning.json | 特征分箱结果配置文件，记录每个特征的分箱区间和WOE值 | 分箱映射表 |
| api/app.py | Flask应用入口，初始化APP并注册路由蓝图 | WSGI应用 |
| api/routes.py | 定义RESTful接口路由，处理评分请求和解释请求 | API端点 |
| api/schemas.py | 请求/响应数据模型定义，使用Pydantic或dataclass进行校验 | 数据契约 |
| explainers/shap_explainer.py | 封装SHAP解释器，提供全局特征重要性和局部Shapley值计算 | 解释结果 |
| explainers/lime_explainer.py | 封装LIME解释器，为单笔样本生成局部可解释模型 | 解释结果 |
| explainers/reason_codes.py | 拒贷原因码映射逻辑，将解释结果转化为业务可读的拒绝原因 | 原因码列表 |
| requirements.txt | 项目依赖清单，使用pip freeze > requirements.txt生成 |
依赖文件 |
| config.yaml | 全局配置文件，包含模型路径、API端口、解释器参数等 | 配置参数 |
2.5 环境验证与依赖冻结
完成安装后，执行以下步骤验证环境正确性，并将依赖关系固化到requirements.txt：
- 验证导入： 在Python交互环境中依次导入所有核心库，确认无报错。
- 冻结依赖： 使用
pip freeze命令生成精确版本号的依赖清单。 - 创建目录结构： 使用
mkdir -p命令创建上述目录树。
# 步骤1：验证导入
python -c "import pandas; import sklearn; import flask; import shap; import lime; print('All libraries imported successfully!')"
# 步骤2：冻结依赖
pip freeze > requirements.txt
# 步骤3：创建目录结构（在项目根目录下执行）
mkdir -p data/raw data/processed
mkdir -p models
mkdir -p api
mkdir -p explainers
touch data/features.json models/binning.json api/__init__.py explainers/__init__.py config.yaml README.md
📌 关键提示：
__init__.py文件使api/和explainers/成为Python包，支持from api import app这样的模块导入方式。在Python 3.3+中，即使没有__init__.py，命名空间包也能工作，但为了兼容性和显式声明，建议保留。
2.6 环境搭建检查清单
在进入下一阶段开发前，请逐项确认以下检查点全部通过：
- ✅ 虚拟环境已激活，终端提示符显示
(.venv) - ✅ 五个核心库（pandas, sklearn, flask, shap, lime）均已成功安装且版本符合要求
- ✅
requirements.txt已生成并包含所有依赖及其精确版本号 - ✅ 项目目录结构完整，所有子目录和占位文件已创建
- ✅
.gitignore中已添加.venv/、__pycache__/、*.pkl等忽略规则 - ✅ 通过
python -c "import ..."验证所有库可正常导入
至此，项目环境搭建全部完成。你已经拥有了一个隔离、可复现的开发环境，以及清晰的项目目录结构。接下来的章节将基于此环境，逐步构建风控评分模型和可解释API接口。