诊断（Diagnostics）

只读纯查询接口：不联网、不安装环境、不触发模型调度。

信息

排查模型打开失败时，先读这组能力位看缺哪个运行时包；SDK 不负责下载或代装运行时包。

属性表 — darra_diag 结构与 getter

类别	属性	类型	读写	说明
结构	size	uint32_t	只写	调用方必填，填 sizeof(darra_diag)
总览	supported	int32_t	只读	用 getter darra_diag_supported 读取。默认 0。值为 1 表示推荐运行时包已经装好
总览	version	char[32]	只读	用 getter darra_diag_version 读取。默认是空字符串。未安装或没有推荐版本时也是空字符串；getter 返借用指针，不要 free
能力	has_onnx_cpu	int32_t	只读	用 getter darra_diag_has_onnx_cpu 读取。默认 0。值为 1 表示细包已装好且对应硬件在场
能力	has_onnx_cuda	int32_t	只读	用 getter darra_diag_has_onnx_cuda 读取。默认 0。值为 1 表示细包已装好且对应硬件在场
能力	has_onnx_openvino	int32_t	只读	用 getter darra_diag_has_onnx_openvino 读取。默认 0。值为 1 表示细包已装好且对应硬件在场
能力	has_onnx_trt_ep	int32_t	只读	用 getter darra_diag_has_onnx_trt_ep 读取。默认 0。值为 1 表示细包已装好且对应硬件在场
能力	has_onnx_directml	int32_t	只读	用 getter darra_diag_has_onnx_directml 读取。默认 0。值为 1 表示细包已装好且对应硬件在场
能力	has_trt_native	int32_t	只读	用 getter darra_diag_has_trt_native 读取。默认 0。值为 1 表示细包已装好且对应硬件在场
能力	has_paddle_cpu	int32_t	只读	用 getter darra_diag_has_paddle_cpu 读取。默认 0。值为 1 表示细包已装好且对应硬件在场
能力	has_paddle_gpu	int32_t	只读	用 getter darra_diag_has_paddle_gpu 读取。默认 0。值为 1 表示细包已装好、对应硬件在场且实测可加载
能力	has_edge_rknn	int32_t	只读	用 getter darra_diag_has_edge_rknn 读取。默认 0。值为 1 表示细包已装好且对应硬件在场
能力	has_torchscript	int32_t	只读	用 getter darra_diag_has_torchscript 读取。默认 0。值为 1 表示细包已装好且对应硬件在场

类型定义

typedef struct darra_diag {
    uint32_t size;        /* 调用方填 sizeof(darra_diag) */
    int32_t  supported;   /* 1 = 推荐运行时包已装好 */
    char     version[32]; /* 推荐运行时包版本；未装 / 无推荐 = 空串 */
    int32_t  has_onnx_cpu, has_onnx_cuda, has_onnx_openvino, has_onnx_trt_ep,
             has_onnx_directml, has_trt_native, has_paddle_cpu, has_paddle_gpu,
             has_edge_rknn, has_torchscript;
} darra_diag;

快照采集

darra_diag_fill()

DARRA_API int32_t darra_diag_fill(darra_diag* out);

一次调用把整份诊断快照填满，之后再用各个 getter 逐字段去读。out 是调用方自己准备的快照结构体，调用前必须先把 size 字段填成 sizeof(darra_diag)。

示例：

darra_diag d;
d.size = (uint32_t)sizeof(d);
if (darra_diag_fill(&d) != 0) {
    puts("诊断快照采集失败");
}

darra_model_runtime_diag()

DARRA_API int32_t darra_model_runtime_diag(const darra_model* h, darra_diag* out);

运行期诊断：把模型句柄的运行状态填进一个已经准备好的 darra_diag 快照里。h 是模型句柄，out 是调用方快照（先填 size）。

示例：

darra_diag d;
d.size = sizeof(darra_diag);
darra_model_runtime_diag(h, &d);

Provider 权威表

权威表 DARRA_PROVIDER_ID_COUNT = 18。

类别	属性	类型	读写	说明
推理执行体	id	string	只读	onnx-cpu、onnx-cuda、onnx-openvino、onnx-trt-ep、onnx-directml、trt-native、paddle-cpu、paddle-gpu、edge-rknn、tflite、onnx-tflite、torchscript-cpu
依赖资源包	id	string	只读	cudnn、cuda-libs
工具链包	id	string	只读	torch、ultralytics、openvino-intel-gpu、openvino-intel-npu

darra_provider_id_at()

DARRA_API const char* darra_provider_id_at(size_t index);

按下标遍历权威表取 id 字符串，下标范围 0 到 DARRA_PROVIDER_ID_COUNT-1。下标越界返回 NULL，这不算错误码。

示例：

for (size_t i = 0; i < DARRA_PROVIDER_ID_COUNT; ++i) {
    printf("provider id: %s\n", darra_provider_id_at(i));
}

darra_provider_id_is_valid()

DARRA_API int32_t darra_provider_id_is_valid(const char* provider_id);

传入一个 id 字符串，返回 1 表示合法，返回 0 表示不合法。传入 NULL 返回 0，这不算错误码。

