44-EFT.WP.Data.ModelCards v1.0 | 第16章 实现绑定与验证 API

目录 ／ 文档-技术白皮书 ／ 44-EFT.WP.Data.ModelCards v1.0

第16章 实现绑定与验证 API

I. 章节目的与范围

II. 服务面（规范性）

services:

modelcards.v1:

# 元数据与结构校验

- POST /api/v1/validate_model_card

- POST /api/v1/lint_model_card

- POST /api/v1/check_units

- POST /api/v1/verify_references

- POST /api/v1/split_freeze_check

- POST /api/v1/leakage_audit

# 评测/校准/稳健/公平

- POST /api/v1/eval_run

- POST /api/v1/eval_significance

- POST /api/v1/calibration_eval

- POST /api/v1/robustness_eval

- POST /api/v1/fairness_eval

# 模型侧绑定（可选）

- POST /api/v1/score

- POST /api/v1/calibrate

- POST /api/v1/explain

# 工件与发布

- POST /api/v1/hash_artifact

- POST /api/v1/sign_artifact

- POST /api/v1/publish_release

- POST /api/v1/revoke_release

III. 通用请求/响应与鉴权

request_envelope:

headers:

Authorization: "Bearer <oidc-token> | HMAC <key>:<sig>"

x-eift-idempotency: "<uuid>" # 幂等键（≥24h 有效）

content-type: "application/json"

body:

card: { ... } # model_card 对象（YAML/JSON）

artifacts?: [{path, bytes_b64?, sha256?}]

options?: {dry_run?: true, strict?: true}

response_envelope:

status: "ok" | "warn" | "error"

errors: [{code, message, path?, see?}]

warnings:[{code, message, path?, see?}]

metrics: { ... } # 校验/评测统计

version: "modelcards.v1"

security:

auth: "OIDC bearer | HMAC"

tls: "TLS1.2+"

scope: ["validate","evaluate","publish","admin"]

rate_limits:

per_key_per_minute: 120

burst: 60

IV. 规范性 OpenAPI 摘录

openapi: 3.0.3

info: {title: "EFT ModelCards API", version: "v1"}

paths:

/api/v1/validate_model_card:

post:

summary: Validate Model Card against schema & cross-volume constraints

requestBody:

required: true

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

responses:

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

/api/v1/check_units:

post:

summary: Dimensional/unit consistency check (Metrology v1.0)

responses: {"200": {content: {"application/json": {schema: {$ref: "#/components/schemas/Result"}}}}}

/api/v1/score:

post:

summary: Bind model scoring I/O with io_schema (Chapter 6)

responses: {"200": {content: {"application/json": {schema: {$ref: "#/components/schemas/ScoreResult"}}}}}

components:

schemas:

CardEnvelope: {type: object, required: [card], properties: {card: {}}}

Result:

type: object

properties:

status: {type: string, enum: [ok, warn, error]}

errors: {type: array, items: {$ref: "#/components/schemas/Issue"}}

warnings:{type: array,items: {$ref: "#/components/schemas/Issue"}}

metrics: {type: object}

ScoreResult:

type: object

properties: {outputs: {type: object}, latency_ms: {type: number}}

Issue:

type: object

properties:

code: {type: string}

message: {type: string}

path: {type: string}

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

V. 端点语义（要点）

• /validate_model_card（阻断）——结构必填、类型/正则、export_manifest.references[] 格式、计量最小集、冻结切分标志；失败返回 status="error"。
• /lint_model_card——执行第15章规则：比例/泄漏、防冲突符号、数学禁中文、软最大区间等。
• /check_units——units="SI"、check_dim=true、向量/张量单位一致性。
• /verify_references——校验 "^[^:]+ v\\d+\\.\\d+:[A-Z].+$" 与锚点可达性（目录服务/索引）。
• /split_freeze_check——splits 求和=1±1e-6、索引冻结、与 training_data.splits_ref 一致。
• /leakage_audit——对象/时间窗/场景去重；跨 split 泄漏阻断。
• /eval_run & /eval_significance——按第11章协议运行评测并返回区间与显著性（置换/自助）。
• /calibration_eval——返回 ECE/Brier/曲线 与覆盖；与第12章一致。
• /robustness_eval / /fairness_eval——运行偏移/对抗/公平性条目并对照阈值。
• /score / /calibrate / /explain——与第6章 io_schema 与第7章架构保持 I/O 对齐；/explain 可返回热力图/重要性。
• /hash_artifact / /sign_artifact——计算 sha256 与签名/验签；与导出清单对表。
• /publish_release / /revoke_release——遵循第14章版本化与撤回墓碑。

