Java 用法

面向最终用户的接入步骤：装依赖、打开模型、反复推理、关掉会话。

调用链

一条链走到底：tryOpen / open 打开会话 → inferImage 反复推理 → close 关闭。会话实现 AutoCloseable，用 try-with-resources 收口。

tryOpen / open — 打开模型建会话。打开成本只付一次，之后一次打开反复推理，不要每张图重新打开。
tryActivate / activate — 出厂首次或试用，让用户填一次激活码；成功后本机记住，之后直接 tryOpen / open，不用再填。inferImage 不收激活码。
inferImage — 每次处理一张图，返回结果 JSON。相机/视频按帧循环调用。
close — 释放会话；重复关闭安全。禁止与在飞推理并发。

失败抛 AiException 的嵌套子类，getHint() 是给最终用户的修复建议。常见子类：IoNotFoundException（文件不在）、PasswordRequiredException（要激活码）、TrialExhaustedException（试用完）、ProviderMissingException（缺运行时包）、UnsupportedPlatformException（系统/架构不支持）。

前置依赖

JDK 17 及以上。
主 jar 纯 Java，不含原生库。真正跑推理的是 Core.dll / libCore.so 与 darraai_jni（Windows 为 darraai_jni.dll，Linux 为 libdarraai_jni.so），三种放法按顺序找，找到就用：
1. 系统属性 -Dxyz.darra.ai.natives.dir 指向放好这两个文件的目录。
2. classpath 引 natives classifier 包，包内路径形如 natives/windows-x86_64/。
3. 放进 java.library.path（Windows 一般是程序工作目录或 PATH 里的目录）。
Provider 运行时包须提前部署。SDK 只查找、验证和加载本地 Provider，不下载不安装；缺包时返回缺包错误，安装进度在 Studio 下载中心看。
支持 Windows x64、Linux x86_64、Linux aarch64（RK3588）。macOS 不在 v1。

安装

Maven 依赖加对应平台 natives classifier：

<dependency>
    <groupId>xyz.darra</groupId>
    <artifactId>darra-ai</artifactId>
    <version>1.0.0</version>
</dependency>
<dependency>
    <groupId>xyz.darra</groupId>
    <artifactId>darra-ai</artifactId>
    <version>1.0.0</version>
    <classifier>natives-windows-x86_64</classifier>
</dependency>

Linux x64 把 classifier 换成 natives-linux-x86_64；Linux ARM64 / RK3588 用 natives-linux-aarch64。

Gradle：

implementation 'xyz.darra:darra-ai:1.0.0'
implementation 'xyz.darra:darra-ai:1.0.0:natives-windows-x86_64'

手头 jar 直接进 classpath：

java -cp darra-ai-1.0.0.jar;你的程序.jar 你的主类

快速开始

打开 .darmodel、推一张图、打出结果 JSON：

import java.nio.file.Files;
import java.nio.file.Path;

import xyz.darra.ai.AiSession;
import xyz.darra.ai.ImageDesc;

public class Demo {
    public static void main(String[] args) throws Exception {
        AiSession.OpenResult r = AiSession.tryOpen("model.darmodel", null);
        if (!r.ok()) {
            System.err.println(r.info().display());
            return;
        }
        try (AiSession s = r.session()) {
            byte[] jpg = Files.readAllBytes(Path.of("photo.jpg"));
            String json = s.inferImage(jpg, ImageDesc.auto());
            System.out.println(json);
        }
    }
}

明文模型 + 阈值覆盖走 openPlainEx 与 SessionOptions（0 / null = 不覆盖）：

SessionOptions opt = SessionOptions.empty().confThreshold(0.5f).nmsThreshold(0.45f);
try (AiSession s = AiSession.openPlainEx("model.onnx", null, opt)) {
    String json = s.inferImage(Files.readAllBytes(Path.of("photo.jpg")), ImageDesc.auto());
}

按场景索引

案例	一句话能力
推理入门	打开会话、推理一张图、关闭的最小调用链
视频连续推理	相机逐帧进图，满队列丢最旧帧保最新画面
图片队列	一次上百张进队列，容量与溢出策略由应用定
并行推理	同模型多路并发，推理线程数独立可配
多模型并行	多模型或多卡分槽，按 Weight 分并发槽份额

运行时与诊断见运行时，失败处置见错误处理。

设备池

多张卡按每卡权重分活，不是插队。和同一张卡上的推理池不是一回事。打开没成功：路径空抛 InternalException；文件不在、未激活、缺 Provider 抛 AiException 子类；JNI 或运行库缺符号抛 UnsatisfiedLinkError。不是关了再开。

AiDevicePool pool = AiDevicePool.openPlain("model.onnx", null, null);
long ticket = pool.submit(jpg, ImageDesc.auto(), -1);
String json = pool.waitFor(ticket);
pool.close();

调用链​

前置依赖​

安装​

快速开始​

按场景索引​

设备池​

调用链

前置依赖

安装

快速开始

按场景索引

设备池