类型

公开常量、SessionOptions、以及诊断 / 元信息 / 推理结果三份 JSON。Python 把 C 的定长结构体藏进绑定，调用方只看见这些。

本绑定图像格式只有下面四个常量。头文件的 GRAY8 / RGBA8888 本绑定未导出。

图像格式

类别	属性	类型	访问	说明
格式常量	IMAGE_AUTO	int	常量	0。按字节魔数自嗅探 JPG/PNG/BMP。裸缓冲禁止用 AUTO
	IMAGE_ENCODED	int	常量	1。显式已编码字节流；当前行为同 AUTO
	IMAGE_RGB888	int	常量	2。裸 RGB 8bit，须给宽高
	IMAGE_BGR888	int	常量	3。裸 BGR 8bit，须给宽高

from darra_ai import IMAGE_AUTO, IMAGE_ENCODED, IMAGE_RGB888, IMAGE_BGR888

四个值必须与 darra_ai.h 的 darra_image_format 一致。绑定在 native 缺席时也能用这些常量做裸缓冲参数校验。未知 format 抛 InternalError（码 18）。

AUTO / ENCODED 时 width / height / stride 忽略（填 0）。RGB888 / BGR888 时 width / height 必填（>0）；stride=0 表示紧凑：width * 3。

SessionOptions

@dataclass
class SessionOptions:
    key_path: str | None = None
    password: str | None = None
    prefer_provider: str | None = None

类别	属性	类型	访问	说明
会话选项	key_path	str | None	读写	授权文件路径。构造本对象不加载 native
	password	str | None	读写	永久密码通道
	prefer_provider	str | None	读写	指名 Provider；None = 自动选。指名但不可用 = fail-closed

给 Session.open_ex 用。None = 全部可选通道为空。当前 open_ex 翻译到 open。本绑定不含头文件 darra_session_options 的 intra_op_threads / inter_op_threads / cpu_affinity_mask。

合法 prefer_provider 见 Runtime · 合法 ID。Windows 上不要指名 edge-rknn。

诊断 JSON

diagnostics.collect 输出：

{
  "schema": 1,
  "sdk": { "version": "1.0.0+runtime", "abi": 65536 },
  "os":   { "name": "windows", "version": "10.0.26100", "arch": "x64" },
  "cpu":  { "model": "AMD Ryzen 7 9800X3D", "cores": 16 },
  "gpus": [ { "model": "NVIDIA RTX 4070", "driver": "560.94", "cudaMax": "12.6" } ],
  "providers": [ { "id": "onnx-cpu", "version": "1.0.0", "path": "C:/.../Env/onnx-cpu/1.0.0" } ],
  "license": { "present": true, "mode": "trial", "trialRemaining": 12, "machineBound": false },
  "recentErrors": [ { "code": 11, "message": "...", "when": "2026-09-01T10:00:00+08:00" } ]
}

• schema 恒存在；其余字段采不到时为 null 或缺席，消费方必须容忍。
• 去敏：永不出现密钥 / 密码 / token / 机器指纹原始字节；license 只有状态摘要。
• gpus 无独显时为 []；providers 未装任何包时为 []。

会话元信息 JSON

Session.meta() 输出：

{
  "schema": 1,
  "task": "detect",
  "labels": ["scratch", "dent"],
  "input": { "width": 640, "height": 640, "channels": 3 },
  "payloadKind": "onnx",
  "provider": "onnx-cuda",
  "encrypted": true,
  "containerFormat": "DARM1",
  "license": { "mode": "trial", "trialRemaining": 12, "machineBound": true }
}

• task 派生短名随容器头；推理结果 results 元素结构以此为准。缺席不编 detect。头文件对结果形态的承诺：detect→box，classify→top-k，segment→掩码。
• payloadKind：onnx / trt-engine / openvino / rknn / paddle。Paddle 是运行时载荷。rknn 只在 linux-arm64；Windows 打开即 UnsupportedPayloadError。
• input.width / height / channels 来自容器头。缺则 null，不编 640/80/17。
• provider 是实际选中的 Provider（不是 prefer 入参）。
• encrypted=false 时无 containerFormat / license（明文会话）。
• 标准字段表见 元数据。

只读属性映射：

属性	JSON 路径
task	task
labels	labels
input_width	input.width
input_height	input.height
channels	input.channels
layout	input.layout，否则顶层 layout
payload_kind	payloadKind
provider_id	provider
encrypted	encrypted

推理结果 JSON

infer_image 输出。每次调用一张图（一帧）。

{
  "schema": 1,
  "task": "detect",
  "provider": "onnx-cuda",
  "elapsedMs": 3.2,
  "image": { "width": 1920, "height": 1080 },
  "results": [ { "label": "scratch", "score": 0.93, "box": [120, 40, 36, 18] } ]
}

• envelope 字段（schema / task / provider / elapsedMs / image / results）恒定；results 元素随 task 而变：
  • detect：{label, score, box:[x,y,w,h]}
  • classify：{label, score} top-k 按分降序
  • segment：{label, score, maskRle}
  • 其余 task 的逐元素 schema 随对应 Provider 落地，本契约只承诺 envelope
• 结果坐标基于 image 字段（解码后、送入模型前的尺寸）；裸缓冲输入时等于传入的宽高。
• 永不包含模型明文、密钥等任何敏感字节。