todaywork/on_device_ai

OnDeviceAi SDK 使用手册（v1.0.11）

on_device_ai 是基于 MNN 的 Android 端侧大模型推理 SDK，提供模型初始化、同步/流式对话、性能指标、会话管理和多模态图片输入能力。

1. 当前版本

• SDK/AAR 版本：1.0.11
• MNN Runtime：3.6.1
• Android ABI：arm64-v8a
• minSdk：26
• targetSdk：35
• 当前 AAR：on_device_ai-1.0.11-release.aar

v1.0.11

• 升级 MNN 工具链及 Android Runtime，解决新模型导出后的加载兼容问题。
• 使用最新 MNN 3.6.1 Android Runtime 重新构建完整 AAR。
• 支持新版工具链导出的结构化 tie_embeddings 配置，包括 alpha_dtype: "fp16"。
• 修复旧 Runtime 无法解析新版内嵌 embedding、错误查找 embeddings_bf16.bin 而导致新模型初始化失败的问题。
• 保持 Kotlin/JNI 公开 API 不变；兼容修复位于 MNN Runtime 内部。
• CMake 支持通过 MNN_ROOT 环境变量定位完整 MNN 源码与 Android Runtime 构建产物。
• Release AAR 同时包含 classes.jar、libMNN.so 和 libon_device_ai.so。

v1.0.10

• 修复 AI 推理过程中可能发生的 crash 问题。
• 提升模型运行及异常场景下的稳定性。

v1.0.9

• 新增 uploadImage(...)、chat(input, images, callback) 和 chatSync(input, images)。
• 支持本地图片路径与 Android Uri 导入。
• 补齐 native 图片解码及 MultimodalPrompt 接入。
• 修复 stop/max-token 状态、重复 init、maxHistory 和 setSystemPrompt 等会话管理问题。

2. 模型兼容性

v1.0.11 已在以下模型上完成实机验证：

/data/local/tmp/qwen3-car-mnn-int4

该模型由新版 MNN 工具链导出，embedding 内嵌在 llm.mnn.weight，llm_config.json 使用对象形式的 tie_embeddings。验证结果：

System Prompt Prefilled with Template. Fixed tokens: 39
Load() finished. Result: 1
Prefill: 149 ms
Decode: 742 ms / 16 tokens
Decode speed: 21.7 tokens/s

如果日志仍出现以下错误，说明应用很可能仍打包了旧版 libMNN.so：

Can't open file: .../embeddings_bf16.bin
Failed to open embedding file!

不要创建空的 embeddings_bf16.bin，也不要复制其他模型的 embedding 文件。

3. 集成 AAR

将 AAR 放入应用模块的 libs 目录：

dependencies {
    implementation files("libs/on_device_ai-1.0.11-release.aar")
}

SDK 会依次加载：

System.loadLibrary("MNN")
System.loadLibrary("on_device_ai")

因此集成时不要再同时打包另一个版本的 libMNN.so。

4. 初始化示例

val engine = OnDeviceAiEngine()

val config = OnDeviceAiEngine.PerformanceConfig(
    backendType = "cpu",
    threadNum = 4,
    precision = "low",
    memory = "low",
    promptCache = true,
    reuseKv = true,
    maxHistory = 1,
    temperature = 0.0f,
    topP = 0.1f,
    topK = 1,
    maxNewTokens = 64,
    samplerType = "greedy"
)

val success = engine.init(
    modelPath = "/data/local/tmp/qwen3-car-mnn-int4",
    config = config,
    systemPrompt = "You are a multilingual vehicle control assistant. Extract intent and slots from user commands in any language. Always respond with English JSON only.",
    isThinking = false
)

maxNewTokens 是调用方配置项；SDK 数据类的默认值仍由 PerformanceConfig 定义，当前 Demo 显式设置为 64。

5. 文本对话

同步调用：

val result = engine.chatSync("Close the passenger window")

流式调用：

engine.chat("Close the passenger window", object : OnDeviceAiEngine.ChatCallback {
    override fun onToken(token: String, isEnd: Boolean): Boolean {
        return true
    }

    override fun onPerformanceUpdate(
        prefillTimeMs: Long,
        decodeTimeMs: Long,
        tokenCount: Int
    ) {
        // 更新性能指标
    }
})

6. 多模态图片输入

本地路径：

val image = engine.uploadImage("/sdcard/Pictures/camera.jpg")
val result = engine.chatSync("Describe this image", listOf(image))

Android Uri：

val image = engine.uploadImage(context, uri)
engine.chat("Describe this image", listOf(image), callback)

图片输入需要视觉模型支持。纯文本模型不能获得图像理解能力。

7. 从源码构建 AAR

前置条件：

• 完整 MNN 源码：E:\LLMProject\MNN
• MNN Android Runtime：E:\LLMProject\MNN\project\android\build_64\lib\libMNN.so
• Android SDK/NDK 已正确配置

PowerShell：

$env:MNN_ROOT = "E:\LLMProject\MNN"
.\gradlew.bat :on_device_ai:assembleRelease --rerun-tasks

输出：

on_device_ai/build/outputs/aar/on_device_ai-1.0.11-release.aar

发布前应确认 AAR 中至少包含：

classes.jar
jni/arm64-v8a/libMNN.so
jni/arm64-v8a/libon_device_ai.so

8. 注意事项

• MNN 导出工具和 Runtime 应使用兼容版本，最好来自同一源码提交。
• 更新 Runtime 后必须重新构建整个 AAR，不能只替换 Java/Kotlin 层。
• 每次 init 会释放旧 Session；应用退出时仍建议显式调用 release()。
• 指令抽取任务建议关闭 Thinking，并使用低温度或 greedy sampler。
• consumer-rules.pro 当前未提供；Release 构建会产生警告，但在 minifyEnabled false 下不影响 AAR 生成。