45-EFT.WP.Data.Pipeline v1.0 | 第11章 版本化、溯源与血缘

目录 ／ 文档-技术白皮书 ／ 45-EFT.WP.Data.Pipeline v1.0

第11章 版本化、溯源与血缘

I. 章节目的与范围

II. 术语与依赖

• 术语：semver（语义化版本）、artifact（工件）、digest/sha256、lineage.graph、provenance、repro（可复现）、replay（回放）、dual-write（双写）、compat_mode（兼容模式）。
• 依赖：契约与导出（《Core.DataSpec v1.0》）；单位/量纲校核（《Core.Metrology v1.0》）；切分/覆盖与质量（《DatasetCards v1.0》）；评测/特征与 I/O 假设（《ModelCards v1.0》）。
• 数学与符号：内联符号用反引号（如 QPS、T_inf、ρ）；含除号/积分/复合算符必须加括号并（如涉路径量）声明 gamma(ell) 与 d ell；公式/符号/定义禁用中文。

III. 字段与结构（规范性）

versioning:

scheme: "semver" # vMAJOR.MINOR.PATCH

stability_line: "v1.*"

compat_mode: "forward|backward|both|break"

notice:

type: "release|correction|withdrawal"

summary: "<text>"

date: "<YYYY-MM-DD>"

provenance:

sources: ["<uri-or-ref>", "..."] # 数据来源/上游引用（仅引用）

transforms: ["<stage-name>@vX.Y", "..."]

environment:

containers: ["<image@digest>", "..."]

deps_lock: "locks/deps.lock.yaml"

seeds: {global: 1701}

lineage:

graph:

nodes:

- {id:"src.s3.pull", kind:"stage", version:"v1.0"}

- {id:"schema.check", kind:"stage", version:"v1.2"}

- {id:"feat.map", kind:"stage", version:"v1.1"}

- {id:"train_pkg", kind:"artifact", digest:"sha256:..."}

edges:

- {from:"src.s3.pull", to:"schema.check"}

- {from:"schema.check", to:"feat.map"}

- {from:"feat.map", to:"train_pkg"}

replay:

enabled: true

inputs_lock: "locks/inputs.manifest.json" # 源清单+偏移/水位

policy: "strict|lenient"

artifacts:

- {path:"pipeline.yaml", sha256:"<hex>"}

- {path:"locks/inputs.manifest.json", sha256:"<hex>"}

- {path:"locks/deps.lock.yaml", sha256:"<hex>"}

- {path:"outputs/train_pkg.tgz", sha256:"<hex>"}

IV. 版本化策略与稳定线

• 格式：vMAJOR.MINOR.PATCH；MAJOR 用于破坏性变更，MINOR 用于向后兼容新增，PATCH 用于修复与文案更正。
• 稳定线：对外引用推荐 v1.*；涉及评测/发布材料应固定到次版本。
• 兼容模式：forward|backward|both|break 与 Schema/契约 compat_mode 对齐；break 需影子对比与通告。
• 通告：在 versioning.notice 与 export_manifest.references[] 登记公告锚点。

V. 溯源信息与可复现

• 来源：provenance.sources[] 记录源端标识（仅引用），禁止复制数据事实；水位/偏移与时间范围锁定在 inputs.manifest.json。
• 环境：容器镜像用不可变 digest；依赖锁定文件 deps.lock.yaml 列出版本与哈希。
• 随机性：固定 seeds；对非确定性算子声明库版本与确定性后端。

VI. 血缘图与回放

• 血缘图：lineage.graph 含节点（阶段/工件）与有向边，节点携带版本/哈希；图应无悬空节点。
• 回放：replay.enabled=true 时，使用 inputs_lock 约束输入集合与顺序；policy:"strict" 要求字节级一致，"lenient" 允许非决定性轻微偏差并给出容忍阈。
• 双写窗口：破坏性迁移采用 dual-write，对比差异并在阈内切换。

VII. 工件哈希与完整性

• 强制哈希：所有关键工件（配置/锁定/包/报告）均需 sha256；完整性失败为阻断。
• 清单对表：artifacts[] 与 export_manifest.artifacts[] 必须一致，含路径与哈希；可选记录 SIZE/LASTMOD。

VIII. 计量与单位（SI）

