Rust

Name: Darra AI Studio
Author: Darra

crate darra-ai 是对 darra_ai.h 的薄绑定：只翻译类型和错误码，不另造语义。工作区 publish = false、version = "1.0.0"、rust-version = "1.70"。不发布 crates.io，以路径依赖接入。权威契约 = Core/include/darra_ai.h；hint 文案与错误码逐字一致。

公开 runtime 面只含解密、验票、推理分发、诊断、运行时包管理。物理上没有 darra_encrypt_ / darra_issue_ / darra_fingerprint_ 符号。authoring 面仅 AI Studio 侧，不在本公开包。

命名风格

crate darra-ai，方法 snake_case，错误是 darra_ai::Error 枚举变体，Session / InferPool 是 RAII 句柄 Drop 释放。

安装

[dependencies]
darra-ai = { path = "<SDK 解压目录>/Rust/darra-ai" }

默认 feature json 打开 serde_json。只要字符串 JSON 可写 default-features = false。构建必须设 DARRA_AI_CORE_LIB_DIR，指向 SDK 包内的 Core 链接库目录（include/ 与 lib/ 随包提供，加进构建路径即可）。

$env:DARRA_AI_CORE_LIB_DIR = '<Core 链接库目录>'

环境要求

操作系统 — Windows x64、Linux x86_64、Linux aarch64（RK3588）。macOS / 32 位 / 其它架构不在支持矩阵
Rust — rust-version = 1.70
native — 运行时需要 DarraAI.Core 与对应平台链接库。缺库时加载失败，不放假二进制
Windows 上指名 edge-rknn — Core 返回 UNSUPPORTED_PLATFORM（RKNN 只在 linux-arm64）。Windows 收到 rknn 载荷返回 UNSUPPORTED_PAYLOAD
权限 — 装运行时包到系统目录时可能需要管理员；SDK 不代装 NVIDIA / RK3588 NPU 等系统驱动

诚实边界

不承诺 dump 免疫。 授权机 + 管理员级调试器在会话存活期暂停 dump，挡不住。本 SDK 防的是静态拷走、转发、无授权运行、常规 dump 工具、逆向授权算法。
加密单向。 官方不提供解回明文的通道。永久密码只用于无限次推理。公开包不能签发、不能加密。
环境提前部署。 SDK 只验证和加载本地 Provider；下载、安装与系统驱动由 Studio 或部署流程处理，diagnostics::collect 提供只读诊断。
macOS 不在 v1。 不是「即将支持」。
不承诺硬实时。 推理是阻塞调用。PLC 侧必须在扫描周期外进程 / 线程调用。
诊断 JSON 不含密钥 / 密码 / token / 机器指纹字节。
Windows 无 RKNN。 edge-rknn 永不出现在 Windows 安装列表。

功能概览

功能	说明
会话	Session.open / open_plain / open_ex；Drop 释放
推理	infer_image + ImageDesc；每次一张图，循环帧
运行时	version / version_string；本地环境诊断
版本与诊断	diagnostics.collect 去敏 JSON；禁止放进 PLC 扫描周期
错误处理	每个 darra_error_code 一个枚举变体
类型	ImageFormat / SessionOptions / Error

let opt = SessionOptions::new()
    .intra_op_threads(4)
    .parallel(2);
let s = Session::open_ex("model.darmodel", None, Some(&opt))?;
let json = s.infer_image(&jpeg, &ImageDesc::auto())?;

SDK 不发起环境下载，也没有安装进度回调。下载进度、取消与重试统一在 Studio 右上角下载中心处理，或由客户的部署流程负责。

一模型一实例：一个 Session = 一份已加载模型 + 一个 Provider。多模型或多份同模型 = 多会话，API 完全相同。指名 Provider 不可用 = fail-closed，绝不静默降级。

不同会话可并发。同一会话 infer_image 在 parallel 0/1 时内部互斥排队；同模型并发请设 SessionOptions::parallel = 2..8（走 open_ex / open_plain_ex），仍调 infer_image，一份权重。Drop 禁止与任何在飞调用并发。

Session / InferPool 是不透明 RAII 句柄，不可 Clone，Send + Sync。ImageFormat 只暴露 Auto / Encoded / Rgb888 / Bgr888。

快速开始

use darra_ai::{ImageDesc, Session};

fn main() -> Result<(), darra_ai::Error> {
    let session = Session::open("model.darmodel", None)?;
    let jpeg = std::fs::read("photo.jpg").map_err(|e| darra_ai::Error::IoNotFound {
        message: format!("读图片失败：photo.jpg ({e})"),
        hint: String::new(),
    })?;
    let json = session.infer_image(&jpeg, &ImageDesc::auto())?;
    println!("{json}");
    Ok(())
}

未激活：Session::activate("model.darmodel", code, None, None)。旧双文件 .darmkey：Session::open_with_key。同模型突发 / 流式进图见推理池。prefer_provider 为 None 时按载荷 × 硬件 × 已装包自动选；指名但不可用 = fail-closed，不静默降级。

明文模型

与加密入口同一推理路径，只跳过容器解码与验票。Paddle 是运行时载荷：明文路径可接 .pdmodel（同目录须有 .pdiparams）或含二者的目录。

let session = Session::open_plain("model.onnx", None)?;
let json = session.infer_image(&jpeg, &ImageDesc::auto())?;

open_plain 的路径可以是 .onnx、.pdmodel（同目录须有 .pdiparams）、或含二者的目录。.pt / .pth 返回 UnsupportedPayload。第二参是 prefer_provider；None = 自动选。

何时用哪种

.darmodel + 激活 — 生产环境，推荐。
open_plain — Studio 试跑 / 客户自有明文模型。

工业相机裸缓冲

每次调用处理一张图。相机连续采集时按帧循环调用。裸缓冲禁止 ImageDesc::auto()（嗅探不出通道序）。stride = 0 表示紧凑（= width * 3）。

let frame = grab_bgr_frame();
let results = session.infer_image(
    &frame, &ImageDesc::bgr888(1920, 1080, 0))?;

版本兼容

当前 crate darra-ai v1.0.0，rust-version = 1.70。绑定与 DarraAI.Core 必须同一发布批次；major 变 = ABI 破坏，须成套升级。公开包是 runtime 构建，客户机 version_string() 必须看到 +runtime。

安装​

环境要求​

功能概览​

快速开始​

明文模型​

工业相机裸缓冲​

版本兼容​

安装