4. 模型开发文档规范：文档结构、版本控制、变更记录、可追溯性要求
模型开发文档，说白了就是风控模型的「出生证明」和「成长日记」。
我见过太多团队，模型做得漂亮，但文档一塌糊涂。监管一来，问三个问题就卡住了：谁做的？什么时候改的？为什么这么改？
嗯，今天我们就聊聊怎么把文档这件事做扎实。
4.1 文档结构：骨架要清晰
我个人习惯把模型文档分成三大块：项目背景、技术细节、运维记录。你想想看，这三块正好对应了「为什么做」「怎么做」「做得怎么样」。
标准文档结构（我推荐用这个模板）：
- 封面与元数据 — 模型名称、版本号、创建日期、责任人
- 项目背景 — 业务需求、数据来源、建模目标
- 数据探索与预处理 — 变量分布、缺失值处理、异常值剔除
- 模型开发 — 算法选择、参数调优、变量筛选
- 模型验证 — 区分度、稳定性、校准度
- 模型部署 — 上线策略、接口说明、监控方案
- 附录 — 代码清单、会议纪要、审批记录
我在项目中遇到过一件事：有个同事把数据清洗的代码和模型训练的代码混在一个文档里。后来模型出了问题，排查了三天才发现是数据预处理阶段有个字段类型搞错了。从那以后，我要求每个阶段必须独立成章。
小技巧：每个章节开头加一段「本章目标」，写清楚这章要解决什么问题。比如「本章说明如何对收入字段进行分箱处理」。这样别人读文档时，一眼就知道重点在哪。
4.2 版本控制：别让文档变成一团乱麻
版本控制这件事，我吃过亏。曾经有个项目，模型迭代了七八次，但文档只有一个「最终版.docx」。你猜怎么着？后来发现那个「最终版」其实是第三版的内容，后面五次修改全都没记录进去。
为什么会这样？说白了就是没有版本管理意识。
我建议用语义化版本号：
| 版本号 | 含义 | 举例 |
|---|---|---|
| v1.0.0 | 首次发布 | 模型第一次上线 |
| v1.1.0 | 功能更新 | 新增一个变量 |
| v1.1.1 | 补丁修复 | 修正一个计算错误 |
| v2.0.0 | 重大变更 | 算法从逻辑回归换成XGBoost |
注意：版本号一旦发布，就不能修改。如果发现错误，只能发布新版本。这是审计的基本要求——保证历史版本不可篡改。
实际操作中，我习惯用Git管理文档。每次提交都写清楚commit message，格式是「版本号 + 变更类型 + 简要说明」。比如：
v1.1.0 - 新增 - 增加「近6个月逾期次数」变量
v1.1.1 - 修复 - 修正WOE计算中分母为0的异常处理
v2.0.0 - 重构 - 从逻辑回归切换为LightGBM，AUC提升3%4.3 变更记录：每一笔改动都要有据可查
变更记录是审计最关注的部分。监管来了，第一件事就是翻变更记录。
我建议每份文档末尾都附一张变更记录表，格式如下：
| 日期 | 版本 | 变更内容 | 变更人 | 审批人 | 变更原因 |
|---|---|---|---|---|---|
| 2024-01-15 | v1.0.0 | 初始版本 | 张三 | 李四 | 首次建模 |
| 2024-03-20 | v1.1.0 | 增加收入分箱调整 | 王五 | 李四 | 业务反馈低收入群体区分度不足 |
| 2024-06-10 | v2.0.0 | 算法切换为XGBoost | 张三 | 赵六 | 原模型稳定性下降，PSI超过0.15 |
我曾经遇到过一个案例：某银行被监管处罚，原因就是变更记录里只写了「优化模型」，但没写具体优化了什么。监管认为这是「黑箱操作」。所以，变更原因一定要写清楚，不能含糊。
避坑指南：我曾经见过有人把变更记录写在邮件里，文档里没有。结果那人离职了，邮件也找不到了。记住：所有变更记录必须沉淀在文档里，不能依赖任何人的记忆或邮件。
4.4 可追溯性要求：从数据到决策，每一步都能回查
可追溯性，说白了就是「反向查找」。给你一个模型结果，你能一路追溯到原始数据吗？
我要求团队做到「三可追溯」：
- 数据可追溯：每个变量都能找到原始数据源、加工逻辑、转换公式
- 代码可追溯：每个模型版本都有对应的代码版本，代码和文档一一对应
- 决策可追溯：每个审批节点都有记录，谁在什么时间批准了什么
举个例子，如果模型输出一个客户的信用评分是650分，你应该能回答：
- 这个分数用了哪些变量？（比如收入、负债、历史逾期）
- 这些变量是怎么算出来的？（比如收入是取近6个月均值）
- 原始数据从哪里来的？（比如来自核心系统表T_CUST_INCOME）
- 这个版本的模型是谁开发的？谁审批的？
我习惯在文档里加一个「数据血缘图」，用表格形式展示每个变量的完整链路：
| 变量名 | 原始表 | 原始字段 | 加工逻辑 | 转换函数 | 代码行号 |
|---|---|---|---|---|---|
| income_avg | T_CUST_INCOME | monthly_income | 近6个月均值 | mean() | feature_eng.py:45 |
| debt_ratio | T_CUST_LOAN | total_debt | 总负债/总收入 | divide() | feature_eng.py:78 |
监管红线：可追溯性不是可选项，是必选项。银保监会《商业银行互联网贷款管理暂行办法》明确要求，模型开发过程必须完整记录，确保可追溯。做不到这一点，合规审计直接亮红灯。
4.5 知识体系总览
下面这张图，是我梳理的模型文档规范核心逻辑。你看一眼就能明白整个框架：
这张图把四个核心要素串起来了。你写文档时，就按这个框架来，保证不会漏项。
最后说一句：文档不是写给监管看的，是写给未来的自己看的。半年后你回头看自己写的模型，如果文档写得清楚，你能省下80%的回忆时间。我吃过这个亏，所以现在特别较真。
公众号:蓝海资料掘金营，微信deep3321