04 · 训练/推理一致性

   普通 bug：            这类 bug：
   报错 / 崩溃            静默
   一眼看见               要几周才被发现
   栈信息指向问题          没有任何线索
   修完就好               修完还要重训、还要评估影响范围

   训练：Spark SQL 里写的     AVG(price) OVER (last 7 days)
   线上：Java 服务里写的       sum/count 最近7天

   看起来一样，但：
   · 时区不同（UTC vs 本地）→ 「7 天」的边界差 8 小时
   · 空值处理不同（跳过 vs 当 0）
   · 「最近 7 天」是否含当天

   训练时：用整天的数据算「用户当天点击数」
   线上时：请求发生在下午 3 点，只能拿到当天前 15 小时的数据

   → 训练时这个特征的均值是 20，线上是 8  💀
   → 模型学到的「>15 算活跃」在线上几乎永远不成立

   训练：用「订单最终状态」算特征 —— 但那是下单 3 天后才确定的
   线上：预测时订单刚创建，状态是「待支付」

   → 训练时模型学会了依赖一个线上根本拿不到的信息

   训练时：city 字段做 LabelEncoder，fit 在训练集上
           北京→0, 上海→1, 广州→2

   线上时：来了个「深圳」（训练集里没有）
   → 编码器行为不确定：报错 / 给个默认值 / 映射到 0（=北京）💀

   ⭐ 最坏的情况是映射到 0：模型把所有新城市当成北京，毫无察觉

   训练：用训练集的 mean/std 做标准化
   线上：忘了保存，用了【当前批次】的 mean/std  💀

   → 每个 batch 的归一化基准都不一样
   → batch=1 时更是灾难（std=0）

   训练：pandas 里 NaN 被 fillna(0)
   线上：Java 里 null 被当成 -1 或抛异常

   训练时特征顺序：[age, income, city_id, ...]
   线上拼装时顺序：[income, age, city_id, ...]

   ⭐ 模型不会报错 —— 维度是对的，它照样算
   → 但每个权重都乘错了特征  💀💀

   ① 取 1000 条真实线上请求
   ② 记录线上服务实际算出的特征向量
   ③ 用离线训练管道，对同一批样本再算一遍
   ④ 逐字段比对

   通过标准：【完全一致】，不是「差不多」
   浮点特征允许 1e-6 的误差，其余必须逐位相同

import numpy as np, pandas as pd

def compare_features(online: pd.DataFrame, offline: pd.DataFrame, tol=1e-6):
    """online / offline 必须是同样的样本、同样的列"""
    assert list(online.columns) == list(offline.columns), \
        f"列顺序不一致！{set(online.columns) ^ set(offline.columns)}"   # ⭐ 先查第⑦条
    report = []
    for col in online.columns:
        a, b = online[col], offline[col]
        if np.issubdtype(a.dtype, np.number):
            diff = (a - b).abs()
            bad = (diff > tol).sum()
        else:
            bad = (a.astype(str) != b.astype(str)).sum()
        if bad:
            report.append((col, bad, len(a), bad / len(a)))
    return pd.DataFrame(report, columns=["特征", "不一致数", "总数", "占比"]) \
             .sort_values("占比", ascending=False)

   对每个重要特征，同时记录：
   · 训练集上的分布（均值/分位数/缺失率/类别占比）
   · 线上实时的分布

   ⭐ 任何一个特征的分布突然偏离训练集 → 告警

   每周取一批线上请求，用当时的特征重新跑一遍离线模型
   → 对比线上当时的预测值
   → 不一致说明两边又飘了

   传统做法：
   线上算特征 → 预测 → 只记录结果
   训练时     → 用离线管道【重新算一遍】特征   ← 不一致就在这产生

   日志即训练数据：
   线上算特征 → 预测 → 【把特征向量原样落日志】⭐
   训练时     → 直接读日志里的特征向量，不重算

   ⭐ 从根本上消除了「两套代码」——因为只有一套

   代码层
   [ ] 特征逻辑只有一份实现（或有自动化的一致性测试）
   [ ] 编码器 / 归一化参数【和模型一起保存和加载】⭐
   [ ] 特征顺序由 schema 定义，不靠人工拼装 ⭐⭐
   [ ] 未见过的类别有明确、可观测的处理方式（不是静默映射到 0）

   数据层
   [ ] 每个特征都确认过：预测时点真的能拿到吗（防穿越）
   [ ] 时间窗口的定义两边一致（含不含当天、时区）

   验证层
   [ ] 上线前做过 1000 条样本的逐字段比对 ⭐
   [ ] 影子流量跑过至少一个业务周期
   [ ] 线上有特征分布监控

   线上：特征服务 30ms 超时 → 返回默认值 → 模型照常预测
        这类请求占 2~5%（高峰期可能到 15%）

   训练：离线管道慢慢跑，【每个特征都拿得到】
        → 训练集里【一条降级样本都没有】  💀

   → 模型从来没见过「一半特征是默认值」的输入
   → 它在这些样本上的表现完全不可控

   训练：target encoding 用【整个训练集】算类别均值
        「北京」的历史转化率 = 3.2%（用了全部 180 天数据）

   线上：只能用【截止到此刻】的滚动统计
        「北京」的转化率 = 2.9%（用了最近 30 天）

   → 同一个类别，两边的编码值不一样
   → 而且【差多少取决于类别】：新类别差得最多  💀

import hashlib, json, numpy as np

# ⭐ 训练结束时，把 schema 和模型一起保存
def make_contract(columns, dtypes, encoders, scaler):
    spec = {
        "columns": list(columns),                       # ⭐ 顺序就是契约（挡第⑦条）
        "dtypes": {c: str(d) for c, d in zip(columns, dtypes)},
        "cat_vocab": {c: sorted(e.classes_.tolist()) for c, e in encoders.items()},
        "scaler_mean": scaler.mean_.tolist(),           # ⭐ 归一化参数必须一起存（挡第⑤条）
        "scaler_std": scaler.scale_.tolist(),
    }
    spec["fingerprint"] = hashlib.md5(
        json.dumps(spec, sort_keys=True).encode()).hexdigest()[:12]
    return spec


# ⭐ 线上每次构造特征向量时校验，不通过就【拒绝服务】而不是继续算
def enforce(vec_df, spec, strict=True):
    if list(vec_df.columns) != spec["columns"]:
        raise ValueError(f"特征顺序/集合不符：{set(vec_df.columns) ^ set(spec['columns'])}")
    bad = []
    for c, vocab in spec["cat_vocab"].items():
        unseen = set(vec_df[c].astype(str)) - set(vocab)
        if unseen:
            bad.append((c, list(unseen)[:5]))           # ⭐ 未见类别要显式暴露（挡第④条）
    if bad and strict:
        raise ValueError(f"出现未见过的类别：{bad}")
    return bad

   某风控模型，训练环境 sklearn 0.24 → 生产镜像升级到 1.1
   OneHotEncoder 的 categories_ 排序规则在版本间有差异
   → 同样的原始数据，one-hot 后的【列顺序变了】

   现象：
   · 服务不报错                     ← 维度一样
   · 预测分数分布几乎没变            ← 监控全绿 💀
   · 通过率从 88% 变成 87.6%         ← 在正常波动内

   两个月后：坏账率从 1.8% 涨到 4.1%   ← 标签延迟 60 天才暴露
   损失：两个月的坏账增量