模型文档与版本梳理：收集模型设计文档、参数配置、版本变更记录、评审纪要

模型文档与版本梳理是机会评分模型复盘优化的第一道数据基石。缺乏完整的文档与版本记录，后续的偏差分析、参数回溯、绩效归因将无从下手。本章将结构化拆解如何系统性地收集、核验、归档模型设计文档、参数配置、版本变更记录与评审纪要。

适用场景

• 机会评分模型已完成一轮或以上迭代，需要进行效果复盘和优化方向判断。
• 团队对历史版本的关键参数、特征逻辑、风控规则存在记忆模糊或争议。
• 模型上线后出现异常波动，需要快速定位是版本变更还是数据漂移导致。
• 模型需要接受内部审计或外部监管机构检查，要求提供完整的版本溯源链。

前置条件

1. 已建立模型版本命名规范（如语义化版本 v1.2.3），或至少有过版本号标记习惯。
2. 团队有统一的文档存储库（如 Confluence、Git Wiki、共享网盘），且历史文档未被随意删除。
3. 模型参数配置文件（YAML/JSON/TOML 格式）至少保留最近两个全量快照。
4. 评审纪要（含会议记录、邮件审批截图、评审结论）已按时间归档。
5. 如果缺乏上述条件，需先启动“文档抢救”流程（参见异常处理）。

操作步骤

1. 建立版本清单：列出所有线上/测试过的模型版本号、发布时间、标签（如 prod/v2.1.0）。
2. 收集设计文档：针对每个版本找到对应的《模型设计说明书》《特征开发文档》《评分卡设计文档》《风控规则表》。
3. 导出参数配置：从部署环境（K8s ConfigMap、参数服务器、数据库配置表）导出完整参数集，包括模型权重、阈值、分箱映射、缺失值处理策略。
4. 整理版本变更记录：从 Git 提交日志、发布工单、变更审批单中提取每次变更的摘要、变更人、审批人、变更原因。
5. 收集评审纪要：汇总版本上线前的技术评审、交叉评审、业务评审会议纪要，提取关键结论、待办事项、风险点。
6. 交叉核验：将设计文档中的参数声明与环境实际的参数值逐一比对，记录偏差。
7. 统一编号存储：按 版本号_文档类型_日期 的格式重命名文件，存入版本化仓库（如 Git LFS）。

输入输出物

责任边界

• 模型算法负责人：提供最新的设计文档、参数配置文件，并对文档完整性负责。
• 模型发布工程师（MLOps）：提供版本清单、变更记录、部署参数快照。
• 技术评审组：提供评审纪要原件，并确认纪要中关键结论已被纳入文档。
• 数据治理/文档管理员：制定统一编号规则，监督存储规范执行。
• 质量保障（QA）：执行交叉核验，输出差异报告，推动解决不一致项。

记录材料

• 《版本-文档交叉索引表》（含文件哈希值用于防篡改）
• 《参数对比差异报告》
• 《评审纪要归档清单》
• 《版本树可视化图》（SVG / Graphviz 生成，可与本章内 SVG 复用风格）
• 《文档缺失与待补充列表》（作为异常处理的输入）

异常处理

1. 文档缺失：立即启动“文档抢救”流程——联系历史版本负责人回忆关键点，优先补齐参数配置和评审纪要，设计文档可后期补写并标注“回忆版”。
2. 参数配置与设计文档不一致：在差异报告中标记 待确认，召集相关方对齐。若无法对齐，以线上真实参数为准，并在设计文档中增加注释说明。
3. 版本号混乱或丢失：根据部署时间戳和工单内容重建版本序列，使用近似标记（如 reconstructed_v20230101）并附加风险说明。
4. 评审纪要无法获取：尝试从邮件、即时通讯记录、审批工单中提取会议结论，形成最小可行纪要。
5. 存储空间不足或权限受限：优先使用 Git LFS 或对象存储（S3/OSS），向基础设施团队申请临时扩容权限。

验收标准

1. 每个线上版本至少对应一份设计文档（允许补写但需标注）、一套参数配置文件、一条变更记录、一份评审纪要（或最小可行纪要）。
2. 设计文档与参数配置的交叉核验差异项数 ≤ 2，且所有差异已标注状态（待确认/已对齐/已修复）。
3. 统一编号存储包命名符合规范，无法通过通配符 v*_design_*.pdf 找到的文档数 ≤ 1。
4. 版本清单与生产环境实际运行实例的版本号完全匹配。
5. 输出《版本-文档交叉索引表》《参数对比差异报告》《文档缺失列表》三份交付物，签名确认。