14-EFT.WP.Methods.Inference v1.0 | 附录B 实现绑定与函数原型

目录 ／ 文档-技术白皮书（V5.05） ／ 14-EFT.WP.Methods.Inference v1.0

附录B 实现绑定与函数原型

I. 范围与目标

• 给出 I40-* 实现绑定的原型、输入输出、幂等与确定性契约、观测与审计字段，以及异常模型，确保跨环境、跨设备与跨版本的一致可复现推理。
• 本附录与第3、6、7、8、9、10、11、12、13章的度量口径、卡片结构与门限策略保持一致；所有时间戳在处理与发布前映射到 ts = alpha + beta * tau_mono。

II. 设计原则与通用契约

• 幂等与确定性
  在锁定 EnvLock 与固定 anchor 下，同一输入调用返回等价输出；若存在随机化算子，须记录 rng.seed 与 rng_family，并提供确定性回放选项 opts.det = true。
• 量纲与安全
  所有表达在入参与产出前执行 check_dim(expr)；log/exp/ln 自变量无量纲。
• 观测与审计
  每个 I40-* 调用均产出 TS.latency_{p50,p95,p99}、TS.error、资源采样 budget.cpu/gpu/mem、cost.per.req，并写入可验证指纹 fingerprint 与 anchor。
• 错误与回退
  非致命异常统一上抛枚举（见本附录 XV），并提供 kill_switch、holdback 钩子以配合第10章告警与自愈。

III. 公共数据结构（摘要）

• Graph
  键：sig:str, ops:list, inputs:spec, outputs:spec, dtype:dict, version:str。
• Runtime
  键：graph:Graph, artifacts:list, device:str, precision:str, EnvLock:dict, rng:{seed:int,family:str}。
• ScoreReport
  键：metrics:dict, R_emp:float, R_exp:float|None, ECE:float|None, MCE:float|None, NLL:float|None, confusion:dict|None, ts:str, fingerprint:str。
• CalibReport
  键：method:str, T_temp:float|None, iso_map:any|None, ECE_before:float, ECE_after:float, NLL_before:float, NLL_after:float, ts:str。
• DriftReport
  键：tests:{psi:float|None,ks:float|None,js:float|None}, p_value:float|None, decision:str, reasons:list, ts:str。
• ConsistencyReport
  键：delta_offon:float, R_infer:float, window:dict, policy:dict, decision:str, reasons:list, ts:str。
• Attribution
  键：method:str, importances:any, baseline:any|None, ts:str。

IV. I40-1 build_inference_graph(spec:dict) -> Graph

1. 入参 spec
   • 必填：inputs:spec, outputs:spec, ops:list, dtype:dict, precision:str, constraints:dict。
   • 可选：quant:dict, fuse:bool, determinism:bool。
2. 契约
   • 若 spec.determinism = true，则禁止引入非确定性算子；检查 ops 条件数与数值稳定性。
   • 产出 Graph.sig = hash(spec)，并与 anchor 绑定。
3. 失败与异常
   E_SCHEMA_MISMATCH，E_PRECISION_LOSS，E_NONDETERMINISM。
4. 伪流程
   • 生成 Graph 与 sig，记录 TS.*。
   • 图优化（折叠、融合、量化），保序保证。
   • 校核 dtype/precision 与量纲。

V. I40-2 load_artifacts(anchor:str) -> Runtime

1. 入参 anchor
   语义：模型权重、特征规范、依赖哈希的联合引用。
2. 契约
   • Runtime.EnvLock 必须锁定驱动、库、硬件能力；若缺失则报错。
   • 记录 rng.seed 与 rng_family，默认从 anchor 复现。
3. 失败与异常
   E_MODEL_MISMATCH，E_RESOURCE_EXCEEDED，E_TIMEBASE_SKEW。

VI. I40-3 run_inference(rt:Runtime, inputs:any, opts:dict) -> outputs:any

1. 入参
   • inputs：遵循第4章接口与第9章卡片的 features.spec。
   • opts：batch:int, timeout_ms:int, det:bool, trace:bool。
