运行时包

确保指定 Provider / profile 已装好。没装就探测 → 选包 → 下载 → sha256 校验 → 解压登记。函数仍是 C ABI。

Windows 上指名 edge-rknn 返回 DARRA_UNSUPPORTED_PLATFORM。edge-rknn 永远不会出现在 Windows 安装列表。SDK 不自动安装 / 升级系统驱动。

进度回调类型见 类型。

功能概览

类别	属性	类型	访问	说明
运行时包	darra_runtime_ensure	int32_t	过程	确保 Provider / profile 已装；幂等、事务性
	darra_runtime_ensure_cancel	void	过程	取消在飞的 ensure；无在飞则为 no-op

合法 ID

头文件第 5 节，不得另造：

类别	ID	说明
细包	onnx-cpu	ORT CPU
细包	onnx-cuda	ORT CUDA EP
细包	onnx-openvino	ORT OpenVINO EP
细包	onnx-trt-ep	ORT TensorRT EP
细包	trt-native	裸 TensorRT 引擎
细包	edge-rknn	仅 linux-arm64。Windows 上指名返回 DARRA_UNSUPPORTED_PLATFORM
场景包	cpu-only	细包清单，不产生新二进制
场景包	nvidia-gpu	同上
场景包	intel-iap	同上
场景包	amd-dml	同上
场景包	board-rk3588	同上
自动	nullptr	按硬件探测自动选细包（默认推荐）

Paddle 是运行时载荷（PayloadKind = paddle），由会话按载荷选 Provider，不另造 paddle 细包 ID。

安装

darra_runtime_ensure()

int32_t darra_runtime_ensure(const char* profile_or_provider_id,
                             const char* offline_zip_or_null,
                             darra_progress_cb cb,
                             void* user);

确保指定 Provider / profile 已装好；没装就探测 → 选包 → 下载 → sha256 校验 → 解压登记。

• 幂等：已装且清单匹配 → 直接成功（回调收到一次 "done", 100）
• 进程内串行：并发调用被内部互斥串行化
• 事务性：全部步骤成功才登记；取消或任何失败不留半成品
• 离线安装：offline_zip_or_null 给本地整合包 zip 路径时跳过 manifest/download（stage 仍走 verify/install），同样过内嵌 sha256 清单校验

进度回调在 SDK 内部工作线程触发：回调里禁止调用任何 darra_* 函数，只准记录或转发到调用方自己的 UI 队列。percent 0..100，每个 stage 内单调不降。stage：probe / manifest / download / verify / install / done。

参数:

• profile_or_provider_id (const char*) — 上表细包 / 场景包；nullptr = 按硬件探测自动选
• offline_zip_or_null (const char*) — 离线整合包 zip 路径；nullptr = 在线下载
• cb (darra_progress_cb) — 进度回调；nullptr = 不要进度
• user (void*) — 原样透传给 cb

返回值:

• int32_t — DARRA_OK 成功；非 0 = 错误码

典型错误：DARRA_IO_NOT_FOUND（离线包路径错）/ DARRA_NETWORK_FAILED / DARRA_CHECKSUM_MISMATCH / DARRA_IO_DENIED（目标目录需管理员）/ DARRA_UNSUPPORTED_PLATFORM / DARRA_PROVIDER_ABI_MISMATCH / DARRA_CANCELLED。

示例:

static void on_progress(float percent, const char* stage, void* user) {
    (void)user;
    std::printf("\r[%-8s] %5.1f%%", stage, percent);
    std::fflush(stdout);
}

int32_t rc = darra_runtime_ensure("cpu-only", nullptr, on_progress, nullptr);

有捕获的 lambda 不能直接当作 darra_progress_cb；有状态走 user 指针。

darra_runtime_ensure_cancel()

void darra_runtime_ensure_cancel(void);

请求取消当前在飞的 darra_runtime_ensure（可从任意线程调，含进度回调外的 UI 线程）。没有在飞的 ensure 时为 no-op。被取消的 ensure 返回 DARRA_CANCELLED。进度回调内部禁止调用。

示例:

darra_runtime_ensure_cancel();

完整示例

#include "darra_ai.h"
#include <cstdio>

static void on_progress(float percent, const char* stage, void* user) {
    (void)user;
    std::printf("\r环境准备 [%-8s] %5.1f%%   ", stage, percent);
    std::fflush(stdout);
}

int main() {
    if (DARRA_VERSION_DECODE_MAJOR(darra_version()) != DARRA_VERSION_MAJOR) {
        std::fprintf(stderr, "ABI 不匹配，库版本 = %s\n", darra_version_string());
        return 1;
    }

    int32_t rc = darra_runtime_ensure(nullptr, nullptr, on_progress, nullptr);
    std::printf("\n");
    if (rc != DARRA_OK) {
        darra_error_t err{};
        err.size = sizeof(err);
        darra_last_error(&err);
        std::fprintf(stderr, "ensure 失败 [%d] %s\n建议: %s\n",
                     err.code, err.message, err.hint);
        return static_cast<int>(rc);
    }
    return 0;
}

断网现场换成 darra_runtime_ensure("cpu-only", "darra-ai-runtime-cpu-only-offline.zip", ...)。