54-复现实验清单 Template v1.0 | 第12章 附录（表单/清单/模板）

目录 ／ 文档-技术白皮书 ／ 54-复现实验清单 Template v1.0

第12章 附录（表单/清单/模板）

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

• 汇总本卷执行所需的表单（Forms）、清单（Manifests）与模板（Templates），覆盖环境锁定、数据快照与血缘、权重与参数、新鲜度策略、脚本与命令、评测与对齐、UQ 与误差预算、监控与回退、发布与签名，保证一键复现、等价比对、可审计发布。
• 凡涉及路径量（到达时/相位），正文显式 gamma(ell) 与测度 d ell；数据侧记录 delta_form ∈ {general, factored}；所有表达括号化；发布要求 p_dim = 1.0 并随附 check_dim_report.json。

II. 推荐目录结构（PTN_EXPORT/ Layout）

PTN_EXPORT/

model/ # 模型清单与配置

model_manifest.yaml

compat_matrix.yaml

control_spec.yaml

train_config.yaml

hpo_space.yaml

inference/ # 部署接口与绑定

inference_openapi.yaml

inference.proto

binding_spec.md

uq/ # UQ 与误差预算

model_uq.yaml

uq_summary.json

budget_breakdown.csv

eval/ # 评测与对齐

bench_plan.yaml

compare_spec.yaml

scorecard.json

eval_report.md

monitoring/ # 监控与回退

monitoring_rules.yaml

rollback_fsm.yaml

alerts.jsonl

data/ # 数据快照（可选或外部引用）

data_refs.yaml

split_manifest.json

lineage_graph.json

env/ # 环境锁定（可选）

env_lock.json

container_spec.yaml

seed_policy.yaml

preflight_report.json

scripts/ # 运行入口

RUNBOOK.md

Makefile

reproduce.sh

reports/ # 校核与审计

check_dim_report.json

validate_report.json

audit.jsonl

figs/ # 图表（双份导出）

metric_curves.pdf

metric_curves.png

interval_bands.svg

path_profile.pdf

report_manifest.yaml

checksums.txt

SIGNATURE.asc

III. 关键模板（Copy-Ready Templates）

A. 复现实验索引 repro_manifest.yaml

version: "1.0.0"

entrypoints:

preflight: "reproduce.sh preflight"

data_verify: "reproduce.sh data_verify"

train: "reproduce.sh train"

infer: "reproduce.sh infer"

eval: "reproduce.sh eval"

compare: "reproduce.sh compare"

pack: "reproduce.sh pack"

artifacts:

env: ["env/env_lock.json","env/container_spec.yaml","env/seed_policy.yaml","env/preflight_report.json"]

data: ["data/data_refs.yaml","data/split_manifest.json","data/lineage_graph.json"]

model: ["model/model_manifest.yaml","model/compat_matrix.yaml","model/control_spec.yaml","model/train_config.yaml"]

api: ["inference/inference_openapi.yaml","inference/inference.proto","inference/binding_spec.md"]

uq: ["uq/model_uq.yaml","uq/uq_summary.json","uq/budget_breakdown.csv"]

eval: ["eval/bench_plan.yaml","eval/compare_spec.yaml","eval/scorecard.json","eval/eval_report.md"]

monitor: ["monitoring/monitoring_rules.yaml","monitoring/rollback_fsm.yaml","monitoring/alerts.jsonl"]

reports: ["reports/check_dim_report.json","reports/validate_report.json","reports/audit.jsonl"]

figs: ["figs/metric_curves.pdf","figs/interval_bands.svg","figs/path_profile.pdf"]

checksums: "checksums.txt"

sign: "SIGNATURE.asc"

see:

- "Dataset Card v1.0:Ch.4"

- "Model Card v1.0:Ch.10"

- "Error Budget Card v1.0:Ch.8"

B. 环境锁定 env_lock.json（节选）

{

"hardware": {

"cpu": { "model": "Intel Xeon 8368", "sockets": 2, "cores_per_socket": 38, "isa": "AVX512" },

"gpu": [{ "model": "NVIDIA A100 80GB", "count": 8, "sm": 108, "vram_gb": 80 }],

"clock": { "state": "locked", "source": "GNSS_PPS", "allan_1s": 1.0e-11 }

},

"software": {

"os": { "name": "Ubuntu", "version": "22.04", "kernel": "5.15.0-106" },

"drivers": { "nvidia": "535.146.02", "cuda": "12.2", "cudnn": "9.1.0" },

"frameworks": { "torch": "2.2.2+cu122", "triton": "2.2.0" }

}

}

C. 容器规范 container_spec.yaml

version: "1.0.0"