1. 性能与资源：QPS（1/s）、T_inf（ms {p50,p95,p99}）、ρ（—）、net_mbps、size_bytes；
2. 强制：metrology:{units:"SI", check_dim:true}；合成/换算前先做单位归一。
3. 路径量：如血缘涉及到达时/改正链路，登记 delta_form、path="gamma(ell)"、measure="d ell"；采用：
   • T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ) 或
   • T_arr = ( ∫ ( n_eff / c_ref ) d ell )，并通过 check_dim。

IX. 机器可读片段（可直接嵌入）

versioning:

scheme: "semver"

stability_line: "v1.*"

compat_mode: "both"

notice: {type:"release", summary:"initial stable", date:"2025-09-21"}

provenance:

sources: ["s3://eift-data/raw/2025/09/", "contracts/raw_rows@v1.2"]

transforms: ["schema.check@v1.2", "feat.map@v1.1"]

environment:

containers: ["ghcr.io/eift/pipeline@sha256:abcdef..."]

deps_lock: "locks/deps.lock.yaml"

seeds: {global:1701}

lineage:

graph:

nodes:

- {id:"src.s3.pull", kind:"stage", version:"v1.0"}

- {id:"schema.check", kind:"stage", version:"v1.2"}

- {id:"feat.map", kind:"stage", version:"v1.1"}

- {id:"train_pkg", kind:"artifact", digest:"sha256:1234..."}

edges:

- {from:"src.s3.pull", to:"schema.check"}

- {from:"schema.check", to:"feat.map"}

- {from:"feat.map", to:"train_pkg"}

replay: {enabled:true, inputs_lock:"locks/inputs.manifest.json", policy:"strict"}

artifacts:

- {path:"pipeline.yaml", sha256:"..."}

- {path:"locks/inputs.manifest.json", sha256:"..."}

- {path:"locks/deps.lock.yaml", sha256:"..."}

- {path:"outputs/train_pkg.tgz", sha256:"..."}

X. Lint 规则（节选，规范性）

lint_rules:

- id: VER.SEMVER

when: "$.versioning.scheme"

assert: "value == 'semver' and matches($.pipeline.version, '^v\\d+\\.\\d+(\\.\\d+)?$')"

level: error

- id: VER.COMPAT_ALLOWED

when: "$.versioning.compat_mode"

assert: "value in ['forward','backward','both','break']"

level: error

- id: LIN.GRAPH_CONNECTED

when: "$.lineage.graph"

assert: "graph_is_connected(value) and no_dangling_nodes(value)"

level: error

- id: LIN.REPLAY_INPUTS_LOCK

when: "$.lineage.replay.enabled"

assert: "value == false or has_key($.lineage.replay.inputs_lock)"

level: error

- id: ART.SHA256_REQUIRED

when: "$.artifacts[*]"

assert: "has_key('sha256') and len(value.sha256) > 0"

level: error

- id: METROLOGY.SI_AND_CHECKDIM

when: "$.metrology"

assert: "units == 'SI' and check_dim == true"

level: error

XI. 导出清单与审计轨

export_manifest:

version: "v1.0"

artifacts:

- {path:"pipeline.yaml", sha256:"..."}

- {path:"locks/inputs.manifest.json", sha256:"..."}

- {path:"locks/deps.lock.yaml", sha256:"..."}

- {path:"lineage/graph.json", sha256:"..."}

- {path:"reports/replay.result.json", sha256:"..."}

references:

- "EFT.WP.Core.DataSpec v1.0:EXPORT"

- "EFT.WP.Core.Metrology v1.0:check_dim"

- "EFT.WP.Data.DatasetCards v1.0:Ch.11"

- "EFT.WP.Data.ModelCards v1.0:Ch.11"

XII. 本章合规自检

• 版本号符合 semver，stability_line 与对外引用一致；compat_mode 明确，break 变更已影子对比并公告。
• 溯源信息完整：来源、水位/偏移、环境与依赖锁定、随机种子记录到位，不复制数据事实。
• 血缘图连通且无悬空节点；回放启用时提供 inputs_lock 与严格/宽松策略说明。
• 所有关键工件均具 sha256 并在 export_manifest 登记；性能/资源计量采用 SI 且 check_dim=true。
• 涉路径量 T_arr 已登记 delta_form/path/measure 并通过校核；与数据/模型卡的冻结切分与评测协议对表。