2. 契约
   • 对每批次输出 y_hat 或分布要素 mean,var,quantile_q；若 opts.det = true 则强制固定随机源。
   • 产出随附 TS.latency、TS.error 与资源采样；对流式返回追加 ts（已完成 ts = alpha + beta * tau_mono）。
3. 失败与异常
   E_RESOURCE_EXCEEDED，E_PRECISION_LOSS，E_NONDETERMINISM。

VII. I40-4 score_predictions(y_true:any, y_pred:any, metrics:dict) -> ScoreReport

1. 入参
   metrics 示例：{"acc":true,"auc":true,"ECE":{"K":15},"NLL":true,"reg":{"rmse":true}}。
2. 契约
   • 统一口径：R_emp = ( 1/N ) * Σ L( y_i, y_hat_i )；分类报告阈值扫描域须在 metrics 声明。
   • 校准度量：ECE,MCE,NLL 与第7章一致。
3. 失败与异常
   E_SCHEMA_MISMATCH，E_CALIBRATION_FAIL（若分布输出缺失导致不可算）。

VIII. I40-5 calibrate(runtime:Runtime, method:str, data:any) -> CalibReport

1. 入参
   method ∈ {"temperature","isotonic"}；data 含验证集或在线对照窗。
2. 契约
   • 温度缩放：学习 T_temp > 0，更新后 ECE_T <= ECE；NLL_after <= NLL_before 为最小通过门。
   • 保留可逆映射与版本化，写回 artifacts 并更新 anchor。
3. 失败与异常
   E_CALIBRATION_FAIL，E_RESOURCE_EXCEEDED。

IX. I40-6 estimate_uncertainty(runtime:Runtime, x:any) -> {mean:float, var:float, intervals:list}

1. 入参
   x：单样本或小批；方法隐式自 runtime 推断（如 ensemble,mc_dropout,quantile_reg）。
2. 契约
   • 输出至少包含 mean,var 与置信区间 intervals，需标明置信度 1 - delta 与构造法 method。
   • 与第7章的校准映射后输出 _T 版本（如 var_T）。
3. 失败与异常
   E_MODEL_MISMATCH，E_RESOURCE_EXCEEDED。

X. I40-7 monitor_drift(stream:any, spec:dict) -> DriftReport

1. 入参
   spec：{"window":"W","tests":{"psi":true,"ks":true,"js":true},"tau":{"psi":0.2,"p":0.05}}。
2. 契约
   • 计算分布漂移并生成决策：decision ∈ {"ok","warn","block"}；与第10章告警矩阵映射。
   • 若 decision = "block"，触发 kill_switch 并写入原因 reasons。
3. 失败与异常
   E_DRIFT_DETECTED（作为可控异常上抛） 。

XI. I40-8 align_timebase(trace:any, reference:any) -> {alpha:float, beta:float, fit:dict}

1. 契约
   • 依据公设 P41-2 拟合线性映射 ts = alpha + beta * tau_mono；推荐鲁棒回归或 RANSAC。
   • 产出 fit 含残差分布与 CI_{1-delta}；若 |beta - 1| > tau_cons 报告 E_TIMEBASE_SKEW。
2. 失败与异常
   E_TIMEBASE_SKEW。

XII. I40-9 explain(runtime:Runtime, x:any, method:str) -> Attribution

1. 入参
   method ∈ {"grad","intgrad","shap","lime"}。
2. 契约
   • 解释不改变推理路径；对随机近似方法固定 rng.seed；返回 importances 与可能的 baseline。
   • 记录解释计算的 TS.latency 与资源占用，纳入 score 的成本分量。
3. 失败与异常
   E_RESOURCE_EXCEEDED。

XIII. I40-10 compare_offline_online(off:any, on:any, policy:dict) -> ConsistencyReport

1. 入参
   policy：{"window":"W","tau_cons":0.01,"metrics":["delta_offon","ECE","NLL"]}。
