04 · 训练/推理一致性

⏱ 44 分钟 ｜ ⭐ 线上掉点最常见、也最难查的原因

🎯 一句话

训练时算特征用的是一套代码，线上算特征用的是另一套。 两套只要有一点点不一样，模型就会悄悄变差 —— 而且它不报错、不崩溃、延迟正常，只是答案不对。

💀 一、为什么这类 bug 最贵

🔑 业界给它起了个名字：training-serving skew（训练-服务偏斜）。 在很多团队的事故复盘里，它是线上效果不及预期的第一大原因 —— 超过模型选型、超过调参、超过数据量。

🕳️ 二、七种最常见的不一致（按出现频率排）

① 同一个特征，两套代码

⭐ 这是最根本的一类，解法在第五节。

② 时间窗口对不齐

③ 特征穿越（训练时用了未来）

🔗 这是ML基础 05 数据泄漏在生产环境的形态。 离线交叉验证完全发现不了它 —— 因为离线两边都有那个未来信息。

④ 类别编码不一致

⑤ 归一化参数不一致

⑥ 默认值 / 缺失值处理不同

⑦ 特征顺序错位

💀 第 ⑦ 条是所有里面最隐蔽的：形状对、类型对、没有异常， 但结果完全是垃圾。而且它的表现常常是「效果比随机好一点」， 容易被误判成「模型本身不行」。

🔬 三、怎么发现它（三个层次）

层次 1：上线前 —— 逐样本比对

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)

⭐ 这一步就是第 3 章影子流量最有价值的用法。 它能把这七类问题一次全查出来。

层次 2：上线后 —— 持续监控特征分布

🔗 具体怎么做在第 5 章和第 6 章。

层次 3：兜底 —— 定期回放

🛡️ 四、怎么根治：三种方案

🔑 方案 ③ 值得单独说

代价与限制（要诚实面对）：

💡 实践中常用混合方案：核心的实时特征走日志，稳定的统计特征走离线。 关键是明确哪些特征归哪条路，别混着来。

📋 五、可以照抄的检查清单

⭐ 如果只能做一件事：做「逐字段比对」那一条。 它花半天，能挡掉这一章里绝大部分问题。

🕳️ 六、还有两种，教科书里几乎不提

⑧ 线上有"降级样本"，训练数据里没有

⭐ 两个正确做法： 1. 在线上日志里打一个 is_degraded 标记，训练时把这类样本如实保留， 并分开评估这部分的指标。 2. 用一个明确的哨兵值（如 -999 或专门的 missing 类别）而不是 0， 让模型能学到"这是缺失"而不是"这个值是 0"。

⑨ 统计类特征的口径：全量 vs 滚动

⚠️ 这类不一致有个特别讨厌的性质：它对高频类别影响小、对长尾类别影响大， 所以整体指标看不出来，只有长尾人群在悄悄变差。 对策：训练时也用滚动窗口算（time-aware target encoding），两边窗口长度一致。

🧾 七、把它变成工程约束：特征 schema 契约

前面所有问题的共同解法是一句话：别让人去"记住"特征该长什么样，让代码去检查。

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

⭐ fingerprint 这一行值得单独说：把 schema 指纹写进预测日志。 事后排查时，你能立刻回答"这条预测是用哪个版本的特征定义算的" —— 而这个问题在没有指纹时，通常要查半天代码提交记录。 🔗 第 17 章会把它扩展成完整的版本体系。

⚠️ "不通过就拒绝服务"这个选择要想清楚：

💡 实践建议：第三种。每 100 条校验 1 条，开销可以忽略， 而任何系统性的 schema 问题在几秒内就会被抽到。

💀 一个真实的 schema 事故

⭐ 三个可以带走的点： 1. 依赖版本本身就是特征定义的一部分 —— 训练和推理的库版本必须锁死（requirements.lock / 同一个镜像）。 2. 这个事故里所有监控都是绿的 —— 因为分布真的没变，变的只是列的对应关系。 只有 schema 契约（列顺序校验）能挡住它。 3. 标签延迟 60 天，意味着它至少烧掉两个月（🔗 第 7 章）。

🔗 八、和站内其他章的关系

✅ 检查点

1. 为什么说这类 bug 最贵？它的业界名字是什么？
2. 七种不一致里，哪一种最隐蔽？为什么？
3. 特征穿越为什么离线交叉验证发现不了？
4. 类别编码不一致最坏的情况是什么？
5. 「逐样本比对」的通过标准是什么？
6. 「日志即训练数据」为什么能根治问题？它的三个代价是什么？
7. 如果只能做一件事，该做哪件？
8. 什么是「降级样本」？为什么说"只占 3% 影响不大"是错的？两个正确做法是什么？
9. 统计类特征的口径不一致有什么讨厌的性质？为什么整体指标看不出来？
10. schema 契约里的 fingerprint 有什么用？
11. 校验不通过时三种策略各适合什么场景？高 QPS 时推荐哪种？
12. sklearn 版本升级那个事故里，为什么所有监控都是绿的？什么能挡住它？

🛑 可以停在这里

⚡ 走神救援

⭐ 训练一套代码算特征、线上另一套，一点不一样模型就悄悄变差——⭐⭐ 不报错、不崩溃、延迟正常，只是答案不对。 很多团队复盘里，它是「线上不及预期」的头号原因。

九种不一致里，真正该记的是它们各自为什么发现不了：特征穿越用了预测时拿不到的字段——⚠️ 离线交叉验证完全发现不了，因为两边都有那个字段；新类别静默映射成 0——把所有没见过的取值当成同一个；💀 特征顺序错位最隐蔽——形状对、类型对、不报错，只是每个权重乘错了特征，表现得就像「模型不行」。

⭐⭐ 只做一件事的话就做这件：上线前取一千条真实请求，线上特征和离线重算逐字段比对，标准是完全一致、不是差不多。 这也正是影子流量最有价值的用法。

根治三条路里最彻底的是「日志即训练数据」：线上算完特征原样落日志，训练直接读、不重算——⭐ 因为只有一套代码。⚠️ 代价是日志量大、改特征要等攒数据、历史数据用不上。

两种教科书不提的：⭐ 线上有「降级样本」而训练数据里没有——特征服务超时返回默认值，占比不低，⚠️ 而高峰期占比更高，那正是收入最集中的时候；处方是如实打标记保留，并且用哨兵值而不是 0。另一种是统计口径不同，⭐ 它对高频类别影响小、长尾影响大，所以整体指标看不出来。

⭐ 工程解法是特征 schema 契约：列顺序、类型、类别词表、归一化参数，并把指纹写进预测日志，校验不过就拒绝服务。

💀 那次事故的形状：升了一个依赖的小版本，编码器的列顺序变了——不报错、分数分布几乎没变、监控全绿，而标签延迟让它两个月后才以坏账率翻倍的形式暴露。⭐ 教训两条：依赖版本本身就是特征定义的一部分，而且只有列顺序校验能挡住它。

下一节 👉 05-该监控什么.md