52-数据集卡 Template v1.0 | 第6章 切分、版本与新鲜度（Splits/Versioning/Freshness）

第6章 切分、版本与新鲜度（Splits/Versioning/Freshness）

I. 目的与范围（Purpose & Scope）

• 规范数据集的切分（Splits）、**版本（SemVer）与新鲜度（Freshness/Validity）**管理与校验口径，确保训练/验证/测试的独立性与可比性、版本演进的可追溯、时间与校准新鲜度的一致。
• 涉及路径量（到达时/相位）之样本，正文显式路径 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0 并随附 check_dim_report.json。

II. 输入与依赖（Prerequisites & Inputs）

• 结构与契约：schema.json/contract.yaml 完整（见第4章），字段/单位/量纲与 TARR 对齐。
• 来源与血缘：provenance.yaml/lineage_graph.json 完备（见第3章），切分操作写入 lineage DAG。
• 计量与覆盖：与《误差预算卡》一致（cov_group/Σ、coverage ∈ {k, alpha, quantile}）；与《参数注册卡》一致的版本/新鲜度策略。
• 引用与版本：一律采用“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%，禁止外链/别名。

III. 切分策略（Splits Strategy）

1. 切分集合：train / val / test / holdout / slice_k；每个 split 在 split.yaml 中唯一命名并记录意图。
2. 防泄漏原则：
   • 时间泄漏：按时间窗切分（TS → {train < val < test}），严禁跨窗交叉。
   • 实体泄漏：按实体/场站/设备 group_by(entity) 切分，确保实体不跨 split。
   • 路径量一致：路径数组 gamma_ell/d_ell/n_eff 在任一 split 内长度与采样步长一致。
3. 分层与抽样：按 batch/device/region/quality.flags 分层；必要时保障类/难例比例一致。
4. 切片（slices）：对关键亚群体（极端工况/低信噪/特定区域）生成 slice_k 并显式记录筛选条件。
5. 再现性：在 split.yaml 记录随机种子 seed、算法与参数；生成 split_manifest.json 写明样本计数与校验和。

IV. 版本管理（Versioning — SemVer）

• MAJOR：Schema/字段语义/单位/量纲的破坏性变更或 split 语义改变（必须迁移指南与回滚点）。
• MINOR：向后兼容新增字段/新增 slice_k 或补充元数据（不破坏既有消费者）。
• PATCH：修补默认值/描述/小错误，不改语义。
• 标注规范：数据集根版本与每个 split 在 manifest.yaml/split_manifest.json 中分别标注 version；对外仅发布 v1.*。
• 依赖闭合：与管线/参数/误差卷的 see[]/references[]/version 同步；版本变更需更新 audit.jsonl。

V. 新鲜度策略（Freshness / Validity）

• 字段：freshness{ valid_from, valid_to, policy{ tau_calib_s_max, clock_state } }。
• 判定：|ts_start − calib.timestamp| ≤ tau_calib_s_max 且 clock_state="locked" 视为新鲜；否则进入隔离或标注 [Restricted]。
• 滚动更新：在 valid_to 前滚动生成下一版并无缝切换；旧版保留以便回溯与对比评测。
• 过期处理：过期样本仅可用于历史复算/诊断，不得纳入对外定量发布 split。

VI. 质量门映射（Gates Mapping）

• G1｜Schema 完整：split.yaml/split_manifest.json 字段齐备；索引与计数一致。
• G2｜引用合规：see[]/references[] 锚点直指率 ≥ 90%。
• G3｜路径规范：路径块 gamma/measure/delta_form 齐备，len(path)≥2、Δell 合规。
• G4｜量纲闭合：I70-dim_check 通过，要求 p_dim = 1.0。
• G5｜新鲜度：clock_state="locked"、τ_calib 合规；过期样本隔离。
• G6｜覆盖口径：split 内统计区间口径与发布一致（k/alpha/quantile）。
• G7｜协方差一致：分层/切片对 cov_group/Σ 的假设与误差卷一致；Σ 正定。
• G8｜唯一性：样本 record_id 在 split 内唯一；跨 split 不允许重复除非 slice_k 说明共享。
• 停止（S1–S5）：任一核心门失败即拒收/回滚，并可标注 [Restricted]。

VII. 机读配置（Machine-Readable Configs）
A. split.yaml

version: "1.0.0"

seed: 20250924

strategy:

group_by: ["entity_id"]

time_ordered: true

splits:

train: 0.70

val: 0.15

test: 0.15

constraints:

leakage:

time: { enforce: true }

entity: { enforce: true }

path:

require_alignment: true

delta_form: "general"

coverage:

mode: "k" # k|alpha|quantile

k: 2

B. split_manifest.json（节选）

{
  "dataset_version": "1.2.0",
  "splits": {
    "train": { "count": 120345, "checksum": "sha256:..." },
    "val": { "count": 25780, "checksum": "sha256:..." },
    "test": { "count": 25812, "checksum": "sha256:..." }
  },
  "slices": { "low_snr": { "count": 8142, "rule": "snr<5" } },
  "freshness": {
    "valid_from": "2025-09-01T00:00:00Z",
    "valid_to": "2026-03-01T00:00:00Z",
    "policy": { "tau_calib_s_max": 86400, "clock_state": "locked" }
  }
}

C. version_matrix.yaml（兼容矩阵）

dataset: "ds-core"

current: "1.2.0"

compatibility:

"1.2.x": { api: ">=1.2,<2.0", schema: ">=1.2,<2.0" }

"1.1.x": { api: ">=1.1,<1.3", schema: ">=1.1,<1.3" }

migration:

from: "1.1.x"

to: "1.2.x"

steps:

- change: "add slice 'low_snr'"

- change: "add field quality.score_Q"

rollback:

tag: "v1.1.3-lock"

VIII. 反例与修正（Anti-Patterns & Fixes）

• 反例：跨 split 共享同一实体导致泄漏 → 修正：group_by(entity) 切分并去重。
• 反例：T_arr = ∫ n_eff / c_ref d ell（缺括号） → 修正：T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
• 反例：未记录 seed/strategy 导致不可复现 → 修正：在 split.yaml 固化随机源与算法。
• 反例：过期样本混入训练集 → 修正：基于 freshness.policy 过滤或独立隔离并标注。
• 反例：覆盖口径在数据与发布侧不一致 → 修正：统一 coverage.mode 与参数。

IX. 交叉引用（Cross-References）

• 来源与血缘：见第3章；结构与 Schema：见第4章；质量门与完整性：见第7章；不确定度与协方差：见第8章。
• 与《管线卡》：入站契约（Ch.4）、质量门与监控（Ch.9）、产出与发布（Ch.12）。
• 与《误差预算卡》：阈值映射（Ch.9）、区间与覆盖（Ch.8）。

X. 执行勾选清单（Checklist）

• split.yaml/split_manifest.json 完整一致，记录 seed/strategy/count/checksum。
• 防泄漏策略有效（时间/实体），group_by 与窗口排序明示。
• 路径量显式 gamma/measure/delta_form；len(path) ≥ 2、Δell 合规；I70-dim_check 通过、p_dim = 1.0。
• 版本遵循 SemVer；兼容矩阵与迁移/回滚说明齐备；manifest 与 audit.jsonl 已更新。
• 新鲜度策略执行（clock_state="locked", τ_calib 合规）；过期样本隔离或 [Restricted]。
• /validate 通过 G1–G8；引用锚点直指率 ≥ 90%；发布包签名与校验和完备。