4. 模型开发文档体系
在模型开发与可重复性审计中，文档不是“交付前的补充材料”，而是贯穿数据、特征、训练、评估、上线与复盘全过程的证据链。一个可审计的模型项目，通常需要五类文档协同工作：数据文档回答“数据从哪来、长什么样、能不能用”；特征文档回答“每个特征如何计算、口径是否稳定”；模型卡回答“模型是什么、适用边界在哪”；实验记录回答“这次结果由哪组参数和代码产生”；决策日志回答“为什么选这个方案、谁批准、何时变更”。五者缺一，审计时就会出现断点。
核心原则：文档体系的目标不是“写得多”，而是让任何一位未参与项目的工程师，仅凭文档就能复现关键结论、定位变更原因、判断模型是否可继续使用。
一、五类文档的构成与作用
| 文档类型 | 核心构成 | 主要作用 | 典型审计问题 |
|---|---|---|---|
| 数据文档 | 数据来源、采集时间、字段字典、样本量、缺失率、标签定义、授权与合规说明 | 证明数据可追溯、可使用、可复现 | 标签口径是否变更？训练集是否泄漏？ |
| 特征文档 | 特征名、业务含义、计算公式、依赖表、更新频率、缺失处理、版本号 | 保证特征口径一致，避免训练/推理偏移 | 线上特征与离线特征是否同源？ |
| 模型卡 | 模型类型、目标变量、训练数据范围、评估指标、适用场景、限制与风险 | 向业务方和审计方说明模型能力边界 | 模型是否被用于未声明场景？ |
| 实验记录 | 实验ID、代码提交号、参数配置、数据版本、指标结果、随机种子、环境依赖 | 支撑结果复现与对比分析 | 最优结果能否重新跑出？ |
| 决策日志 | 时间、决策事项、备选方案、选择理由、影响范围、审批人、后续动作 | 记录“为什么这样做”，支撑责任追溯 | 关键阈值调整是否有依据？ |
二、方法流程：从数据到决策的文档闭环
五类文档并非孤立存在，而是围绕模型生命周期形成闭环。推荐按以下顺序建立并持续维护：
- 数据接入阶段：先写数据文档，明确数据源、字段含义、标签定义和合规边界。没有数据文档，后续特征和模型都缺少根基。
- 特征开发阶段：每新增一个特征，同步更新特征文档，记录计算公式、依赖表和版本号。特征变更必须触发版本升级。
- 模型训练阶段：每次实验自动生成实验记录，绑定代码提交号、数据版本、参数配置和随机种子，避免“结果只存在于某台机器上”。
- 模型评估与上线阶段：基于实验记录撰写模型卡，说明模型适用场景、指标表现和已知限制。
- 评审与变更阶段：所有关键选择写入决策日志，包括阈值调整、特征取舍、模型替换和回滚操作。
在工程实现上，实验记录和决策日志应尽量自动化。例如，训练脚本可在结束时输出结构化记录：
{
"experiment_id": "exp-20240612-003",
"code_commit": "a1b2c3d",
"data_version": "ds_v3.2",
"feature_version": "feat_v1.8",
"params": {
"learning_rate": 0.05,
"max_depth": 6,
"seed": 42
},
"metrics": {
"auc": 0.842,
"ks": 0.391
},
"decision_log_ref": "dl-20240612-01"
}这样，审计人员可以通过 experiment_id 反查代码、数据、特征和决策记录，形成完整证据链。
三、案例场景：一次特征口径变更的审计追踪
假设某风控模型在线上运行三个月后，KS 指标突然下降。审计人员按文档体系逐层排查：
- 查数据文档：确认近期数据源未更换，但样本分布发生变化。
- 查特征文档：发现“近30天逾期次数”特征在两周前由
feat_v1.7升级到feat_v1.8，计算口径从“自然月”改为“滚动30天”。 - 查实验记录：发现模型训练仍使用旧特征版本，线上推理却已切换新版本，导致训练/推理不一致。
- 查决策日志：找到变更记录，但缺少影响评估和回滚方案。
- 查模型卡：模型卡未更新特征版本说明，业务方并不知情。
这个案例说明：文档体系的价值不在于单份文档写得多漂亮，而在于五类文档能否相互引用、相互校验。一旦某个环节缺失，问题定位成本会成倍增加。
四、常见误区与复盘
误区一：把文档当成“一次性交付物”。实际上，数据、特征、模型和决策都在持续变化，文档必须版本化、可追溯。
- 误区二：只记录成功实验。失败实验同样重要，它能避免团队重复踩坑，也能解释为何最终选择当前方案。
- 误区三：模型卡写成“宣传页”。模型卡应如实披露限制、风险和不适用的场景，而不是只展示高指标。
- 误区四：决策日志只写结果，不写理由。没有备选方案和选择依据，审计时无法判断决策是否合理。
- 误区五：文档与代码脱节。文档中的参数、特征版本、数据版本必须与代码和实验记录一致，否则文档反而会误导审计。
复盘建议：每个迭代周期结束时，做一次“文档一致性检查”——随机抽取一个实验记录，尝试仅凭文档复现结果；若无法复现，优先补齐缺失的数据、特征或决策记录。
综上，数据文档、特征文档、模型卡、实验记录和决策日志共同构成模型开发的可审计文档体系。它们分别对应“数据可信、特征可控、模型可知、实验可复现、决策可追溯”五个目标。只有把五类文档嵌入日常开发流程，而不是事后补写，才能真正支撑可重复性审计，并让模型在长期运行中保持可控、可信、可维护。