跳到主要内容

ensure

确保 Provider / profile 已装好。幂等、进程内互斥、事务性。

合法 ID​

细包（Provider）：

ID平台
onnx-cpuWindows / Linux
onnx-cuda有 NVIDIA GPU 的机器
onnx-openvinoIntel
onnx-trt-epNVIDIA + TensorRT EP
trt-nativeNVIDIA + 原生 TensorRT
paddle-cpuWindows / Linux x64（Paddle 载荷，PayloadKind = paddle）
edge-rknn仅 linux-arm64（RK3588）

场景整合包（profile，只是细包清单，不产生新二进制）：

cpu-only · nvidia-gpu · intel-iap · amd-dml · board-rk3588

None = 按硬件探测自动选细包（默认推荐，用户不感知包）。绑定把 ID 当 &str 原样交给 Core，不在 Rust 侧枚举。

Windows 无 RKNN
  • edge-rknn 永远不会出现在 Windows 安装列表。
  • 在 Windows 上指名 edge-rknn → Error::UnsupportedPlatform。
  • Windows / linux-x64 收到 rknn 载荷 → Error::UnsupportedPayload。
  • rknn 只在 linux-arm64 板端运行时（RK3588 + edge-rknn + librknnrt）。

SDK 不代装系统驱动。NVIDIA 驱动过旧、RK3588 板镜像缺 NPU 驱动这类要管理员权限 / 重启 / 板厂镜像的依赖，只诊断不代劳。

功能概览​

类别属性类型访问说明
runtimeruntime::ensureResult<(), Error>函数确保 Provider / profile 已装；没装就探测→选包→下载→校验→解压登记
runtime::cancel()函数请求取消当前在飞的 ensure。可从任意线程调；进度回调内部禁止

安装​

runtime::ensure()​

pub fn ensure(
    profile_or_provider_id: Option<&str>,
    offline_zip: Option<&str>,
    progress: Option<&dyn Fn(f32, &str)>,
) -> Result<(), Error>

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

参数:

  • profile_or_provider_id (Option<&str>) — 细包 ID 或场景整合包名；None = 按硬件自动选
  • offline_zip (Option<&str>) — 本地整合包 zip 路径；None = 在线下载。离线时跳过 manifest/download，仍走 verify/install，同样过内嵌 sha256 清单校验
  • progress (Option<&dyn Fn(f32, &str)>) — 进度回调 (percent 0..100, stage)。None = 不要进度

返回值:

  • Result<(), Error> — 成功为空；失败见 错误

  • 幂等：已装且清单匹配 → 直接成功（回调收到一次 "done", 100）。

  • 进程内串行：并发调用被内部互斥串行化，重复调用安全。

  • 事务性：全部步骤成功才登记 Provider；取消或任何失败不留半成品。

进度 stage ∈ probe / manifest / download / verify / install / done。percent 每个 stage 内单调不降。回调在 SDK 内部工作线程触发：

  • 回调里禁止再调任何 darra API（含 cancel）。
  • trampoline 已挡住 panic 穿过 FFI。

典型错误：IoNotFound（离线包路径错）/ NetworkFailed / ChecksumMismatch / IoDenied（目标目录需管理员）/ UnsupportedPlatform / ProviderAbiMismatch / Cancelled。

示例:

use darra_ai::runtime;

runtime::ensure(None, None, Some(&|percent, stage| {
    eprint!("\r环境准备 [{stage:<8}] {percent:5.1}%   ");
}))?;

指名场景包：

runtime::ensure(Some("cpu-only"), None, None)?;

Paddle 细包：

runtime::ensure(Some("paddle-cpu"), None, None)?;

离线 zip：

runtime::ensure(None, Some(r"D:\offline\nvidia-gpu.zip"), None)?;

runtime::cancel()​

pub fn cancel()

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

示例:

std::thread::spawn(|| {
    darra_ai::runtime::cancel();
});