53-模型卡 Template v1.0 | 第10章 部署接口与实现绑定（API/函数原型）

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

第10章 部署接口与实现绑定（API/函数原型）

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

• 规范模型在部署阶段的对外接口（REST/gRPC/CLI）与实现绑定（函数原型、类型与错误语义、幂等/重试/审计），确保线上推理可复现、可审计、可回滚，并与数据/参数/误差/管线各卷口径一致。
• 凡涉及路径量（到达时/相位），正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；所有表达一律括号化，发布要求 p_dim = 1.0。

II. 前置条件与输入（Prerequisites & Inputs）

• 数据与切分：对齐《数据集卡》Ch.4/Ch.6/Ch.7/Ch.10（Schema/Splits/QC/API）。
• 训练与权重：对齐本卷 Ch.6 的 train_config.yaml、best.ckpt 与环境快照。
• 覆盖与协方差：对齐《误差预算卡》之覆盖（k/alpha/quantile）与 Σ PD。
• 参数与新鲜度：对齐《参数注册卡》之 freshness.policy 与 cov_group。
• 引用与版本：一律“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%；对外仅 v1.*。

III. 错误语义与返回信封（Error Model & Return Envelope）

• 错误分类：E_INPUT / E_DIM / E_GATE / E_SYNC / E_UQ / E_DRIFT / E_INTERNAL。
• 统一返回信封：

{

"status":"OK|ERROR",

"code":0,

"error":{"type":"E_*","message":"...","details":{}},

"payload":{},

"metrics":{"latency_ms":87,"retries":0},

"anchors":["EFT.WP.Core.Equations v1.1:S20-1"],

"version":"1.0.0",

"checksum":"sha256:..."

}

IV. REST OpenAPI（节选）

openapi: 3.0.3

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

servers: [{ url: "https://api.example.com/v1" }]

components:

securitySchemes: { bearerAuth: { type: http, scheme: bearer } }

schemas:

InferRequest:

type: object

required: [idempotency_key, inputs]

properties:

idempotency_key: { type: string }

inputs: { type: array, items: { type: object } }

options:

type: object

properties:

coverage: { type: string, enum: ["k","alpha","quantile"] }

return_uq: { type: boolean, default: true }

InferResponse:

type: object

properties:

status: { type: string }

payload: { type: object }

uq: { type: object }

anchors: { type: array, items: { type: string } }

version: { type: string }

checksum: { type: string }

paths:

/models/{id}/infer:

post:

security: [{ bearerAuth: [] }]

summary: "Idempotent inference"

parameters: [{ in: path, name: id, required: true, schema: { type: string } }]

requestBody:

required: true

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

responses:

"200": { description: "OK", content: { application/json: { schema: { $ref: "#/components/schemas/InferResponse" } } } }

"409": { description: "Idempotency conflict" }

/models/{id}/validate:

post:

summary: "Validate gates G1–G8 & report stops"

responses: { "200": { description: "Validation report" } }

V. gRPC（proto 节选）

syntax = "proto3";

package model.v1;

​

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

message InferRequest { Ctx ctx = 1; bytes inputs = 2; } // inputs: Avro/JSON/Parquet

message InferResponse {

string status = 1;

bytes payload = 2; // outputs

bytes uq = 3; // optional UQ bundle

repeated string anchors = 4;

string version = 5;

string checksum = 6;

}

service Inference {

rpc Infer (InferRequest) returns (InferResponse);

rpc Validate (InferRequest) returns (InferResponse);

}

VI. CLI（节选）

# 幂等推理

mdl infer mdl-core \

--idempotency_key run42+p010+win001 \

--inputs @samples.json \

--coverage k --return_uq true \

--out outputs/predictions.json

​

# 门校验

mdl validate mdl-core --out reports/validate_report.json

VII. 实现绑定（函数原型 I60–I69）

1. I60-infer(ctx, x) -> y | err
   • in：ctx{idempotency_key,coverage,return_uq}，x 与《数据集卡》Ch.4 对齐；
   • out：y（含单位/量纲）与可选 uq；
   • 错误：E_INPUT/E_DIM/E_GATE/E_SYNC/E_UQ/E_DRIFT/E_INTERNAL。
