模型元数据（header_json）

DARM1 容器头里的标准元数据。导出格式即加载格式：AI Studio 写出的 header_json，运行时原样读。加载方零配置——不存在「打开后再喂宽高 / 类别 / 均值」。

契约与 darra_ai.h §6 一致；语义冲突以头文件注释为准。运行时 API darra_session_meta_json 的 camelCase JSON 是本头的派生视图，不是第二份真相。见 C SDK。

公开 SDK 是 runtime 构建：读头、解密已签发容器、推理。不写、不加密、不签发。 header_json 由 AI Studio authoring 写出。

RKNN（PayloadKind=rknn）只在 linux-arm64 的 edge-rknn 上跑。Windows / linux-x64 收到 = DARRA_UNSUPPORTED_PAYLOAD。

相关：错误码 · 运行时清单

铁律

1. 导出格式即加载格式。 Studio 写出的头，运行时原样读。
2. 缺字段不编默认。 禁止把缺失字段填成 640 / 80 / 17（或 ImageNet mean/std、NCHW、3 通道等「常见值」）。没有就是没有——JSON 里字段缺席或 null；派生视图同样缺席 / null。
3. PascalCase 属性名。 生成侧与 System.Text.Json 默认序列化一致（Version / Task / Labels / PayloadKind / OnnxMeta …）。解析侧大小写不敏感，但新写出必须 PascalCase。
4. 多余字段忽略，不报错。 旧容器多 ChunkScheme / InputSize 等，新加载器照认；新字段旧加载器跳过。
5. UTF-8 无 BOM，一个 JSON 对象，无注释。

推理标准字段

写出端（Studio 导出）能探测到就写；探测不到就缺席，禁止编造。

字段	JSON 类型	必填	说明
Version	number（int）	是	容器头格式版本。当前 1。
Task	string	建议	detection / classification / segmentation / pose / obb / ocr / anomaly。缺席不编 detection。不要写成派生视图的短名 detect。
Labels	string[]	建议	类别名，声明序即 id 序（下标 0 = 第 0 类）。缺席或 [] 合法；禁止编 80 类 COCO 名。
InputWidth	number（int）	建议	模型输入宽（px）。
InputHeight	number（int）	建议	模型输入高（px）。
InputChannels	number（int）	建议	模型输入通道数（1 / 3 / 4 常见）。缺席不编 3。
Layout	string	建议	仅 NCHW 或 NHWC。缺席不编 NCHW。
Mean	number[]	可选	逐通道均值，长度应 = InputChannels（若通道数已知）。缺席不编 ImageNet 0.485/0.456/0.406，也不写 0/0/0 占位。
Std	number[]	可选	逐通道标准差。缺席不编 ImageNet 0.229/0.224/0.225，也不写 1/1/1 占位。
PayloadKind	string	是	见下表。
OnnxMeta	object	可选	图结构键值，值均为字符串。契约不规定必有键；缺席或 {} 合法。

Version + PayloadKind 是加载分发的最小集；其余按「有则用、无则不编」。

PayloadKind

值	含义	明文 open_plain / open_plain_ex	运行时
onnx	ONNX 图	.onnx 文件	onnx-* Provider
trt-engine	TensorRT engine	不走 plain（进 DARM1）	trt-native
openvino	OpenVINO IR	随 Provider	onnx-openvino
rknn	RKNN	不走 Windows / linux-x64 plain	仅 edge-rknn（linux-arm64）；其它平台 = DARRA_UNSUPPORTED_PAYLOAD
paddle	Paddle 推理载荷	.pdmodel（同目录须有 .pdiparams），或含二者的目录	paddle-cpu；指名不可用 fail-closed

PayloadKind=paddle 是运行时载荷。目录存在但缺 pdmodel 或 pdiparams、或 .pdmodel 缺伴生 .pdiparams → DARRA_UNSUPPORTED_PAYLOAD。路径不存在 → DARRA_IO_NOT_FOUND。

仍拒（不是运行时载荷）：.pt / .pth（PyTorch 训练格式）→ DARRA_UNSUPPORTED_PAYLOAD，先在 AI Studio 转 ONNX（或转成上表某一种）。

细包 ID 以 运行时清单 为准；本表钉的是载荷种类，不在此另造 Provider 名。

兼容字段

加载器必须能解析；不得因出现这些字段而失败。新推理不依赖它们。

字段	说明
InputSize	旧方形边长别名。仅当 InputWidth / InputHeight 都缺席且本字段存在时，当作宽 = 高 = InputSize。禁止在本字段也缺席时编 640。新导出器应写 InputWidth / InputHeight；方形模型可同时写 InputSize 以便旧读侧。
ChunkScheme	容器分块方案，当前唯一 fixed。内务字段，推理不读。
ChunkSize	非末块明文字节数。内务字段。生产默认常 1 MiB。
ChunkCount	分块数。内务字段。

兼容形态示例（逐字节无空格；不是要新导出器复制 InputSize=640）：

{"Version":1,"Task":"detection","InputSize":640,"Labels":["a","b","c"],"ChunkScheme":"fixed","ChunkSize":1024,"ChunkCount":3,"OnnxMeta":{"opset":"17","note":"tv-only"},"PayloadKind":"onnx"}

新导出完整例（人读缩进；生成侧落盘无空格。Mean/Std 仅在模型真实有值时写，不知道就整段省略）：

{
  "Version": 1,
  "Task": "detection",
  "Labels": ["scratch", "dent"],
  "InputWidth": 640,
  "InputHeight": 640,
  "InputChannels": 3,
  "Layout": "NCHW",
  "PayloadKind": "onnx",
  "OnnxMeta": {"opset": "17"},
  "ChunkScheme": "fixed",
  "ChunkSize": 1048576,
  "ChunkCount": 4
}

加载方行为

• darra_session_open* 读（加密容器则先解密）header 后缓存本对象；darra_session_meta_json 从缓存派生，微秒级。
• 推理预处理（缩放目标、通道、Layout、归一化）只读本对象。某字段缺席 = 该步按「无元数据」处理（例如无 Mean/Std 则不做减均值除方差），不是回退到 640/80/17。
• 调用方零配置：不要在 darra_session_options 或其它 ABI 再传一遍宽高 / 类别。
• 明文 open_plain* 无容器头时：从文件 / ONNX 图 / Paddle 目录能探测到的字段写入会话缓存；探测不到的同样缺席，不编默认。
• 公开 SDK 不能把明文再打成 DARM1；那是 AI Studio authoring 的事。

与 session_meta_json 的关系

	header_json（本页）	session_meta_json
位置	DARM1 容器头（加密容器里头也加密；公开 SDK 只读）	运行时 API 出参
键名	PascalCase	camelCase
Task	detection …（长名）	detect …（短名，派生）
输入尺寸	InputWidth / InputHeight / InputChannels（+ 旧 InputSize）	input:{width,height,channels}，缺则 null
额外	Chunk*、OnnxMeta、Mean、Std、Layout	provider / encrypted / license（运行时态，不进容器头）

短名映射（仅派生视图，不写回容器）：detection→detect，classification→classify，segmentation→segment；其余同形（pose / ocr / anomaly / obb）。无法映射时派生视图 task 为 null，不编 detect。