52-数据集卡 Template v1.0 | 第10章 接口、清单与访问（API/Manifest/Access）

目录 ／ 文档-技术白皮书 ／ 52-数据集卡 Template v1.0

第10章 接口、清单与访问（API/Manifest/Access）

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

• 规范数据集的访问接口（API）、发布清单（Manifest）与访问控制（Access），覆盖 REST/gRPC/CLI 约定、鉴权与幂等、速率与配额、校验和与签名、/validate 报告链接与合规放行。
• 凡涉及路径量（到达时/相位），正文显式 gamma(ell) 与测度 d ell，数据侧记录 delta_form ∈ {general, factored}；发布要求 p_dim = 1.0 并随附 check_dim_report.json。

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

• 结构与契约：schema.json/contract.yaml 与第4章一致并通过 I70-dim_check。
• 来源与血缘：provenance.yaml/lineage_graph.json 完整（第3章）。
• Splits/Versioning/Freshness：split.yaml/split_manifest.json 完整（第6章），过期样本隔离。
• 质量门：/validate 通过 G1–G8（第7章），引用采用“卷名 + 版本 + 锚点（P/S/M/I）”，锚点直指率 ≥ 90%。

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

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

{

"status":"OK|ERROR",

"code":0,

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

"payload":{},

"metrics":{"latency_ms":123,"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: "Dataset API", version: "1.0.0" }

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

components:

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

schemas:

GetRequest:

type: object

properties:

dataset_id: { type: string }

split: { type: string, enum: ["train","val","test","holdout"] }

filter: { type: object }

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

GetResponse:

type: object

properties:

status: { type: string }

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

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

version: { type: string }

checksum: { type: string }

paths:

/datasets/{id}/info:

get:

security: [{ bearerAuth: [] }]

summary: "Get dataset manifest info"

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

responses:

"200": { description: "OK" }

/datasets/{id}/get:

post:

security: [{ bearerAuth: [] }]

summary: "Idempotent read of records"

requestBody:

required: true

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

responses:

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

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

/datasets/{id}/validate:

post:

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

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

V. gRPC（proto 节选）

syntax = "proto3";

package dataset.v1;

message GetRequest {

string dataset_id = 1;

string split = 2; // train|val|test|holdout

repeated string fields = 3;

bytes filter = 4; // JSON

}

message GetResponse {

string status = 1;

bytes payload = 2; // Parquet/JSON

repeated string anchors = 3;

string version = 4;

string checksum = 5;

}

service DatasetService {

rpc Info(GetRequest) returns (GetResponse);

rpc Get (GetRequest) returns (GetResponse);

rpc Validate (GetRequest) returns (GetResponse);

}

VI. CLI（节选）

# 清单

ds info ds-core --out reports/manifest_view.json

# 幂等读取

ds get ds-core --split test --fields obs.T_arr,obs.Phi --filter @filters.json \

--idempotency_key run42+p010+win001 --out data/test_subset.parquet

# 门校验

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

VII. 幂等、速率与审计（Idempotency, Rate, Audit）

• 幂等键：idempotency_key = f(dataset_id, split, window, partition, …)；同键多次读取输出不变。
• 速率与配额：rate_limit{ rps, burst } 与 quota{ daily_export_mb }；超限返回 429。
• 审计：所有导出与写入操作在 audit.jsonl 记录时间、操作者、输入哈希、字节数、签名与 checksum。

VIII. Manifest 规范（report_manifest.yaml）

version: "1.0.0"

dataset_id: "ds-core"

schema: "schemas/dataset/schema.json"

contract: "contracts/contract.yaml"

splits: "splits/split_manifest.json"

reports:

- "reports/check_dim_report.json"

- "reports/validate_report.json"

- "reports/audit.jsonl"

figs:

- "figs/scale_dist.pdf"

- "figs/path_profile.pdf"

checksums:

schema: "sha256:..."

contract: "sha256:..."

splits: "sha256:..."

sign: "SIGNATURE.asc"

see:

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

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

IX. 访问控制与安全（Access Control & Security）

• 鉴权：Bearer 或 mTLS；最小权限 RBAC：reader|publisher|admin。
• 数据保护：敏感字段加密/脱敏；导出文件强制校验和与签名。
• 日志最小化：禁止在日志中落敏感原文，仅保留哈希与必要元信息。

X. 路径量接口规范（Path-Specific）

• 必备字段：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。

XI. 质量门映射（Gates Mapping）

• G1 Schema 完整：schema/contract/splits 与 Manifest 一致；
• G2 引用合规：锚点直指率 ≥ 90%；
• G3 路径规范：路径块齐备与步长合规；
• G4 量纲闭合：check_dim_report.json 通过；
• G5 新鲜度：clock_state="locked"；
• G6 覆盖口径一致：coverage.mode ∈ {k, alpha, quantile}；
• G7 协方差一致：cov_group/Σ 与误差卷一致且 PD；
• G8 唯一性：record_id/checksum 不重复；lineage 无环。
• 触发 S1–S5 即拒收或标注 [Restricted] 并阻断外部下载。

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

• 反例：返回 T_arr = ∫ n_eff / c_ref d ell（缺括号）→ 修正：统一括号化口径。
• 反例：Manifest 缺 checksums/signature → 修正：生成并随发布提供。
• 反例：路径响应未回显 delta_form → 修正：在 payload.meta 补充。
• 反例：速率/配额缺省导致滥用 → 修正：设置 rate_limit/quota 并告警。

XIII. 交叉引用（Cross-References）

• 结构与 Schema：见第4章；Splits/Versioning/Freshness：见第6章；质量门：见第7章；不确定度与协方差：见第8章。
• 与《管线卡》：接口与实现绑定（Ch.11）、产出与发布（Ch.12）。
• 与《误差预算卡》：区间与阈值映射（Ch.8/Ch.9）。

XIV. 执行勾选清单（Checklist）

• OpenAPI/gRPC/CLI 三端规范一致；RBAC 与最小权限生效。
• Manifest 含 checksums/signature、/validate 链接与锚点；与 schema/contract/splits 对齐。
• 路径接口显式 gamma/measure/delta_form，并在响应中回显；I70-dim_check 通过。
• 速率/配额与审计策略开启；导出校验和与签名完整。
• /validate 通过 G1–G8；必要时标注 [Restricted]；引用合规（锚点直指率 ≥ 90%）。