VI. 错误码（规范性）

errors:

- {code:"ESCHEMA001", message:"missing required field", path:"$.title"}

- {code:"EREF001", message:"invalid reference format", path:"$.export_manifest.references[2]"}

- {code:"EMETR001", message:"units must be SI and check_dim=true", path:"$.metrology"}

- {code:"ESPLIT001", message:"ratios must sum to 1±1e-6", path:"$.evaluation.protocol"}

- {code:"ELEAK000", message:"cross-split leakage detected", path:"$.training_data.leakage_guards"}

- {code:"EIO001", message:"io_schema mismatch with deployment I/O", path:"$.io_schema"}

- {code:"EFAIR010", message:"fairness gap exceeds threshold", path:"$.fairness"}

- {code:"EROB010", message:"robustness drop exceeds threshold", path:"$.robustness"}

- {code:"ESIGN001", message:"artifact signature mismatch", path:"$.export_manifest.artifacts[0]"}

VII. 幂等性、版本协商与兼容性

idempotency:

header: "x-eift-idempotency"

window_hours: 24

versioning:

api: "modelcards.v1" # 破坏性变更 → 提升 MAJOR

minor: "向后兼容新增"

compatibility:

request_backward: "minor+patch"

response_fields: "新增仅追加，不移除"

VIII. 安全、审计与合规

• 鉴权：OIDC/HMAC；传输：TLS1.2+；最小权限：按 scope 发放。
• 审计：记录 request_id、idempotency_key、调用者、时间戳、摘要；日志纳入合规工件与导出清单。
• 合规：区域限制与数据主体权利对接第14章；撤回/更正对接发布策略。

IX. 机器可读实现片段（参考 Ixx-?）

def validate_model_card(card: dict) -> dict: ...

def lint_model_card(card: dict, rules: dict) -> dict: ...

def check_units(card: dict) -> dict: ...

def verify_references(card: dict) -> dict: ...

def split_freeze_check(card: dict) -> dict: ...

def leakage_audit(card: dict) -> dict: ...

def eval_run(card: dict, seeds: list[int], repeats: int) -> dict: ...

def eval_significance(baseline: dict, contender: dict) -> dict: ...

def calibration_eval(card: dict) -> dict: ...

def robustness_eval(card: dict) -> dict: ...

def fairness_eval(card: dict) -> dict: ...

def score(inputs: dict) -> dict: ...

def calibrate(probs: list[float], method: str="temperature") -> dict: ...

def explain(inputs: dict, method: str="grad") -> dict: ...

def hash_artifact(path: str|bytes) -> dict: ...

def sign_artifact(path: str|bytes, key_id: str) -> dict: ...

def publish_release(card: dict, channel="stable") -> dict: ...

def revoke_release(tag: str, reason: str) -> dict: ...

X. 示例调用（可直接使用）

# 结构与跨卷校验

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

-H "Authorization: Bearer <token>" \

-H "x-eift-idempotency: 7b7a0b1e-0a21-4f3f-9d0b-3b1e9b1f3c22" \

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

-d '{"card": { "model_id":"eift.vision.cls.resnet50", "version":"v1.0",

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

"evaluation":{"protocol":{"splits":"frozen"},"metrics":{}},

"export_manifest":{"version":"v1.0","artifacts":[],

"references":["EFT.WP.Core.DataSpec v1.0:EXPORT",

"EFT.WP.Core.Metrology v1.0:check_dim"]}}}'

XI. 与导出清单的耦合（规范性）

export_manifest:

artifacts:

- {path:"api/openapi.yaml", sha256:"..."}

- {path:"api/clients/python.tar.gz", sha256:"..."}

references:

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

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

XII. 本章合规自检

• 阻断接口（validate_model_card、check_units、verify_references、split_freeze_check、leakage_audit）已实现并启用鉴权/幂等/速率限制。
• 引用锚点采用“卷名 vX.Y:锚点”，并在 export_manifest.references[] 中体现；无短码与无版本引用。
• 计量校核生效（units="SI", check_dim=true）；io_schema 与部署端点一致；评测/校准/鲁棒/公平端点按各章口径运行。
• 发布/撤回遵循第14章；OpenAPI/SDK 工件已列入导出清单并可校验。