53-模型卡 Template v1.0 | 第13章 附录（表单/清单/模板）

目录 ／ 文档-技术白皮书 ／ 53-模型卡 Template v1.0

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

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/

model_uq.yaml

uq_summary.json

budget_breakdown.csv

eval/

bench_plan.yaml

scorecard.json

eval_report.md

monitoring/

monitoring_rules.yaml

rollback_fsm.yaml

alerts.jsonl

reports/

check_dim_report.json

validate_report.json

audit.jsonl

figs/

model_arch.svg

latency_hist.pdf

throughput_series.svg

path_profile.pdf

SIGNATURE.asc

report_manifest.yaml

III. 模型清单与兼容矩阵（Model Manifest & Compatibility）

A. model_manifest.yaml

version: "1.0.0"

model:

id: "mdl-core"

semver: "1.2.0"

task: ["regression","path-estimation"]

io:

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

outputs: ["obs.T_arr (s)","obs.Phi (rad)","score.uncertainty"]

deps:

dataset_card: "Dataset Card v1.0:Ch.3/4/6/7/8/11/12"

parameter_card: "Parameter Card v1.0:Ch.4/6/8/9"

error_budget: "Error Budget Card v1.0:Ch.5/6/8/9"

pipeline_card: "Pipeline Card v1.0:Ch.11/12"

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

sign: "SIGNATURE.asc"

checksums:

weights: "sha256:..."

code: "sha256:..."

B. compat_matrix.yaml

runtime:

cuda: ">=12.2,<13.0"

driver: ">=535"

framework: { torch: "2.2.x", triton: "2.2.x" }

data:

schema: ">=1.2,<2.0"

splits: ">=1.1,<2.0"

pipeline_api: ">=1.0,<2.0"

notes:

- "Path block required: gamma/d ell/delta_form"

IV. 架构与控制式（Architecture & Control）

A. control_spec.yaml

version: "1.0.0"

preprocess:

normalize: { mean: "μ", std: "σ" }

path_align: { require: true, delta_form: "general" }

core:

f_theta: { type: "hybrid", ops: ["conv","attn","mlp"] }

loss:

total: "L = E[ℓ] + λ R"

tasks: ["task_main","task_aux"]

path_forms:

T_arr: "( ∫ ( n_eff / c_ref ) d ell )"

Phi: "( (2π / lambda_ref) * ∫ n_eff d ell )"

postprocess:

scale: { a: "learned", b: "learned" }

B. model_arch.svg

V. 训练与 HPO（Training & HPO）

A. train_config.yaml

version: "1.0.0"

seed: 20250924

batch: { size: 256, accum: 2, drop_last: true }

optimizer: { name: "adamw", lr: 3.0e-4, betas: [0.9,0.999], weight_decay: 0.01 }

lr_scheduler: { name: "cosine", warmup_steps: 1000, min_lr: 1.0e-6 }

amp: { enabled: true, dtype: "fp16" }

grad_clip: { type: "norm", max: 1.0 }

ddp: { world_size: 8, backend: "nccl", sync_bn: true }

eval: { every_steps: 1000, metrics: ["MAE","AUC","r_phi","Q_res"], coverage: { mode: "k", k: 2 } }

checkpoint: { best: "min:val/MAE", every_steps: 5000, keep_last: 5 }

B. hpo_space.yaml

lr: { type: "loguniform", low: 3.0e-5, high: 3.0e-3 }

wd: { type: "loguniform", low: 1.0e-6, high: 1.0e-2 }

batch: { type: "choice", values: [128,256,512] }

warmup: { type: "choice", values: [500,1000,2000] }

VI. 部署接口与绑定（Deployment APIs & Bindings）

A. inference_openapi.yaml

openapi: 3.0.3

info: { title: "Model Inference API", version: "1.0.0" }

paths:

/models/{id}/infer:

post:

summary: "Idempotent inference"

requestBody:

content: { application/json: { schema: { $ref: "#/components/schemas/InferRequest" } } }

responses:

"200": { description: "OK" }

B. inference.proto（节选）

message Ctx { string idempotency_key = 1; string coverage = 2; bool return_uq = 3; }

message InferRequest { Ctx ctx = 1; bytes inputs = 2; }

message InferResponse { string status = 1; bytes payload = 2; bytes uq = 3; string version = 4; string checksum = 5; }

C. binding_spec.md（提纲）

# Binding Spec