示例：

if (!darra_provider_id_is_valid("onnx-cpu")) {
    puts("id 不在权威表里");
}

darra_provider_runtime_version()

DARRA_API int32_t darra_provider_runtime_version(const char* provider_id, char** out_json);

查指定 Provider 的运行时版本，版本 JSON 通过出参 out_json 返回（provider / packVersion / runtimeVersion，没有结构体出参）。

示例：

char* json = NULL;
if (darra_provider_runtime_version("onnx-cpu", &json) == DARRA_OK) {
    puts(json);
    darra_string_free(json);
}

darra_env_list()

DARRA_API int32_t darra_env_list(char** out_json);

一次性返回完整的环境清单，清单包括 providers 表和当前推荐的运行时包。

示例：

char* json = NULL;
if (darra_env_list(&json) == DARRA_OK) {
    puts(json);
    darra_string_free(json);
}

darra_env_supported()

DARRA_API int32_t darra_env_supported(void);

环境是否可用：推荐的运行时包已经装好返回 1，否则返回 0。

示例：

if (!darra_env_supported()) { puts("推荐运行时包未装好"); }

darra_env_version()

DARRA_API int32_t darra_env_version(char** out_ver);

查询推荐运行时包的已安装包版本，也就是安装时记录的 packVersion。返回 int32_t 状态码，版本字符串通过出参 out_ver 返回，用完要调用 darra_string_free 释放。

示例：

char* ver = NULL;
if (darra_env_version(&ver) == DARRA_OK) {
    printf("packVersion=%s\n", ver);   /* 空串 = 未装 / 无推荐 */
    darra_string_free(ver);
}

darra_provider_supported()

DARRA_API int32_t darra_provider_supported(const char* provider_id);

查询指定的 Provider 是否已经装好并且对应硬件在场：是返回 1，否返回 0。id 不合法、包没装、硬件缺失三种情况都返回 0。

示例：

if (!darra_provider_supported("onnx-cuda")) { puts("onnx-cuda 不可用"); }

高级 JSON 入口

darra_diag_collect()

int32_t darra_diag_collect(char** out_json);

采集本机的环境诊断信息，输出一份统一格式的 JSON。schema 字段永远存在，其他字段如果采集不到就会是 null 或者干脆缺席，使用方必须能容忍这些情况。

参数：

• out_json (char**) — SDK 分配的 UTF-8 JSON，用完 darra_string_free

示例：

char* diag = NULL;
if (darra_diag_collect(&diag) == DARRA_OK) {
    puts(diag);
    darra_string_free(diag);
}

整机诊断的 JSON 已做去敏处理。

{
  "schema": 1,
  "sdk": { "version": "1.0.0+runtime", "abi": 65536 },
  "os":   { "name": "windows", "version": "10.0.26100", "arch": "x64" },
  "cpu":  { "model": "...", "cores": 0 },
  "gpus": [ { "model": "...", "driver": "...", "cudaMax": "..." } ],
  "providers": [ { "id": "onnx-cpu", "version": "1.0.0", "path": "..." } ],
  "license": null,
  "recentErrors": [ { "code": 11, "message": "...", "when": "..." } ]
}

/* 字段表： */
/* schema 整数：恒存在，当前 1；消费方据此识别结构版本 */
/* sdk.version 字符串：SDK 版本串 / sdk.abi 整数：打包值 65536=v1.0.0 */
/* os.name 字符串：系统名，采不到 null */
/* os.version 字符串：系统版本，采不到 null */
/* os.arch 字符串：架构，采不到 null */
/* cpu.model 字符串：型号，采不到 null */
/* cpu.cores 整数：核数，采不到 0 */
/* gpus 数组：元素 model / driver / cudaMax；无独显 []，采不到 null */
/* providers 数组：元素 id / version / path；未装包 []，采不到 null */
/* license 对象：本版恒 null（未采集，不代表没有密码） */
/* recentErrors 数组：最近错误环形缓冲；元素 code / message / when；无错误 [] */

完整示例

#include "darra_model.h"
#include <stdio.h>

int main(void) {
    darra_diag d;
    d.size = (uint32_t)sizeof(d);
    if (darra_diag_fill(&d) != 0) {
        return 1;
    }
    printf("supported=%d version=%s\n",
           darra_diag_supported(&d), darra_diag_version(&d));
    printf("cpu=%d cuda=%d dml=%d ovp=%d\n",
           darra_diag_has_onnx_cpu(&d), darra_diag_has_onnx_cuda(&d),
           darra_diag_has_onnx_directml(&d), darra_diag_has_onnx_openvino(&d));
    printf("trt_ep=%d trt=%d paddle_cpu=%d paddle_gpu=%d\n",
           darra_diag_has_onnx_trt_ep(&d), darra_diag_has_trt_native(&d),
           darra_diag_has_paddle_cpu(&d), darra_diag_has_paddle_gpu(&d));
    printf("rknn=%d torchscript=%d\n",
           darra_diag_has_edge_rknn(&d), darra_diag_has_torchscript(&d));
    return 0;
}