2. 契约
   • 计算 delta_offon = ( norm( y_hat_off - y_hat_on ) / norm( y_hat_off ) )，并给出 R_infer = 1 - delta_offon。
   • 复刻窗口、对齐 ts，对分布输出比对 ECE/NLL 与第7章口径一致。
   • 输出决策 decision ∈ {"pass","hold","rollback"} 与 reasons。
3. 失败与异常
   E_TIMEBASE_SKEW，E_SCHEMA_MISMATCH。

XIV. 典型状态机与回退钩子

1. 状态集合：INIT -> READY -> RUNNING -> DEGRADED -> ROLLBACK -> ARCHIVED。
2. 迁移条件
   • READY -> RUNNING：I40-10.decision = "pass" 且 score >= score_LCB。
   • RUNNING -> DEGRADED：TS.error > tau_error 或 I40-7.decision = "warn"。
   • DEGRADED -> ROLLBACK：I40-7.decision = "block" 或 I40-10.decision = "rollback"。
   • ROLLBACK -> READY：恢复到上一个 anchor，ConsistencyReport 通过。
3. 回退动作
   触发 kill_switch，限制 q <= q_cap，应用 holdback 并更新 RingMetrics。

XV. 异常枚举与处置建议

• E_MODEL_MISMATCH：图与权重签名不一致；处置 load_artifacts 回滚到上一个 anchor。
• E_SCHEMA_MISMATCH：输入/输出模式不符；处置校正 features.spec 与 ParamCard。
• E_TIMEBASE_SKEW：时基偏斜；处置执行 I40-8 并重算 ts。
• E_NONDETERMINISM：检测到非确定性；处置设置 opts.det = true 或替换算子。
• E_CALIBRATION_FAIL：校准不可收敛或退化；处置更换方法或扩大验证窗。
• E_DRIFT_DETECTED：漂移超门；处置降级与回退。
• E_RESOURCE_EXCEEDED：资源超预算；处置限流、切换精度 fp32/fp16/int8 或更换设备。
• E_PRECISION_LOSS：数值不稳定或下溢；处置调整缩放或提高精度。

XVI. 观测、审计与合规字段

• 观测键：TS.latency_{p50,p95,p99}, TS.thrpt, TS.error, budget.cpu/gpu/mem, budget.power, cost.per.req。
• 审计键：anchor, fingerprint, Graph.sig, EnvLock, rng.seed, rng.family, version, channel, PlanId, GateDecision, reasons。
• 时间键：所有事件采集前先对齐 ts = alpha + beta * tau_mono。

XVII. 跨域/跨设备钩子

• 设备等效性
  输出 delta_dev 与 CertEq，依据第11章口径对 precision/quant 组合做同等性检验。
• 站点差异
  I40-10 支持 policy.site 维度，以环 R = {R0,R1,R2,R3} 聚合并验证 score 的下置信界 score_LCB。

XVIII. 版本与弃用策略

• 版本遵循 ver = major.minor.patch；主版本变更可能破坏兼容，需要新建 ParamCard.version 并设定 meta.parent_fingerprint。
• 弃用窗口
  至少跨两个 channel 周期（canary -> stable），并提供 compare_offline_online 报告链路证据。

XIX. 最小实现清单（建议顺序）

• 实现 I40-1/I40-2 并完成 EnvLock/anchor 管理。
• 实现 I40-3 的确定性回放与 TS.* 观测。
• 实现 I40-4/I40-5 以进入第7章校准与第8章评分。
• 实现 I40-10 与第6章一致性策略。
• 实现 I40-7 与第10章告警矩阵。
• 实现 I40-8 的时基对齐与验收前校验。
• 可选实现 I40-6/I40-9 以增强不确定性与可解释性。

XX. 交叉引用

• 术语与符号：附录A。
• 数据与特征接口：第4章。
• 校准与不确定性：第7章。
• 性能度量与 SLO：第8章。
• 管线卡与配置卡：第9章。
• 运行、监控与告警：第10章。
• 跨域/跨设备：第11章。
• 验收与评分发布：第12章。
• 变更管理与灰度策略：第13章。