17 · 版本、回溯与可复现

   ⭐ 一个「发布单元」应该包含五样东西，版本号统一：

   ① 模型文件         （权重 + 结构）
   ② 特征逻辑         （代码版本 / 特征定义）
   ③ 预处理产物       （编码器、归一化参数、分桶边界）⭐
   ④ 配置             （阈值、截断、降级开关）
   ⑤ 依赖环境         （库版本，尤其是 sklearn/xgboost 大版本）

   💀 只记①是最常见的错误 —— 回滚时会出第 3 章那个问题

   [ ] 请求 ID、时间戳、用户/实体 ID
   [ ] 模型版本号  ⭐
   [ ] 输入特征值（至少抽样落全量）⭐⭐
   [ ] 预测输出（分数 + 最终决策）
   [ ] 走了哪条链路（正常 / 降级 / 兜底）⭐
   [ ] SHAP 值（抽样，第 10 章）

   层次 1：能【重新加载】那个模型，对同样输入给出同样输出
           → 存模型文件 + 环境即可                    ✅ 最低要求

   层次 2：能【重新训练】出一个等价的模型
           → 还要存：训练数据快照、代码版本、随机种子、超参  ⭐

   层次 3：能【解释】当时为什么这么决策
           → 还要存：特征值、SHAP、当时的阈值配置

   完全复现比想象的难，因为随机性来源很多：

   · 随机种子（数据打乱、初始化、dropout）
   · 多线程/分布式的【浮点累加顺序】⭐ —— 这条最难消除
   · GPU 的非确定性算子
   · 数据源本身在变（同一个 SQL 明天跑结果就不一样）⭐⭐

   ⭐ 务实的目标不是「逐位相同」，而是：
      【效果等价】——重训出的模型在同一验证集上指标差异 < 容忍阈值

   模型：信贷审批，2024 年训练，joblib 存的 sklearn Pipeline
   2025 年 3 月：平台统一升级基础镜像（安全补丁）
                sklearn 1.2 → 1.4，numpy 也跟着升了大版本

   Pipeline 里的编码器，对「训练时没见过的类别」的处理方式变了
   （原配置没有显式指定，吃了默认值的变化）

   旧行为：抛异常 → 上游兜底走人工
   新行为：静默编码成【全 0 行】  💀

   → 而恰好那段时间上了两个新渠道
   → 新渠道的 channel 值是训练时没见过的
   → 这批人的渠道特征全部变成全 0 → 分数系统性偏低 → 被拒

   持续 3 个月，多拒约 1.4 万人
   事后回捞：其中约 63% 按老模型是该通过的优质客户

   ⭐ 最后是怎么被发现的？
     一张申诉工单里客户写了一句：
     「我从另一个渠道申请就通过了」

   发布时：把 200 条有代表性的样本 + 它们【当时的预测值】
          一起冻进发布单元

   每次启动 / 每次升级依赖 / 每次改代码：
   → 重跑这 200 条，逐条比对
   → 任何一条对不上，【拒绝启动】而不是告警  ⭐⭐

import json, numpy as np, pandas as pd

def freeze_golden(model, X_sample, out_path):
    """发布时跑一次：把样本和当时的预测冻起来"""
    p = model.predict_proba(X_sample)[:, 1]
    json.dump({"X": X_sample.to_dict("records"), "p": p.tolist()},
              open(out_path, "w", encoding="utf-8"), ensure_ascii=False)

def verify_golden(model, path, atol=1e-6):
    """启动时跑一次：对不上就【拒绝启动】"""
    g = json.load(open(path, encoding="utf-8"))
    p = model.predict_proba(pd.DataFrame(g["X"]))[:, 1]
    diff = np.abs(p - np.array(g["p"]))
    if (diff > atol).any():                       # ⭐ raise，不是 log.warning
        raise RuntimeError(
            f"黄金样本对不上：{(diff > atol).sum()}/{len(diff)} 条，最大偏差 {diff.max():.6f}")

   models/
     2026-08-02_v17/
       model.pkl                 模型
       preprocessor.pkl          编码器/归一化参数  ⭐
       config.json               阈值等配置
       feature_schema.json       特征名 + 顺序 + 类型  ⭐⭐
       requirements.txt          环境
       train_meta.json           数据范围、代码 commit、超参、随机种子
       eval_report.json          验证集指标、分人群指标
       MODEL_CARD.md             一页说明（第 19 章）

import json, hashlib, subprocess, joblib
from datetime import date

def save_release(model, preproc, config, schema, X_val, y_val, out_dir):
    """把一次发布的全部要素打包，版本号统一"""
    import os; os.makedirs(out_dir, exist_ok=True)
    joblib.dump(model, f"{out_dir}/model.pkl")
    joblib.dump(preproc, f"{out_dir}/preprocessor.pkl")      # ⭐ 别忘了它
    json.dump(config, open(f"{out_dir}/config.json", "w"), ensure_ascii=False)
    json.dump(schema, open(f"{out_dir}/feature_schema.json", "w"), ensure_ascii=False)
    meta = {
        "date": str(date.today()),
        "git_commit": subprocess.run(["git", "rev-parse", "HEAD"],
                                     capture_output=True, text=True).stdout.strip(),
        "n_train": len(X_val), "seed": 42,
        "data_hash": hashlib.md5(X_val.to_csv().encode()).hexdigest()[:12],  # ⭐
    }
    json.dump(meta, open(f"{out_dir}/train_meta.json", "w"), ensure_ascii=False)

import numpy as np
def assemble(raw: dict, schema: dict) -> np.ndarray:
    """⭐ 按 schema 组装特征，而不是按调用方传进来的顺序"""
    missing = [c for c in schema["columns"] if c not in raw]
    if missing:
        raise KeyError(f"缺特征：{missing}")
    extra = [c for c in raw if c not in schema["columns"]]
    if extra:
        raise KeyError(f"多了不认识的特征：{extra}")     # ⭐⭐ 这一行最容易被省
    row = []
    for c, t in zip(schema["columns"], schema["dtypes"]):
        v = raw[c]
        if t == "float" and not isinstance(v, (int, float)):
            raise TypeError(f"{c} 类型不对：{type(v).__name__}")
        row.append(v)
    return np.asarray(row, dtype=float).reshape(1, -1)

   一个 4000 QPS 的服务：

   轻量版（版本号 + 分数 + 决策 + 链路 + 耗时）≈ 每条 200 字节
     → 4000 × 200B × 86400 ≈ 每天 69 GB          ✅ 完全可以 100% 落

   全量特征（假设 300 个特征）≈ 每条 4 KB
     → 100% 落 ≈ 每天 1.4 TB                      💀 确实贵
     → 分层采样 3% 后 ≈ 每天 41 GB                ⭐ 完全可以接受