17 · 数据版本与血缘

⏱ 52 分钟 ｜ ⭐ 三个月后，你能重现当时那份训练数据吗

🎯 一句话

只存代码不存数据，等于没有可复现。 模型是 代码 × 数据 × 参数 × 环境 的函数 —— 你把其中三项都版本化了，剩下那一项是一张每天被覆盖的上游表。

🔍 一、先花五分钟做个自测

随便挑一个三个月前上线的模型，回答这六个问题。

为什么"我们代码都在 git 里"救不了你：

⭐ 本章和《模型上线之后》第 17 章的分工，就在这张图上： 那边负责左边三格（代码、参数、环境、模型权重），这边只负责最右边那一格。 两边都做齐了才叫可复现；而现实中挂掉的，九成是最右边这一格。

📦 二、四种版本化方案：成本、粒度、适用规模

假设一张 200 GB 的宽表，每天产出一版，日变化率约 5%（这是很典型的数值）。

怎么选：先算你的日变化率。

⭐ 一条被反复验证的经验： 绝大多数团队不需要上 DVC / lakeFS / Delta Lake。 他们需要的只是两条纪律 —— ① 分区永不覆盖；② 每次训练把用到的分区名和指纹写进 manifest。 这两条不需要任何新工具，但它们能解决 80% 的复现问题。

🔑 三、指纹：用一行字符串锁住一份数据

版本化只解决"数据还在"，指纹解决"它还是不是原来那份"。

import hashlib
import json
import numpy as np
import pandas as pd

def logical_fingerprint(df: pd.DataFrame, float_dp: int = 6) -> dict:
    """逻辑指纹：对文件切分方式、行顺序、分片数都不敏感。
    回答的是"这两份数据是不是同一份"，而不是"这两个文件是不是同一个文件"。"""
    cols = sorted(df.columns)                                  # ⭐ 列顺序无关
    parts = []
    for c in cols:
        s = df[c]
        if pd.api.types.is_float_dtype(s):
            s = s.round(float_dp)                              # ⭐ 浮点必须先定精度，否则永远对不上
        h = pd.util.hash_pandas_object(s, index=False).to_numpy(dtype=np.uint64)
        parts.append((c, int(np.bitwise_xor.reduce(h))))       # ⭐ XOR 聚合 → 行顺序无关
    payload = {"n_rows": int(len(df)), "cols": parts}
    digest = hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
    return {
        "fingerprint": digest[:16],          # ⭐ 16 位十六进制足够，写进 manifest 一眼能比
        "n_rows": len(df),
        "n_cols": len(cols),
        "per_column": dict(parts),           # ⭐ 出问题时，这一列能直接告诉你是【哪一列】变了
    }

# ⭐ 关键用法：不要只存总指纹，要存 per_column ——
#     总指纹只能告诉你"变了"，per_column 能告诉你"哪一列变了"，
#     这是排查时间从两天缩到十分钟的差别

四个让指纹永远对不上的坑：

🧾 四、血缘要记什么

血缘不是一张关系图，是一份「能让人照着重跑一遍」的记录。

一份 run manifest 长这样（和产出物放在同一个目录，文件名 _MANIFEST.json）：

{
  "run_id": "train_credit_v37_20240131_0412",
  "produced_at_utc": "2024-01-31T04:12:38Z",
  "data_cutoff_utc": "2024-01-31T00:00:00Z",
  "code": {"repo": "risk-models", "commit": "9f2c1ab", "entry": "jobs/build_train.py"},
  "params": {"window_days": 180, "neg_sample_rate": 0.15, "seed": 20240131},
  "filters": ["status != 'test'", "apply_time < data_cutoff", "dedup by (uid, apply_date)"],
  "inputs": [
    {"table": "dw.user_profile_wide", "partition": "dt=2024-01-31",
     "fingerprint": "3a91f0c7d2be4155", "n_rows": 8421339},
    {"table": "dw.repay_label", "partition": "dt=2024-01-31",
     "fingerprint": "77c0be14aa39d802", "n_rows": 3110284}
  ],
  "output": {"path": "s3://ds/train/credit_v37/", "fingerprint": "b5e2149c8f0a7731",
             "n_rows": 3110284, "n_cols": 214}
}

⭐ 把 manifest 写在产出物【旁边】，不要写在另一个系统里。 三个月后你能找到那份 parquet，就一定能找到 _MANIFEST.json； 但你不一定还能登进当年那个血缘平台 —— 它可能换了域名、换了负责人、或者根本已经下线了。 💀 血缘系统的存活率，比数据文件低得多。

🛑 读到这里可以停 —— 前半章讲完了（约 19 分钟）。 后半章还有：只存代码不存数据的两种死法 · 一次真实的事故复盘 · 和《模型上线之后 17》的分工 · 按团队规模分级实施 回来的时候不用重读，直接从下一节接着看就行。

☠️ 五、只存代码不存数据的两种死法

