包管理

没装就探测 → 选包 → 下载 → 校验 → 解压登记到 C:\DARRA\Runtime。幂等；进程内串行；取消或失败不留半成品。

Provider ID

细包（Provider）：

ID	说明
onnx-cpu	CPU
onnx-cuda	NVIDIA CUDA
onnx-openvino	Intel OpenVINO
onnx-trt-ep	TensorRT EP
trt-native	原生 TensorRT
edge-rknn	仅 linux-arm64（RK3588）

场景整合包（只是细包清单，不产生新二进制）：cpu-only / nvidia-gpu / intel-iap / amd-dml / board-rk3588。

Windows 无 RKNN

edge-rknn 永远不会出现在 Windows 安装列表。在 Windows 上指名它抛 AiUnsupportedPlatformException。Windows 收到 rknn 载荷抛 AiUnsupportedPayloadException。

Ensure

AiRuntime.Ensure()

public static void Ensure(
    string? profileOrProviderId = null,
    string? offlineZip = null,
    Action<float, string>? progress = null)

确保指定 Provider / profile 已装好。已装且匹配 → 直接成功（回调收到一次 "done", 100）。

参数:

• profileOrProviderId (string?) — 细包 ID 或场景整合包；null = 按硬件探测自动选细包
• offlineZip (string?) — 离线整合包 zip 路径；null = 在线下载
• progress (Action<float, string>?) — 进度回调（percent 0..100，stage ∈ probe / manifest / download / verify / install / done）。在 SDK 工作线程触发

进度回调契约

回调内禁止调用任何 Darra AI API（含 Cancel / Check / Open）。回调抛出的异常会被吞掉，避免穿过 native 边界。UI「取消」从 UI 线程调 AiRuntime.Cancel，用 CancellationToken.Register(AiRuntime.Cancel)。

示例:

CancellationToken token = /* UI token */;
token.Register(AiRuntime.Cancel);

try
{
    AiRuntime.Ensure("nvidia-gpu", progress: (p, s) => Console.WriteLine($"{s} {p:0}%"));
}
catch (AiCancelledException)
{
    return;
}

AiRuntime.Cancel()

public static void Cancel()

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

示例:

AiRuntime.Cancel();

环境检测

类别	属性	类型	访问	说明
AiEnvironment	Check	AiEnvCheck	静态	基础检测：推荐哪套推理包、装了没有。不联网、不改盘
	EnsureReady	AiEnvCheck	静态	按检测结果自动安装推荐 Provider（及 requires：cuDNN / cuda-libs）。幂等。返回装完后的再检测结果

推荐优先级：NVIDIA → onnx-cuda；否则 Intel → onnx-openvino；否则 AMD 且 Windows → onnx-directml；否则 onnx-cpu。不在此推荐 edge-rknn。

AiEnvironment.Check()

public static AiEnvCheck Check()

基础检测：推荐哪套推理包、装了没有。不联网、不改盘。

返回值:

• AiEnvCheck — 推荐 Provider、是否已装、已装列表、GPU 型号、中文结论

示例:

AiEnvCheck env = AiEnvironment.Check();
Console.WriteLine(env.Message);

AiEnvironment.EnsureReady()

public static AiEnvCheck EnsureReady(Action<float, string>? progress = null)

按检测结果自动安装推荐 Provider（及 requires：cuDNN / cuda-libs）。幂等。返回装完后的再检测结果。

参数:

• progress (Action<float, string>?) — 进度回调，契约同 AiRuntime.Ensure

返回值:

• AiEnvCheck — 安装后再检测的结果

示例:

AiEnvCheck env = AiEnvironment.Check();
if (!env.Ready)
    env = AiEnvironment.EnsureReady((percent, stage) =>
        Console.Write($"\r[{stage,-8}] {percent,5:0.0}%"));