34-EFT.WP.Astro.Acceleration v1.0 | 附录 C. 数据/模型/管线卡

目录 ／ 文档-技术白皮书（V5.05） ／ 34-EFT.WP.Astro.Acceleration v1.0

附录 C. 数据/模型/管线卡

I. 摘要与范围
本附录定义三类卡片 DatasetCard、ModelCard、PipelineCard 的统一模式（Schema）、必填字段、单位与量纲（Unit/Dim）携带规则、引用锚点（see:）、哈希与版本化、校验与发布流程。任一涉及到达时（ToA）的字段必须并行记录两种口径并显式声明路径 gamma(ell) 与测度 d ell：T_arr^A = ( 1 / c_ref ) * ( ∫ n_eff d ell )、T_arr^B = ( ∫ ( n_eff / c_ref ) d ell )，并登记 delta_form。

II. 依赖与引用
统一符号与量纲：附录 A、第二章 P12-；数据与管线发布：第十四章 I75-/M75-；仿真与基准：第十二章 M70-；推断与证伪：第十三章 M72-；API 绑定：第十五章 I80-；通道/谱/传输：第三–八章（S20-/S30-/S40-/S50-/S52-）；GRB/FRB：第十–十一章（M62-/M64-）。

III. 统一模式与命名（I75- 基线）

• 命名与标识：{dataset_id|model_id|pipeline_id} 唯一；语义化版本 MAJOR.MINOR.PATCH。
• 最小字段：{meta, spec/graph, quality/acceptance, hash, see}；所有数值列强制 unit 与 dim。
• 哈希与可复现：{code_hash, data_hash, rng_state}；导出 repro/（环境锁定与脚本）。
• ToA 强制：并列 T_arr^A / T_arr^B / delta_form，并在 integrals 中声明 {path:"gamma(ell)", measure:"d ell"}。

IV. DatasetCard（数据卡）模式与示例

表 C-1 DatasetCard 字段一览（必填为★）

JSON 示例（节选）

{

"meta": {

"dataset_id": "CR_ARRAY_V3",

"version": "3.2.0",

"instrument": "CTA",

"band": "0.1–10 TeV",

"time_span": "2021-2024"

},

"spec": {

"columns": [

{"name":"E","unit":"eV","dim":"E","description":"energy","see":"S50-*"},

{"name":"Phi","unit":"m^-2·s^-1·sr^-1·eV^-1","dim":"L^-2 T^-1 Ω^-1 E^-1","description":"diff. flux","see":"S50-9"}

],

"sampling":"live_time_weighted",

"calibration":"v2_gain_map"

},

"quality":{"systematics":"5% abs","covariance":"provided","masks":["dominant_band"]},

"integrals":{"path":"gamma(ell)","measure":"d ell"},

"toa":{"T_arr^A":"1.234e-3 s","T_arr^B":"1.236e-3 s","delta_form":"A"},

"hash":{"data_hash":"sha256:...","card_hash":"sha256:..."},

"see":["S50-*","S52-*"]

}

V. ModelCard（模型卡）模式与示例

表 C-2 ModelCard 字段一览（必填为★）

JSON 示例（节选）

{

"meta":{"model_id":"S50_spectrum_v1","version":"1.1.0","family":"S50"},

"params":[

{"name":"alpha_inj","transform":"identity","prior":"N(2.2,0.3)","bounds":[1.0,3.5],"unit":"1","dim":"1","see":"S50-*"},

{"name":"E_max","transform":"log","prior":"LogU[1e9,1e21]","bounds":[1e6,1e22],"unit":"eV","dim":"E","see":"S50-7"}

],

"channels":{"A_rec":1,"A_shear":1,"A_dsa":0,"A_turb":0},

"diagnostics":{"logZ":7.11,"WAIC":512.3,"LOO":510.8},

"hash":{"code_hash":"sha256:...","card_hash":"sha256:..."},

"see":["S30-*","S40-*","S50-*","S52-*"]

}

VI. PipelineCard（管线卡）模式与示例

表 C-3 PipelineCard 字段一览（必填为★）

JSON 示例（节选）

{

"meta":{"pipeline_id":"ASTROACC_FIT_V2","version":"2.0.0"},

"graph":{

"nodes":[

{"id":"n1","type":"ingest","inputs":["cards/dataset_cr.json"],"outputs":["staged/"],"env":"docker://acc:1.3","seed":1729},

{"id":"n2","type":"fit","inputs":["staged/","cards/model_s50.json"],"outputs":["products/posterior.zarr"],"env":"docker://acc:1.3","seed":1729},

{"id":"n3","type":"validate","inputs":["products/posterior.zarr"],"outputs":["metrics.json"],"env":"docker://acc:1.3"}

],

"edges":[["n1","n2"],["n2","n3"]]

},

"acceptance":{"SpecMAE":"<=0.03","IndexErr":"<=0.05","ToAΔ":"<=1e-4 s"},

"exports":{"products/":true,"metrics.json":true,"masks/":true,"delta_form.log":true,"repro/":true},

"hash":{"code_hash":"sha256:...","data_hash":"sha256:..."},

"see":["M70-*","M72-*","I75-*"]

}

VII. 校验与一致性（M75-1）

• Schema 校验：三类卡片均须通过 JSON Schema 与必填字段校核。
• 单位与量纲：所有数值列通过 Unit/Dim 审计；Phi(E) 强制 m^-2·s^-1·sr^-1·eV^-1；时间以 s。
• ToA 合规：若存在 ToA 字段，必须并列 T_arr^A/T_arr^B/delta_form，且 integrals 显式 gamma(ell)/d ell。
• 哈希一致性：data_hash 与载荷一致；code_hash 与运行环境一致；失败即拒绝发布。

VIII. 发布与审计（M75-2/M75-4/M75-5）

• 环境锁定：导出 repro/（容器镜像、依赖版本、随机种子）。
• 审计清单：汇总 {code_hash, data_hash, rng_state, SimCfg, cards, masks, delta_form}。
• 版本与兼容：MAJOR 升级需附迁移脚本；MINOR/PATCH 维持向后兼容字段。
• 注册表键：sim_id / pipeline_id / dataset_id / model_id / version / code_hash / data_hash。

IX. 质量门与验收（对接第十二章）

• 指标集合：SpecMAE、IndexErr、LagRMS、PA_RMS、ToAΔ。
• 通过条件：各指标满足门限即 pass，否则 fail 并输出差分报告。
• 占优掩码：随 masks/ 导出能区/时段掩码（eta_dom(E[,t])）以约束下游求解。

X. 模板清单

表 C-4 DatasetCard 列模板（摘录）

表 C-5 ModelCard 参数模板（摘录）

表 C-6 Pipeline 节点模板（摘录）

XI. 接口对接（I80-*）

• export_dataset_card / export_cards：从产物导出标准卡片；
• run_pipeline：读取 PipelineCard 执行 DAG，生成 products/ 与 metrics.json；
• metrics_validate：按门限评估通过/失败并输出 diff；
• register_benchmark：注册基准产物与卡片集合，供回归使用。

XII. 小结
本附录以 I75-/M75- 为基线，给出 DatasetCard/ModelCard/PipelineCard 的统一模式、字段与示例，明确 Unit/Dim、ToA 双口径、哈希与审计、验收门限与发布流程，确保数据—模型—管线在全链路内可验证、可复现、可审计。