- I/O fields and units/dimensions

- Coverage mode and UQ payload

- Error classes and return envelope

VII. UQ 与误差预算（UQ & Error Budget）

A. model_uq.yaml

version: "1.0.0"

targets: ["T_arr","Phi","epsilon_flux","r_phi","Q_res"]

methods:

T_arr: { type: "delta", jacobian: "auto", cov_group: "medium" }

Phi: { type: "mc", draws: 10000, coverage: { quantile: [0.025,0.975] } }

coverage: { mode: "k", k: 2 }

covariance:

medium: { kernel: "exp", params: { sigma2: 9.0e-6, L_c_m: 25.0 } }

reports: ["uq_summary.json","cov_blocks.json"]

B. uq_summary.json

{ "T_arr":{"point":1.23e-8,"U_k2":1.5e-9}, "Phi":{"median":0.035,"q025":0.028,"q975":0.043} }

C. budget_breakdown.csv（表头）

source,variance_share,u_or_sigma,notes

VIII. 评测与评分（Evaluation & Scoring）

A. bench_plan.yaml

version: "1.0.0"

tasks:

- id: "bench-arrival"

split: "test"

metrics: ["DeltaT_arr_s","Q_res","p_dim"]

coverage: { mode: "k", k: 2 }

baseline: { id: "base-001", version: "1.2.3" }

weights: { DeltaT_arr_s: 0.35, r_phi: 0.25, epsilon_flux: 0.15, p_dim: 0.15, Q_res: 0.10 }

B. scorecard.json（示例）

{

"version":"1.0.0",

"baseline":{"id":"base-001","Q":0.62},

"method":{"id":"mdl-core","Q":0.78},

"weights":{"DeltaT_arr_s":0.35,"r_phi":0.25,"epsilon_flux":0.15,"p_dim":0.15,"Q_res":0.10}

}

IX. 监控与回退（Monitoring & Rollback）

A. monitoring_rules.yaml

version: "1.0.0"

kpis:

latency_p95_s: { target: 0.200, alert: 0.250, critical: 0.300 }

throughput_rps: { target_min: 1000 }

q_res: { target_max: 0.20 }

p_dim: { require: 1.0 }

drift:

data: { test: "ks", p_crit: 0.01 }

actions:

on_alert: ["degrade"]

on_critical: ["rollback"]

B. rollback_fsm.yaml

version: "1.0.0"

states: [normal, degrade, rollback, recover]

transitions:

- { from: normal, to: degrade, when: "gate_alert or drift_alert" }

- { from: degrade, to: rollback, when: "gate_critical or perf_critical" }

- { from: rollback,to: recover, when: "stable_prev_version_ready" }

- { from: recover, to: normal, when: "validate_pass and perf_ok" }

C. alerts.jsonl（示例行）

{
  "ts": "2025-09-24T16:10:00Z",
  "level": "critical",
  "event": "gate_fail",
  "gate": "G4",
  "detail": "p_dim < 1.0",
  "action": "rollback"
}

X. 发布清单（Release Manifest）

A. report_manifest.yaml

version: "1.0.0"

bundle:

figs:

- "figs/model_arch.svg"

- "figs/path_profile.pdf"

reports:

- "reports/check_dim_report.json"

- "reports/validate_report.json"

- "reports/audit.jsonl"

configs:

- "model/model_manifest.yaml"

- "model/compat_matrix.yaml"

sign: "SIGNATURE.asc"

see:

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

- "EFT.WP.Core.Equations v1.1:S20-1"

XI. 路径量统一口径（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 )

正文显式路径与测度，数据侧记录 delta_form；路径数组 len(gamma_ell)=len(d_ell)=len(n_eff)≥2，发布要求 p_dim = 1.0。

XII. 执行勾选清单（Checklist）

• 清单与模板按本卷与跨卷口径落库，see[]/references[]/version 合规且锚点直指率 ≥ 90%。
• 路径相关模板显式 gamma/measure/delta_form，到达时/相位采用括号化统一口径；I70-dim_check 通过，p_dim = 1.0。
• report_manifest.yaml / check_dim_report.json / validate_report.json / audit.jsonl / SIGNATURE.asc 齐备。
• 训练/推理/UQ/评测/监控/回退模板间覆盖与协方差口径一致；产出均含 checksum。
• 不合规项已标注 [Restricted] 并限制为定性发布；路径图注明 Δell 与 delta_form。