跳到主要内容

创建实例

方法​

darra_model_create()​

DARRA_API int32_t darra_model_create(const char* model_path,
                                     const darra_model_config* cfg_or_null,
                                     darra_model** out);

创建句柄，记下模型路径和配置并加载元信息。

参数：

  • model_path (const char*) — 模型文件路径
  • cfg_or_null (const darra_model_config*) — 配置。传 NULL 表示全部用默认值
  • out (darra_model**) — 成功时写入句柄。失败时置为 NULL

示例：

darra_model_config cfg = {0};   /* 零初始化：全部 0/NULL 就是用默认值 */
darra_model* m = NULL;
if (darra_model_create("model.darmodel", &cfg, &m) != 0) {
    /* create 失败时没有句柄，直接结束 */
    return -1;
}

darra_model_open()​

DARRA_API int darra_model_open(darra_model* h, const char* password_or_null);

打开模型，把模型真正加载进来，在 create 之后、infer 之前调用。返回 1 表示成功、0 表示失败，失败详情用 darra_model_last_error 查。

参数：

  • h (darra_model*) — create 得到的句柄
  • password_or_null (const char*) — 密码。传 NULL 或空字符串表示不用密码

示例：

if (!darra_model_open(m, "密码")) {
    printf("open failed: %s\n", darra_model_last_error(m));
    darra_model_close(m);   /* 打开失败，直接释放句柄收场 */
}

darra_model_close()​

DARRA_API int32_t darra_model_close(darra_model* m);

关闭模型并释放句柄。传 NULL 不会崩溃，重复调用也安全。

参数：

  • m (darra_model*) — 句柄。传 NULL 不会崩溃

示例：

darra_model_close(m);
m = NULL;   /* 句柄已释放，置 NULL 防止误用 */

darra_model_cancel()​

DARRA_API int32_t darra_model_cancel(darra_model* m);

尝试取消正在执行的推理。池模式（workers>1）没有逐个取消，这时取消调用会失败。

参数：

  • m (darra_model*) — 已 open 的句柄

示例：

int32_t rc = darra_model_cancel(m);   /* 尝试打断当前推理 */

装入类别名​

结果条目缺 label 字段时，按 class_id 从类别名表取名字来显示。

darra_model_set_labels()​

DARRA_API int32_t darra_model_set_labels(darra_model* h,
                                         const char* const* labels,
                                         size_t count);

往句柄里注入一张类别名表，随时可调，open 后生效。

参数：

  • h (darra_model*) — 模型句柄
  • labels (const char* const*) — UTF-8 非空字符串数组
  • count (size_t) — 传 0 表示清空

示例：

const char* labels[2] = { "OK", "NG" };
int32_t rc = darra_model_set_labels(h, labels, 2);

darra_model_clear_labels()​

DARRA_API int32_t darra_model_clear_labels(darra_model* h);

清空注入的类别名表，回到模型自带的类别名。随时可调，open 后生效。

示例：

int32_t rc = darra_model_clear_labels(h);

加密模型的密码​

加密模型在 open 时把口令凭据传进去。

加载结果​

结果判据含义
试用trial = 1按试用条款使用，有次数或期限限制
绑定machine_binding = NONE首次凭据校验通过后绑定到本机，绑定完就能用
已绑定machine_binding = HERE这台机器已经绑定过，直接用
未通过error_code 非 0会明确报错，不会静默失败

试用剩余次数用 trial_remaining 读取。绑定完成后再次打开时 password_or_null 传 NULL 就行。

示例：

darra_unlock_info ui = {0}; ui.size = sizeof(ui);
darra_unlock_get_info("model.darmodel", &ui);
if (ui.state == DARRA_UNLOCK_READY)            /* 已绑定 */
    darra_session_open_ex("model.darmodel", NULL, NULL, NULL, NULL, &h);
else {
    /* password_or_null = 口令凭据；绑定和试用状态由 SDK 内部判定 */
    rc = darra_session_open_ex("model.darmodel", NULL, code, NULL, NULL, &h);
}

推理与释放​

推理结果的 JSON 是在堆上分配的字符串：

char* json = NULL;
int32_t rc = darra_model_infer_file(h, "a.jpg", &json);
if (rc == 0) { printf("%s\n", json); darra_string_free(json); }
darra_model_close(h);            /* 会话用 darra_session_close(s) */
  • SDK 返回的堆上字符串一律用 darra_string_free 释放。禁止用 free / delete[]。调用方自己 malloc 的自己 free。
  • darra_model_close / darra_session_close 之后句柄就失效了。传 NULL 关闭不会崩。要等正在执行的推理结束再关。