44-EFT.WP.Data.ModelCards v1.0 | Chapter 17 Examples & Best Practices

Home ／ Docs-Technical WhitePaper ／ 44-EFT.WP.Data.ModelCards v1.0

Chapter 17 Examples & Best Practices

I. Chapter Purpose & Scope

II. Minimal Working Model Card (release-grade; validates under Schema & Lint)

model_id: "eift.vision.cls.resnet50"

title: "ResNet50 Classifier"

version: "v1.0"

task: "classification"

io_schema:

inputs: [{name:"image", shape:"(H,W,3)", dtype:"uint8", range:"[0,255]", semantics:"rgb"}]

outputs: [{name:"probs", shape:"(K,)", dtype:"float32", range:"[0,1]", semantics:"softmax"}]

batching: {mode:"dynamic", max_batch:128}

streaming: {enabled:false}

architecture:

version: "v1.0"

backbone: "resnet50"

topology:

- {name:"stem", type:"conv", params:{out:64, k:7, s:2, norm:"bn", act:"relu"}}

- {name:"stage1",type:"resblk", repeat:3, params:{out:256, bottleneck:true}}

- {name:"stage2",type:"resblk", repeat:4, params:{out:512}}

- {name:"head", type:"linear", params:{out_dim:1000}}

training_data:

refs:

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

splits_ref: "eift.obs.demo@v1.0"

contamination_policy: "forbid-cross-split"

leakage_guards: ["per-object"]

preprocess:

pipeline_id: "img-prep-v1"

steps:

- {name:"standardize", enabled:true, idempotent:true,

params:{type:"zscore", mean:[0.485,0.456,0.406], std:[0.229,0.224,0.225], stats_from:"train-only"},

inputs:["image"], outputs:["image_std"]}

feature_space: {type:"dense", shape:"(H',W',C')", dtype:"float32", normalization:"zscore"}

parameter_lock: true

optimization:

objective: {name:"cross_entropy", reduction:"mean"}

optimizer: {name:"adamw", lr:3.0e-4, betas:[0.9,0.999], eps:1.0e-8, weight_decay:0.05}

scheduler: {name:"cosine", warmup:{steps:500, mode:"linear"}}

hyperparams: {batch_size:256, epochs:200}

evaluation:

protocol:

splits: "frozen"

seeds: [0,1,2,3,4]

repeats: 5

ci: {method:"bootstrap-bca", level:0.95, samples:1000}

significance: {test:"permutation", alpha:0.05}

metrics:

classification: ["f1_macro","roc_auc","ece","brier"]

calibration:

method: "temperature"

params: {t: 1.7}

robustness:

thresholds: {drop_rel_max: 0.10}

fairness:

axes: ["class","region"]

gap_metric: "abs_diff"

threshold: 0.05

safety:

allowed_use: ["academic","benchmark"]

prohibited_use: ["surveillance"]

deployment:

forms: ["rest"]

devices: ["A100"]

latency_targets_ms: {p50: 5}

resources:

M_param: 25.6

FLOPs: 4.1e9

T_inf: 3.8

metrology: {units:"SI", check_dim:true}

export_manifest:

version: "v1.0"

artifacts:

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

- {path:"eval/summary.csv", sha256:"..."}

references:

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

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

III. Full Example with Path Quantities (T_arr) — Multimodal + Robustness/Fairness

model_id: "eift.radio.audio.asr_toa"

title: "ASR + TOA Estimator"

version: "v1.2"

task: ["asr","forecasting"]

io_schema:

modes:

asr:

inputs: [{name:"waveform", shape:"(T,)", dtype:"float32", range:"[-1,1]", semantics:"pcm"}]

outputs: [{name:"text", shape:"()", dtype:"string", range:"N/A", semantics:"utf-8"}]

forecasting:

inputs:

- {name:"series", shape:"(T,C)", dtype:"float32", semantics:"zscore"}

- {name:"time_index", shape:"(T,)", dtype:"int64", semantics:"unix_ms"}

outputs:

- {name:"y_hat", shape:"(H,C)", dtype:"float32", semantics:"forecast"}

- {name:"q_hat", shape:"(H,C,Q)", dtype:"float32", semantics:"quantiles"}

architecture:

version: "v1.0"

backbone: "conformer-xs"

topology:

- {name:"enc", type:"conformer", repeat:12, params:{dim:256, heads:4, ff_mult:4, act:"silu", norm:"ln"}}

- {name:"toa_head", type:"mlp", params:{hidden:512, out_dim:1}}

params_report: {M_param: 32.4, FLOPs: 9.6e9, T_inf: 12.1}

training_data:

refs:

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

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

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

splits_ref: "eift.radio.toa-set@v1.2"

sampling_binding:

strategy: "stratified"

strata: [{by:"snr_bin", buckets:{"7-10":300,"10-20":500,"20+":700}}]

contamination_policy: "forbid-cross-split"

leakage_guards: ["per-timewindow"]

preprocess:

pipeline_id: "toa-prep-v2"

steps:

- {name:"rfi_clean", enabled:true, idempotent:true, params:{method:"spectral-kurtosis", window:256, thr_sigma:5}}

- {name:"stft", enabled:true, idempotent:true, params:{win:512, hop:160, window:"hann"}}

feature_space: {type:"audio_spec", shape:"(F,T)", dtype:"float32", normalization:"zscore"}

parameter_lock: true

