ensure

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

Windows 无 RKNN

edge-rknn 永远不会出现在 Windows 安装列表。在 Windows 上指名它抛 UnsupportedPlatformError。

装包

runtime.ensure()

def ensure(
    profile_or_provider_id: str | None = None,
    offline_zip: str | None = None,
    progress: Callable[[float, str], None] | None = None,
) -> None

确保指定 Provider / profile 已装好。

参数:

• profile_or_provider_id (str | None) — 细包 ID 或场景整合包名；None = 按硬件自动选
• offline_zip (str | None) — 本地离线整合包 zip；None = 在线下载
• progress (Callable[[float, str], None] | None) — (percent, stage) 回调。percent 为 0..100；stage 为 probe / manifest / download / verify / install / done

相关结构:

ProgressCallback = Callable[[float, str], None]

备注

• 幂等：已装且清单匹配 → 直接成功（回调收到一次 "done", 100）。
• 进程内串行：并发调用被内部互斥串行化。
• 事务性：全部步骤成功才登记；取消或任何失败不留半成品。
• offline_zip 给定时跳过 manifest/download，仍过内嵌 sha256 清单校验。
• SDK 不自动安装 / 升级系统驱动。
• 进度回调在 SDK 工作线程触发，回调内禁止再调任何 Darra AI API（含 cancel）。回调异常被吞掉，以免穿越 C 边界崩进程。percent 在每个 stage 内单调不降。

典型异常：IoNotFoundError（离线包路径错）/ NetworkFailedError / ChecksumMismatchError / IoDeniedError（目标目录需管理员）/ UnsupportedPlatformError / ProviderAbiMismatchError / CancelledError。

示例:

from darra_ai import runtime

def on_progress(percent: float, stage: str) -> None:
    print(f"\r[{stage:<8}] {percent:5.1f}%", end="", flush=True)

runtime.ensure(None, None, on_progress)          # 按硬件自动选
runtime.ensure("cpu-only")                       # 指名场景包
runtime.ensure("cpu-only", "offline.zip")        # 离线安装

runtime.cancel()

def cancel() -> None

请求取消当前在飞的 ensure（任意线程可调，含进度回调外的 UI 线程）。

备注

没有在飞的 ensure 时为 no-op。被取消的 ensure 抛 CancelledError。进度回调内部禁止调用。

示例:

from darra_ai import runtime
from darra_ai.errors import CancelledError

try:
    runtime.ensure("nvidia-gpu", progress=lambda p, s: print(s, p))
except CancelledError:
    pass