💀 回填（backfill）是数据侧最危险的一个动作，因为它长得像修 bug： "我们发现 income_verified 算错了，已经修好并回填了历史数据。" 听起来完全正确 —— 但它同时把所有历史模型的训练数据静默改写了。 ⭐ 纪律：任何 backfill 都必须写新分区（或新版本号），永不原地改写。 存储贵一点，比不可复现便宜一万倍。

💀 六、一次真实的事故复盘

发生了什么

为什么没被发现

代价

该补什么

⭐ 这个案例最值钱的一句话： AUC 差 0.0023 是"没差别"，同一个人的分数差 0.13 是"完全不同的决策"。 可复现性不能用聚合指标验证，必须用个体样本逐条比对 —— 因为你要向监管解释的，从来不是平均值，是某一个人。

🤝 七、和《模型上线之后 17》的分工

两章讲的是同一件事的两半，边界很清晰：

⚠️ 这一行"两边都以为对方管了"是真实事故的高发区： 模型侧觉得"数据是数仓的事"，数据侧觉得"训练集是算法自己拉的"。 ⭐ 解法很简单：把「上游分区指纹」列进模型卡的必填项 （落地处是本章第四节那份 run manifest 的 inputs[].fingerprint 字段， 以及《模型上线之后》第 19 章的模型卡模板）—— 谁发版谁填，填不出来就不许发版。

🪜 八、按团队规模分级实施

别一上来就上工具，按这个顺序做。

⭐ L1 是绝大多数团队应该停下来的地方。 一个 _MANIFEST.json 文件、半天工程量， 能解决你 80% 的"三个月后重现不出来"问题。 剩下 20% 才需要工具，而那 20% 的团队自己知道自己是谁。

🔗 这一章连到哪里

✅ 检查点

1. 五分钟自测的六个问题是什么？大多数团队卡在哪一条？
2. 为什么说"代码都在 git 里"救不了可复现？这四项是什么关系？
3. 四种版本化方案在「200 GB 表、日变化率 5%」下一年各要多少存储？各自的主要痛点是什么？怎么用日变化率选方案、超过 20% 说明什么？
4. 逻辑指纹为什么要按列名排序、要 round 浮点、要用 XOR 聚合？为什么一定要存 per_column 而不只存总指纹？
5. 血缘里最容易漏的三项是什么？为什么 manifest 要放在产出物旁边而不是血缘平台里？
6. 只存代码不存数据的两种死法是什么？为什么说 backfill "长得像修 bug"？纪律是什么？
7. 信贷那个事故里，重跑的 AUC 和原始差多少？那位申请人的分数差多少？为什么说前者"没差别"而后者"完全不同"？
8. 那个事故的四条"没被发现"的原因里，哪一条最容易被忽悠过去？代价一共多少、如果当初就存快照要花多少？
9. 本章和《模型上线之后 17》怎么分工？为什么这个边界特别容易出事、怎么解决？
10. 分级实施表里，哪一级性价比最高、要多少工程量、能解决多少问题？

🛑 可以停在这里

⚡ 走神救援

⭐ 只存代码不存数据，等于没有可复现。 模型是代码、参数、环境、数据四样东西的函数——前三项都有版本号，而数据那一格是一张每天覆盖写的表。💀⭐ 这四项是短板效应不是加权平均：前三项满分、有一项不可回溯，总分还是零。

⭐ 绝大多数团队不需要上任何工具，只需要两条纪律：分区永不覆盖，以及每次训练把用到的分区名和指纹写进清单。⭐ 选型前先算日变化率——变化率高到一定程度说明口径不稳定，那不是存储问题，先去问为什么。

⭐ 一定要存每列的指纹，而不只是总指纹：总指纹只说「变了」，每列指纹说「哪一列变了」——这是排查从两天缩到十分钟的差别。⭐ 清单要写在产出物旁边，💀 因为血缘系统的存活率比数据文件低得多。

☠️ 两种死法：上游被覆盖或过期；⭐ 以及更隐蔽的——上游还在但语义变了：分区名没变、行数没变、结构没变，你重跑结果不同却不知道为什么。⭐ 没有指纹的话，这个问题无法被发现，也无法被证明。

💀⭐ 回填是数据侧最危险的动作，因为它长得像修 bug：「我们发现算错了，已修好并回填历史」听起来完全正确——⚠️ 但它同时静默改写了所有历史模型的训练数据。 ⭐ 纪律：任何回填必须写新分区，永不原地改写。

💀 那个信贷事故里最贵的一句：⭐⭐ 「整体指标只差一点点」是「没差别」，而「同一个人的分数差很多」是「完全不同的决策」。 ⭐ 可复现性不能用聚合指标验证——必须抽上千条个体样本逐条比对，因为你要向监管解释的从来不是平均值，是某一个人。

⚠️ 两条容易漏的：数据保留期短于合规追溯期；⭐ 「有血缘系统」不等于「可复现」——只记表名、不记分区指纹和口径版本，等于没记。

下一节 👉 18-特征存储.md