path_dependence:

applies_to: ["T_arr"]

delta_form: "const-factor"

path: "gamma(ell)"

measure: "d ell"

see: ["EFT.WP.Core.Equations v1.1:S20-1","EFT.WP.Core.Metrology v1.0:check_dim"]

optimization:

objective:

name: "mse"

reduction: "mean"

formula: "L(θ) = ( E_{(x,y)∼D} [ ( y - f_θ(x) )^2 ] )"

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

scheduler: {name:"cosine", warmup:{steps:2000, mode:"linear"}}

hyperparams: {batch_size:64, epochs:120}

evaluation:

protocol:

splits: "frozen"

seeds: [0,1,2,3,4]

repeats: 5

significance: {test:"bootstrap", alpha:0.05}

ci: {method:"bootstrap-bca", level:0.95, samples:2000}

metrics:

timeseries: ["rmse","mae","qloss@{0.1,0.5,0.9}"]

classification: ["ece","brier"]

calibration:

method: "temperature"

params: {t:1.6}

eval: {report:["ece","brier","calibration_curve"], ece_bins:15}

uncertainty:

model: "linear"

components:

- {name:"thermal", type:"random", value:2.1, unit:"K", distribution:"normal", coverage:{k:1.0}}

- {name:"iono", type:"systematic", value:0.7e-9, unit:"s", distribution:"normal", coverage:{k:2.0}, corr_group:"path"}

correlation: {posture:"groups", groups:[{name:"path", pairwise:"rho:0.5"}]}

propagation: {rule:"linear", linearization:"first-order"}

coverage_policy: {target_p:0.95, k:2.0}

robustness:

shift_tests:

- {name:"snr_drop", severity:[3,6,9], policy:"additive-noise"}

- {name:"spec_notch",bands:[["0.3","0.5"],["0.6","0.7"]], unit:"fraction"}

thresholds: {drop_rel_max:0.10}

fairness:

axes: ["region","device"]

gap_metric: "abs_diff"

threshold: 0.05

deployment:

forms: ["grpc"]

devices: ["A100","CPU-AVX2"]

latency_targets_ms: {p50: 20, p99: 80}

concurrency: 256

resources: {M_param:32.4, FLOPs:9.6e9, T_inf:12.1}

metrology: {units:"SI", check_dim:true}

export_manifest:

version: "v1.2"

artifacts:

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

- {path:"eval/summary.csv", sha256:"..."}

- {path:"robustness/acc_vs_snr.csv", sha256:"..."}

references:

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

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

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

IV. Common Failures → Fixes (mapped to Lint/Schema)

• Non-compliant reference: "Core.DataSpec:EXPORT" → Fix: "EFT.WP.Core.DataSpec v1.0:EXPORT".
• Evaluation split not frozen: evaluation.protocol.splits:"custom" → Fix: set "frozen" and reference the Dataset Card indices.
• Softmax not bounded: range:"(-∞,+∞)" → Fix: range:"[0,1]" with sum==1±1e-6.
• Missing metrology: absent metrology or check_dim:false → Fix: metrology:{units:"SI", check_dim:true}.
• Path quantity unregistered: using T_arr without delta_form/path/measure → Fix: add the three fields and validate using one of the two equivalences.
• Leakage: same object/timewindow across splits → Fix: set leakage_guards and rebuild indices; record in audits and evaluation.
• Fairness threshold absent: missing threshold → Fix: set explicitly and report CIs & significance.

V. Best-Practice Checklist (release-critical)

• Citations & versions: Use “Volume vX.Y:Anchor” for all cross-volume citations; public materials pin to a stable line (v1.*) or minor.
• Splits & randomness: Use frozen splits only; provide seeds/repeats plus CIs/significance; report batch/device posture.
• Metrology consistency: Pass check_dim for all units/dimensions; normalize units before combining statistical & metrological uncertainties.
• I/O alignment: Keep io_schema identical to deployment endpoints; provide named sub-modes for multi-task.
• Robustness/Fairness: Set blocking thresholds (e.g., drop_rel_max, fairness gaps) and attach curves & stratified tables in exports.
• Traceable artifacts: List logs, locks, eval tables/plots, and alert rules in export_manifest.artifacts[] with sha256.

VI. Validation API Linkage (examples)

curl -s -X POST https://api.eift.org/api/v1/validate_model_card \

-H "Authorization: Bearer <token>" \

-H "Content-Type: application/json" \

-H "x-eift-idempotency: a0d7b6c4-9478-4e4a-9f13-8c1b9f77f111" \

-d @model_card.json

curl -s -X POST https://api.eift.org/api/v1/check_units \

-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \

-d @model_card.json

curl -s -X POST https://api.eift.org/api/v1/robustness_eval -d @model_card.json

curl -s -X POST https://api.eift.org/api/v1/fairness_eval -d @model_card.json

VII. Chapter Compliance Checklist

• Example Model Cards validate under Chapter 15 Schema & Lint; export_manifest lists anchors and artifact hashes.
• If T_arr appears, delta_form/path/measure are recorded and check_dim passes; math uses backticks and parentheses with no Chinese.
• io_schema, evaluation protocol, and deployment endpoints are consistent; frozen splits, significance, and CI reports are present.
• Robustness & fairness items include thresholds and pass; if adversarial enabled, include norm/steps/ε/restarts.
• Validation-API examples are reproducible; release only after clearing all blockers.