2. I61-validate_gate(card, gates[]) -> report.json：返回 G1–G8 与 stops_triggered。
3. I62-export_artifacts(fmt) -> {manifest, checksums}：fmt ∈ {zip,tgz}。
4. I63-path_align(path,inplace=false) -> path'：校验 gamma/measure/delta_form 与步长。
5. I64-derive_arrival(path,c_ref) -> T_arr：T_arr = ( ∫ ( n_eff / c_ref ) d ell )（或常量外提式）。
6. I65-derive_phase(path,lambda_ref) -> Phi：Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )。
7. I66-uq_delta(J, Σ) -> {u, u_c, U}；I67-cov_merge(blocks[]) -> Σ（PD 校验与抖动）。
8. I68-rollback_fsm(event) -> state：触发回退/降级；
9. I69-emit_audit(event) -> OK：写 audit.jsonl。

VIII. 路径接口专规（Path-Specific Rules）

• 必备字段：path.gamma_ell[]、path.d_ell[]、medium.n_eff_profile[]、ref.c_ref、（相位类）ref.lambda_ref；响应需回显 delta_form。
• 统一口径：
  T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )；或 T_arr = ( ∫ ( n_eff / c_ref ) d ell )；
  Phi = ( 2π / λ_ref ) * ( ∫ n_eff d ell )。
• 量纲闭合：返回前必须运行 I70-dim_check，保证 p_dim = 1.0；单位/量纲在 payload.meta 标注。

IX. 幂等、重试与审计（Idempotency, Retry & Audit）

• 幂等键：idempotency_key = f(model_id, inputs_hash, window, partition, …)；同键多次调用输出不变。
• 重试策略：retry_policy = {max_retries, backoff ∈ {const, exp, jitter}, deadline}；重试不改变 idempotency_key 与输入快照。
• 审计：所有写/导出在 audit.jsonl 记录时间、操作者、输入哈希、字节数、签名与 checksum。

X. 质量门映射（Gate Mapping）

• G1 Schema 完整（I/O 与契约一致）；G2 引用合规（锚点直指率 ≥ 90%）；
• G3 路径规范（路径块齐备、步长合规）；G4 量纲闭合（p_dim = 1.0）；
• G5 新鲜度（clock_state="locked"）；G6 覆盖一致（k/alpha/quantile）；
• G7 协方差一致（Σ PD 且与 cov_group 对齐）；G8 唯一性与无环（record_id/checksum 唯一，lineage DAG 无环）。
• 触发 S1–S5（量纲/新鲜度/路径/协方差/引用）即阻断对外服务或标注 [Restricted]。

XI. 机读制品（Machine-Readable Artifacts）
A. inference_openapi.yaml：REST 合约；
B. inference.proto：gRPC 合约；
C. binding_spec.md：入/出字段、单位/量纲、覆盖模式与误差口径；
D. rollback_fsm.yaml：回退状态机；
E. validate_report.json：G1–G8 与 stops_triggered；
F. report_manifest.yaml：制品清单与签名/校验和。

XII. 反例与修正（Anti-Patterns & Fixes）

• 反例：返回 T_arr = ∫ n_eff / c_ref d ell（缺括号） → 修正：统一括号化口径并回显单位/量纲。
• 反例：路径响应未回显 delta_form → 修正：在 payload.meta 回显并与输入一致。
• 反例：覆盖模式与误差卷不一致 → 修正：统一 coverage.mode 并在图注/清单声明。
• 反例：无幂等键导致重复计费/落库 → 修正：强制 idempotency_key 并返回 409 处理冲突。

XIII. 交叉引用（Cross-References）

• 《数据集卡》：Ch.10（API/Manifest/Access）；
• 《误差预算卡》：Ch.8/Ch.9（区间与阈值）；
• 《管线卡》：Ch.11（接口与实现绑定）、Ch.12（产出与发布）；
• 本卷：Ch.4（控制式）、Ch.6（训练协议）、Ch.7（UQ）。

XIV. 执行勾选清单（Checklist）

• inference_openapi.yaml / inference.proto / binding_spec.md / rollback_fsm.yaml 就绪并版本锁定。
• 路径接口显式 gamma/measure/delta_form；I70-dim_check 通过、p_dim = 1.0。
• 覆盖/协方差口径统一；/validate 通过 G1–G8；引用锚点直指率 ≥ 90%。
• 幂等/重试/审计策略启用；导出制品具 checksum 与签名；不合规项标注 [Restricted]。