模型代码如何从能跑变可靠？Python 工程化与单元测试一文讲透
Notebook 里跑通了，为什么上线前还要重构代码？
一个特征函数改错了，为什么可能影响几万笔审批？
单元测试听起来像后端工程师的事，风控建模工程师为什么也必须会？
上一篇文章中，我们讲了 Linux、Git、Shell、Docker。
这些工具帮助风控建模工程师从本地实验走向服务器、协作和部署。
这一篇，我们继续讲工程落地能力中的另一块核心内容：
很多同学刚开始做模型时，习惯把所有逻辑写在一个 Notebook 里：
探索阶段这样做没问题。
但如果这段代码要进入真实业务，就会出现问题：
所以，风控建模工程师不仅要会写 Python，还要会把 Python 写成工程。
一句话：
实验代码解决“能不能做”，工程代码解决“能不能稳定长期做”。
Python 工程化不是把代码写得很复杂。
恰恰相反，它的目标是让代码更清楚、更稳定、更容易维护。
可以简单理解为：
把零散脚本整理成结构清晰、可复用、可测试、可部署的项目。
对于风控模型项目来说，工程化通常包括：
工程化不是为了“看起来高级”。
它是为了减少线上事故。
风控模型和普通数据分析不同。
它会直接影响业务决策。
一个小错误，可能带来真实损失。
1. 特征口径错了，模型分数就会错
例如特征定义是：
但代码里不小心写成：
或者时间窗口包含了申请日之后的数据。
这就可能造成时间穿越或口径错误。
2. 缺失值处理不一致，线上线下结果不一致
训练时缺失值填充为 -999。
线上评分时缺失值填充为 0。
模型分数可能完全不同。
这类问题非常常见，也非常隐蔽。
3. 模型版本不清楚，回溯困难
线上出了问题后，团队需要回答：
如果项目没有工程化，回溯会变成考古。
4. 改代码没有测试，风险不可控
比如你改了一个 WOE 转换函数。
看起来只是优化了一行代码。
但它可能影响所有评分卡变量。
如果没有测试，只有等线上指标异常后才发现。
这就太晚了。
Notebook 适合探索。
工程项目适合交付。
二者不是敌人，而是不同阶段的工具。
1. Notebook 适合做什么？
2. Notebook 不适合做什么？
3. 代码沉淀的过程
一个比较健康的过程是：
1Notebook 探索
2 ↓
3整理成 Python 函数
4 ↓
5拆成模块
6 ↓
7加入配置和日志
8 ↓
9加入单元测试
10 ↓
11接入训练/评分流水线
12 ↓
13上线部署和监控
探索阶段可以灵活。
交付阶段必须规范。
一个比较清晰的项目可以这样组织：
1risk_model_project/
2 ├── README.md
3 ├── requirements.txt
4 ├── pyproject.toml
5 ├── config/
6 │ ├── train.yaml
7 │ ├── score.yaml
8 │ └── monitor.yaml
9 ├── sql/
10 │ ├── extract_train_sample.sql
11 │ └── extract_score_sample.sql
12 ├── src/
13 │ └── risk_model/
14 │ ├── __init__.py
15 │ ├── data.py
16 │ ├── features.py
17 │ ├── binning.py
18 │ ├── train.py
19 │ ├── evaluate.py
20 │ ├── score.py
21 │ ├── monitor.py
22 │ └── utils.py
23 ├── tests/
24 │ ├── test_features.py
25 │ ├── test_binning.py
26 │ ├── test_score.py
27 │ └── test_monitor.py
28 ├── scripts/
29 │ ├── run_train.sh
30 │ └── run_score.sh
31 ├── models/
32 ├── reports/
33 └── notebooks/
目录怎么理解？
这种结构的好处是：
模块化的意思是：
例如：
为什么要模块化？
因为风控模型流程很长。
如果所有逻辑写在一个文件里：
模块化后，一个函数只做一件事。
例如：
1def debt_income_ratio(monthly_debt: float, monthly_income: float) -> float:
2 if monthly_income <= 0:
3 return -1.0
4 return monthly_debt / monthly_income
这个函数很简单，但它有清楚的输入、输出和异常处理。
这就是工程化的开始。
很多新手喜欢在代码里写死参数：
1train_start = "2025-01-01"
2train_end = "2025-08-31"
3model_type = "lightgbm"
4threshold = 0.12
这样做的问题是：
更好的方式是放到配置文件里。
例如 train.yaml：
1sample:
2 train_start: "2025-01-01"
3 train_end: "2025-08-31"
4 oot_start: "2025-09-01"
5 oot_end: "2025-10-31"
6
7model:
8 type: "lightgbm"
9 learning_rate: 0.05
10 num_leaves: 31
11 min_data_in_leaf: 500
12
13strategy:
14 reject_threshold: 0.12
代码只负责读取配置。
这样训练、评分、监控都可以通过配置驱动。
探索时用 print没问题。
生产任务要用日志。
日志可以帮助我们回答：
一个简单日志示例
1import logging
2
3logging.basicConfig(
4 level=logging.INFO,
5 format="%(asctime)s %(levelname)s %(message)s"
6)
7
8logger = logging.getLogger(__name__)
9
10logger.info("start training model")
11logger.info("train sample size: %s", len(train_df))
12logger.info("model auc: %.4f", auc)
风控任务建议记录什么？
日志不是摆设。
它是线上问题排查的第一手证据。
很多人写代码时喜欢“吞掉异常”。
例如：
1try:
2 score = model.predict(x)
3except:
4 score = 0
这很危险。
如果模型预测失败，却默认给 0 分，可能会让高风险客户被错误通过。
更好的做法是：
例如：
1try:
2 score = model.predict(x)
3except ValueError as e:
4 logger.exception("model predict failed: %s", e)
5 raise
风控系统宁愿明确失败，也不要安静地错。
1. 什么是单元测试？
单元测试就是测试一个很小的代码单元。
通常是一个函数或一个类。
例如：
单元测试的目标是：
2. 为什么风控建模需要单元测试？
因为风控代码里有很多关键逻辑。
例如：
这些问题一旦出错，影响的不是一张图，而是真实审批结果。
假设我们有一个函数：
1def debt_income_ratio(monthly_debt, monthly_income):
2 if monthly_income <= 0:
3 return -1
4 return monthly_debt / monthly_income
我们可以写测试：
1from risk_model.features import debt_income_ratio
2
3def test_debt_income_ratio_normal():
4 assert debt_income_ratio(2000, 10000) == 0.2
5
6def test_debt_income_ratio_zero_income():
7 assert debt_income_ratio(2000, 0) == -1
运行：
如果测试通过，说明这个函数至少在这些场景下表现符合预期。
测试不是为了证明代码完美
测试是为了尽早发现低级错误。
尤其是在别人改代码后，测试可以提醒：
不是所有代码都要一开始写满测试。
优先测试高风险逻辑。
1. 特征计算函数
例如：
这些特征直接影响模型分数。
2. 分箱和 WOE 映射
要测试：
例如年龄分箱：
3. PSI、KS、AUC 等指标计算
指标函数要稳定。
尤其要处理：
4. 评分逻辑
例如：
5. 策略决策逻辑
例如：
1score >= 700：通过
2600 <= score < 700：复核
3score < 600：拒绝
要测试边界值：
边界值最容易出错。
单元测试不需要真实大数据。
它需要小而明确的数据。
例如：
1import pandas as pd
2
3df = pd.DataFrame({
4 "monthly_debt": [1000, 2000, 3000],
5 "monthly_income": [5000, 0, 10000],
6})
测试数据要做到：
不要为了测试一个函数，去连生产库。
单元测试应该快速、稳定、可重复。
工程化不仅是代码能跑，还包括代码能读。
建议做到：
不好的命名
1def f(x):
2 return x[0] / x[1]
更好的命名
1def calculate_debt_income_ratio(monthly_debt, monthly_income):
2 if monthly_income <= 0:
3 return -1
4 return monthly_debt / monthly_income
风控代码经常需要被审计、复盘和交接。
写清楚，是对未来的自己友好。
模型项目要记录依赖版本。
常见文件：
1requirements.txt
2pyproject.toml
3poetry.lock
4conda.yaml
例如：
1pandas==2.2.2
2numpy==1.26.4
3scikit-learn==1.5.1
4lightgbm==4.5.0
5pyyaml==6.0.2
6pytest==8.3.2
为什么要固定版本？
因为不同版本可能导致：
模型可复现，不只是数据和代码可复现，还包括环境可复现。
除了单元测试，还可以用一些工具提高代码质量。
例如：
1pytest tests/
2ruff check src/
3black src/ tests/
这些工具不会替代业务判断。
但它们能减少低级错误。
假设你要开发一个 PSI 监控模块。
第一步：先在 Notebook 中验证
用样例数据算出 PSI，确认逻辑正确。
第二步：沉淀成函数
1def calculate_psi(expected, actual, bins):
2 ...
第三步：写单元测试
测试：
第四步：加入日志和配置
配置基准样本、当前样本、分箱方式和预警阈值。
第五步：接入监控脚本
通过 Shell 或调度平台定时运行。
第六步：纳入 Git 和代码审查
所有代码、配置、测试都提交到仓库。
这就是从探索代码到工程模块的过程。
1. Python 工程化主要解决什么问题？
它解决代码可维护、可复用、可测试、可部署、可追溯的问题。
对于风控模型来说，工程化可以降低线上风险，提高模型复现和协作效率。
2. 为什么不能只用 Notebook 做生产？
Notebook 适合探索，但不适合长期维护、自动化运行、多人协作、版本管理和测试。
生产代码应沉淀为模块化 Python 代码、配置文件和运行脚本。
3. 单元测试在风控项目中有什么作用？
单元测试可以验证关键函数在给定输入下是否输出预期结果。
它能帮助提前发现特征计算、分箱、评分、指标计算和策略边界中的错误。
4. 哪些风控代码最应该写测试？
优先测试：
5. 配置文件有什么价值？
配置文件可以把样本时间、模型参数、路径、阈值等从代码中分离出来，便于复现、修改、上线和版本管理。
6. 日志应该记录什么？
建议记录样本范围、样本量、好坏样本数、参数、指标、模型路径、任务耗时、异常信息和关键数据质量结果。
坑 1：所有逻辑堆在一个 Notebook
探索可以，交付不行。
坑 2：函数太长，一改全动
函数应该职责单一。
坑 3：参数写死在代码里
样本时间、路径、阈值、模型参数要配置化。
坑 4：没有日志
任务失败后不知道哪里出错。
坑 5：异常被悄悄吞掉
风控系统最怕安静地出错。
坑 6：没有单元测试
每次改代码都像拆盲盒。
坑 7：测试依赖生产库
单元测试应该小、快、稳定，不依赖外部系统。
坑 8：没有依赖版本
包版本变化可能导致模型结果变化。
坑 9：不写 README
别人不知道项目怎么安装、怎么运行、怎么测试。
坑 10：上线代码和实验代码不一致
这会导致离线效果和线上表现对不上。
风控建模不是只追求模型指标。
模型指标再好，如果代码不可维护、不可测试、不可复现，也很难稳定产生业务价值。
Python 工程化和单元测试的意义，不是让代码变复杂，而是让模型项目更可靠。
如果用一句话总结本文：
工程化让模型代码可复用、可维护、可部署，单元测试让关键逻辑可验证、可放心修改。
下一篇，我们可以继续聊：
工程落地能力中的模型部署、接口服务、批量评分和实时评分，风控模型如何真正进入业务系统？
如果你正在学习金融风控建模，可以先记住这句话：
Notebook 证明你能做出模型，工程化和测试证明你的模型代码能被团队长期信任。
10个月宝宝每天需要喝多少奶粉？