image: { name: "registry.example.com/ml/ptn-repro", tag: "1.2.0", digest: "sha256:abcdef..." }

runtime: { driver: "nvidia", gpus: "all", shm_size: "64g" }

mounts: [ { src: "/data", dst: "/mnt/data", mode: "ro" } ]

env: [ { name: "OMP_NUM_THREADS", value: "8" } ]

entrypoint: ["bash","-lc"]

cmd: ["./reproduce.sh all"]

D. 数据引用 data_refs.yaml（节选）

version: "1.0.0"

datasets:

- id: "ds-core"

manifest: "DS_EXPORT/manifests/report_manifest.yaml"

schema: "DS_EXPORT/schemas/dataset/schema.json"

splits: "DS_EXPORT/splits/split_manifest.json"

E. 权重清单 weights_manifest.yaml（节选）

version: "1.0.0"

weights:

- file: "weights/best.ckpt"

semver: "1.2.0"

git: "3f1c9ab"

checksum: "sha256:..."

signature: "SIGNATURE.asc"

lock_tag: "v1.2.0-lock"

F. 脚本入口 RUNBOOK.md（提纲）

# RUNBOOK

- Preflight → Data Verify → Train → Infer → Align → Eval & UQ → Compare → Pack & Sign

- Idempotency key per stage; sha256 equivalence required

G. 比对规格 compare_spec.yaml（节选）

version: "1.0.0"

coverage: { mode: "k", k: 2 } # k|alpha|quantile

metrics:

mae: { tolerance: 1.0e-4 }

auc: { tolerance: 2.0e-3 }

r_phi: { lb95_min: 0.60 }

latency_p95_s: { guard: 0.200 }

rules:

interval_overlap_required: true

same_coverage_band_required: true

H. 发布清单 report_manifest.yaml（节选）

version: "1.0.0"

bundle:

reports: ["reports/check_dim_report.json","reports/validate_report.json","reports/audit.jsonl"]

figs: ["figs/metric_curves.pdf","figs/interval_bands.svg","figs/path_profile.pdf"]

checksums: "checksums.txt"

sign: "SIGNATURE.asc"

I. 校验和 checksums.txt（格式）

sha256 model/model_manifest.yaml <64-hex>

sha256 reports/check_dim_report.json <64-hex>

sha256 eval/scorecard.json <64-hex>

...

IV. 路径量统一口径（Normative Path Forms）

• 到达时（两式等价）：
  T_arr = ( 1 / c_ref ) * ( ( ∫ n_eff d ell ) )
  T_arr = ( ( ∫ ( n_eff / c_ref ) d ell ) )
• 相位累计：
  Phi = ( ( 2π / λ_ref ) * ( ∫ n_eff d ell ) )

复现与核验前按“时间→路径→相位”对齐；len(gamma_ell)=len(d_ell)=len(n_eff)≥2；数据侧记录 delta_form；p_dim = 1.0。

V. 质量门映射（Gate Mapping）

• G1 Schema 完整：本章清单与强制制品齐备；
• G2 引用合规：see[]/version 锚点直指率 ≥ 90%；
• G3 路径规范：模板显式 gamma/measure/delta_form；
• G4 量纲闭合：check_dim_report.json 通过；
• G5 新鲜度：包含数据/参数快照时满足 freshness.policy；
• G6 覆盖一致：coverage.mode 在 UQ/评测/部署/监控一致；
• G7 协方差一致：Σ PD 且与误差卷配置一致；
• G8 唯一性与无环：checksums.txt 无重复，引用 lineage 无环。
• 触发 S1–S5 即拒绝验收或标注 [Restricted]。

VI. 交叉引用（Cross-References）

• 第3章（目录与制品）、第4章（环境锁定）、第5章（数据快照）、第6章（权重参数与新鲜度）、第7章（脚本与命令）、第8章（种子与确定性）、第9章（指标与门）、第10章（复现实验流程）、第11章（差异诊断与回退）。
• 《模型卡》Ch.10/Ch.12；《数据集卡》Ch.11；《误差预算卡》Ch.8/Ch.9；《管线卡》Ch.12。

VII. 勾选清单（Checklist）

• 所有模板已按本卷口径入库，see[]/version 合规且锚点直指率 ≥ 90%。
• 路径模板显式 gamma/measure/delta_form；到达时/相位采用括号化统一口径；I70-dim_check 通过，p_dim = 1.0。
• report_manifest.yaml / checksums.txt / SIGNATURE.asc 已更新；制品均含 sha256 与签名。
• 覆盖与协方差口径在 UQ/评测/部署/监控一致；图片双份导出并标注单位与覆盖模式。
• 发现不合规项已标注 [Restricted] 并附修复路径与复检步骤。