AB
AiBoss站
教程

在 Android 上用 LiteRT-LM 集成端侧 LLM:缓存、GPU 探测与多机型适配

教程

在 Android 上用 LiteRT-LM 集成端侧 LLM:缓存、GPU 探测与多机型适配

把 LiteRT-LM 接入 Android 应用并不难,难的是让它在各种机型上都稳定。本文按实际工程顺序讲清:如何预生成模型缓存、如何按模型与后端拆分缓存目录、如何探测 GPU 是否可用、何时该退回 CPU、maxNumTokens 与内存的取舍,以及为什么分发时应选通用版模型。

LiteRT-LM 是 Google 的端侧 LLM 运行时,提供 com.google.ai.edge.litertlm:litertlm-android 这个 Android 库。它的 API 面很小:创建一个 Engine、调用 initialize()、打开一个 Conversation、把消息发出去,就能在设备本地跑起一个 Gemma 系列模型。适合的场景是那些不方便把内容送到服务器的功能,比如对隐私敏感的对话摘要、离线可用的文本处理。

但「在自己手上那台机器能跑」和「在用户手上的各种机器都能跑」之间隔着不少坑。下面按工程落地的顺序,把缓存预热、缓存目录管理、GPU 可用性探测、后端选择、上下文长度与内存、模型版本选择这几件事讲清楚。文中出现的耗时、内存、体积等数值都来自特定机型与特定版本的实测,仅作量级参考;库版本、模型规格、配额与可用性请以官网当前信息为准。

准备工作

依赖与模型文件

在模块的构建脚本中加入 LiteRT-LM 的 Android 依赖,并把 .litertlm 模型文件放进应用可访问的位置(首次启动下载或随包分发,取决于模型体积与你的分发策略)。

dependencies {
    implementation("com.google.ai.edge.litertlm:litertlm-android:0.17.0")
}

模型方面需要区分两种产物:

  • 通用版:同时包含 CPU 与 GPU 所需的图,体积较大(示例中约 2.59GB),但能在任意后端上打开。
  • GPU 专用版:体积更小(示例中约 2.01GB),加载更快、无需生成缓存,但缺少 CPU 图,无法作为 CPU 回退。

面向不特定用户分发时,选通用版。原因在后面的「模型版本选择」一节展开。

权限与清单声明

如果打算使用 GPU 后端,LiteRT-LM 会通过 OpenCL 做推理。OpenCL 由设备厂商的 GPU 驱动提供,并不是 Android 的必备组件。从 Android 12(API 31)起,应用要加载厂商提供的原生库,必须在清单里显式声明:

<uses-native-library
    android:name="libOpenCL.so"
    android:required="false" />

required="false" 很重要:没有 OpenCL 的设备也应该能安装你的应用,只是走 CPU 路径。

存储与内存预算

在动手写代码前先算两笔账:

  • 磁盘:模型本体之外,GPU 缓存约 759MB、CPU 缓存约 788MB。两个后端都保留时合计接近 1.5GB。
  • 内存:加载后仅权重就占用约 2GB;在默认 maxNumTokens 下,实测 PSS 峰值约 2.7GB。RAM 为 4GB 的设备已经相当紧张。

这两笔账决定了后面很多设计取舍。

操作步骤

第一步:跑通最小调用链

基本用法只有四步:构造 Engine、initialize()、createConversation()、发送消息。发送接口返回的是 Flow<Message>,逐片收集即可。

val engine = Engine(
    EngineConfig(
        modelPath = modelFile.absolutePath,
        backend = Backend.GPU(), // 或 Backend.CPU()
        cacheDir = cacheDir.absolutePath,
    ),
)
engine.initialize()

val conversation = engine.createConversation(ConversationConfig())
val output = StringBuilder()
conversation.sendMessageAsync(prompt).collect { message ->
    output.append(message.text())
}
conversation.close()

Message 里混有文本以外的内容片段,需要一个扩展函数把文本部分拼出来:

fun Message.text(): String =
    contents.contents
        .filterIsInstance<Content.Text>()
        .joinToString(separator = "") { it.text }

到这里功能就能用了。接下来的每一步,都是为了让它在更多设备上不出问题。

第二步:在下载模型后立即预热缓存

initialize() 首次执行时会把模型权重编译成缓存写进 cacheDir。有没有这份缓存,加载时间差一个数量级:在 Pixel 9 Pro 的 GPU 上,无缓存约 59 秒,有缓存约 3 秒。

如果什么都不做,用户看到的现象是「第一次摘要怎么都跑不完」。正确的做法是在模型下载完成后立刻单独跑一次初始化,只为了把缓存建出来,不做任何推理:

suspend fun prepareCache(modelFile: File, backend: Backend) {
    runCatching {
        open(modelFile, backend).use { engine ->
            engine.initialize()
        }
    }.onFailure { e ->
        Log.w(TAG, "could not prepare the cache; the first inference will be slower", e)
    }
}

这里有两个必须注意的点:

  • 用完立刻关闭引擎。加载后光权重就占约 2GB,如果为了「预热」把引擎常驻在内存里,很可能因为内存压力被系统杀掉。用 use 保证关闭。
  • 失败不要抛异常。缓存建不出来时推理依然能跑,只是第一次慢。把失败降级成日志即可。

把这一分钟放在「正在下载模型」的等待里,用户几乎无感;放在「正在生成摘要」的等待里,体验完全不同。

第三步:按模型与后端拆分缓存目录

LiteRT-LM 没有提供返回缓存文件名的 API,也没有删除缓存的 API。Engine 暴露的只有 initialize()、close()、createConversation()、createSession() 等,cacheDir 只是通过 EngineConfig 传一个路径进去。

缓存文件按内部规则命名,形如:

<模型文件名>_<数字>_<字节数>_mldrift_weight_cache.bin   // GPU
<模型文件名>_<数字>_<字节数>_mldrift_program_cache.bin  // GPU
<模型文件名>_<数字>_<字节数>.xnnpack_cache              // CPU

这些名字由内部实现决定,版本升级就可能变化,不要依赖它们做删除逻辑。

推荐的做法是:为每个模型、每个后端指定独立的缓存目录,需要清理时整目录删除。这样既不依赖内部命名,也能精确地只删掉不用的那一份。

// root 是应用缓存目录下的子目录,例如 cacheDir/summary-model
// SummaryBackend 是应用侧表示 GPU / CPU 的枚举
fun dirFor(modelFileName: String, backend: SummaryBackend): File =
    File(File(root, modelFileName), backend.name.lowercase()).apply { mkdirs() }

val engineCacheDir = dirFor(modelFile.name, SummaryBackend.GPU)
val engine = Engine(
    EngineConfig(
        modelPath = modelFile.absolutePath,
        backend = Backend.GPU(),
        cacheDir = engineCacheDir.absolutePath,
    ),
)
engine.initialize()

目录结构大致是:

cacheDir/summary-model/<模型文件名>/gpu/
cacheDir/summary-model/<模型文件名>/cpu/

在存储紧张的设备上,删掉用不到的那一侧目录,既省空间,也降低了后续缓存生成失败的概率。

第四步:每次推理重建 Conversation,复用 Engine

Conversation 会保留对话历史。摘要这类每次相互独立的推理如果复用一个会话,历史 prompt 与输出会不断累积,最终撞上 token 上限并报错:

Status Code: 11. Not possible to enqueue all requested tokens

正确的分工是:Engine 长期复用,Conversation 每次推理新建、用完关闭。打开会话本身很轻,重的是引擎加载。

suspend fun infer(engine: Engine, prompt: String): String {
    val conversation = engine.createConversation(conversationConfig())
    try {
        val output = StringBuilder()
        conversation.sendMessageAsync(prompt).collect { output.append(it.text()) }
        return output.toString()
    } finally {
        conversation.close()
    }
}

第五步:探测 GPU 是否真的可用

有些设备有 OpenCL、模型也能加载成功,但推理只返回空字符串,不抛任何异常。实测中 moto g54 5G(Mali-G57)加载耗时 45~48 秒后成功,推理却什么都不返回;同样搭载 Mali-G57 的 OPPO A79 5G 则正常。也就是说,靠 GPU 型号无法判断。

试过的几种间接判断都不可靠:

  • OpenCL sampler not available, falling back to statically linked C API 这条警告在正常工作的 OnePlus 10T 上也会出现。
  • 加载耗时无法区分,正常设备首次生成缓存也要几十秒。

最可靠也最便宜的办法是发一次极短的推理,看有没有返回:

private suspend fun probe(engine: Engine): Boolean = withTimeoutOrNull(PROBE_TIMEOUT_MILLIS) {
    val conversation = engine.createConversation(probeConfig()) // maxOutputToken = 32
    val seen = StringBuilder()
    runCatching {
        conversation.sendMessageAsync("「はい」とだけ答えてください。").collect { message ->
            seen.append(message.text())
        }
    }.onFailure { e ->
        if (e is CancellationException) throw e
    }
    withContext(NonCancellable) { runCatching { conversation.close() } }
    seen.isNotBlank()
} ?: false

探测时机放在上一步的缓存预热阶段,也就是模型刚下载完的时候。多花几秒,用户感知不到。如果 GPU 没有应答,就接着生成 CPU 缓存,并把「该模型在此设备上 GPU 不可用」这个结论持久化,之后直接走 CPU。

一次真实设备上的日志顺序大致如下:

preparing the cache for ...litertlm on GPU
prepared the cache in 43922 ms
probe answered=false in 4560 ms
the GPU did not answer; preparing the CPU cache instead
prepared the cache in 6314 ms
probe answered=true in 2943 ms
dropped 1 caches for other backends (796762312B)
loaded ... on CPU in 564 ms

在正常的 Pixel 9 Pro 上,探测约 0.85 秒返回。对那台 GPU 无响应的设备,用户等待摘要的时间从「永远出不来」变成约 65 秒(801 字输入),而如果等到运行时才发现问题再切 CPU,合计约 133 秒。

不建议把不可用设备的清单硬编码进应用:同一款 GPU 在不同机型上表现不同,系统更新也可能改变结果。让设备自己试一次并记住结论,才能覆盖未知机型。

第六步:先判断 OpenCL 是否存在,并处理模拟器

有些设备根本没有 OpenCL。Pixel 6a(Tensor G1)在加载阶段直接失败:

Status Code: 2. UNKNOWN: Can not find OpenCL library on this device

这一项可以提前判断,只要看 System.loadLibrary("OpenCL") 是否成功:

private val hasOpenCl: Boolean by lazy {
    runCatching { System.loadLibrary("OpenCL") }.isSuccess
}

模拟器的情况更糟:用 GPU 后端加载会在原生层崩溃,整个进程退出。用 Build 信息识别模拟器,直接走 CPU。

第七步:设置 maxNumTokens,并接受它的内存代价

长 prompt 有时不会报错,而是几秒内返回空字符串。这看起来像模型上下文长度不够,实际原因是 EngineConfig 没有指定 maxNumTokens。以 6,754 字 prompt 为例:

maxNumTokens结果
不指定(默认值)返回空(4.7 秒)
8192返回 2,019 字(156 秒)

模型卡上标注的最大上下文远大于此,限制来自引擎配置而不是模型本身。输入与输出共享同一个额度,所以默认值下随着 prompt 变长,输出会先变短、再变空:

prompt 长度输出长度
3,731 字1,509 字
4,751 字1,544 字
5,656 字954 字
6,754 字0 字

看到「输入明明进去了,输出却短得离谱」,先查这个额度,再怀疑模型。

EngineConfig(
    modelPath = modelFile.absolutePath,
    backend = backend,
    cacheDir = cacheDir.absolutePath,
    maxNumTokens = 8192,
)

代价是内存。同一输入下 dumpsys meminfo 的 PSS 峰值:

maxNumTokensPSS 峰值
不指定2,716 MB
81922,942 MB
163843,428 MB

默认值下就已经 2.7GB,4GB RAM 的设备没有余量。所以「调大上限以容纳长输入」只适合内存宽裕的设备。更稳妥的工程做法是保持默认值,把长对话切段摘要后再合并。

另外,目前没有 API 能在推理前查询模型上下文长度或 prompt 的 token 数;推理后的 token 数可以从 BenchmarkInfo 拿到。

一个完整示例

把上面的步骤串起来,模型下载完成后的初始化流程大致如下:

// 1. 决定后端:无 OpenCL 或模拟器直接 CPU
val preferGpu = hasOpenCl && !isEmulator && !knownGpuUnusable

// 2. 用后端专属目录预热缓存
val gpuDir = dirFor(modelFile.name, SummaryBackend.GPU)
val cpuDir = dirFor(modelFile.name, SummaryBackend.CPU)

var useGpu = false
if (preferGpu) {
    prepareCache(modelFile, Backend.GPU(), gpuDir)
    // 3. 短推理探测
    useGpu = open(modelFile, Backend.GPU(), gpuDir).use { engine ->
        engine.initialize()
        probe(engine)
    }
    if (!useGpu) {
        knownGpuUnusable = true
        gpuDir.deleteRecursively()
    }
}
if (!useGpu) {
    prepareCache(modelFile, Backend.CPU(), cpuDir)
}

// 4. 正式推理时复用 Engine,每次新建 Conversation
val backend = if (useGpu) Backend.GPU() else Backend.CPU()
val cacheDirForBackend = if (useGpu) gpuDir else cpuDir
val engine = open(modelFile, backend, cacheDirForBackend)
engine.initialize()
val summary = infer(engine, prompt)
engine.close()

这个流程的关键在于:所有「可能失败、可能很慢」的动作都集中在模型下载之后,用户此时本来就在等待;真正点「生成摘要」时,只剩一次轻量的会话创建和推理。

注意事项

GPU 不一定比 CPU 快

对 801~4,042 字的 7 段对话做摘要,统计模型加载加推理的总耗时(缓存已提前建好,不含缓存生成):

设备GPU 执行CPU 执行结论
Mali-G57 / OPPO A79 5G44.7 分27.6 分CPU 快 1.6 倍
Mali-G68 / Galaxy A54 5G21.4 分21.5 分基本持平
Mali-G715 / Pixel 813.7 分20.0 分GPU 快 1.5 倍

规律是:GPU 较弱的设备上,无论输入长短都是 CPU 更快(Mali-G57 在 7 段输入上全部如此,差距 1.3~1.8 倍);GPU 较强的设备上 GPU 更快,但短输入时差距消失(Mali-G715 在 801 字时几乎相同,其余 6 段最多快 1.8 倍);中间档的 Mali-G68 几乎没有差别。

还有一点容易被忽略:模型加载本身是 CPU 更快。有缓存时 GPU 需要 3~9 秒,CPU 只需 0.5~1.5 秒。对于 30 秒左右就能跑完的短摘要,这个差距足以改变结论。

测量时务必把缓存生成排除在外。缓存生成在 GPU 上要 44~78 秒,CPU 上 8~17 秒,混进去会让短输入场景看起来是 GPU 更慢。

质量方面,按对话中的事实召回率统计,CPU 为 87.3%,GPU 因机型不同在 82.3%~89.9% 之间。GPU 之间的差异比 CPU 与 GPU 之间的差异更大,所以切到 CPU 不会降低质量。

麻烦的是,慢 GPU 的结果是正确的。它和「什么都不返回」的设备不同,探测发现不了,用户只会觉得慢。想按 GPU 型号定默认值也不现实:测试覆盖的 GPU 世代有限,无法预判新世代的表现。因此默认仍用 GPU,同时提供设置项让用户切到 CPU。

CPU 输出跨机型一致,GPU 不一致

把采样温度设为 0、输入相同内容,CPU 的输出在不同机型上完全一致:7 段输入在 4 种机型(3 种 Mali 加 Adreno 750)上处理,输出 md5 全部相同。GPU 的输出则在 6 种机型上各不相同,原因是不同 GPU 实现的计算结果存在细微差异。

这直接影响测试策略:

  • 以 CPU 为默认时,回归测试可以用输出完全一致来断言。
  • 以 GPU 为默认时,必须假设同一输入在不同设备上输出的措辞和长度都会变化。

后者实际踩过的坑是输出长度上限。为了截断失控生成,曾设置「超过 1,500 字就丢弃」的规则,结果在 4,042 字输入下,7 台设备中有 3 台的摘要被整段丢弃。GPU 输出长度因机而异,是否触发上限变成了运气问题。重复字符串检测和长度上限应该分开设计。

GPU 专用模型不适合分发

GPU 专用版 .litertlm 体积更小(2.01GB),加载只要 5.4 秒,也不需要生成缓存,但有两个致命问题:

  • 没有 CPU 图。用 Backend.CPU() 打开会失败:NOT_FOUND: TF_LITE_PREFILL_DECODE not found in the model. 这意味着 GPU 出问题的设备没有任何退路。
  • 在部分 GPU 上输出崩坏。Adreno 650(Snapdragon 870)上,标题结构正常但正文被多种语言的碎片填满;同设备同代码用通用版则正常。

体积增加 0.58GB、首次加载变慢,换来的是能在更多设备上工作。面向广泛分发时选通用版。

想确认一个 .litertlm 里包含什么,可以看文件头部的字符串:

LC_ALL=C head -c 8192 model.litertlm | strings -n 4

NPU 目前没有被使用

启动日志里能看到 LiteRT 尝试注册 NPU、GPU、CPU 三个加速器,只有 NPU 失败:

W litert : [npu_registry.cc:34] NPU accelerator could not be loaded and registered: kLiteRtStatusErrorInvalidArgument
I litert : [gpu_registry.cc:109] Statically linked GPU accelerator registered.
I litert : [cpu_registry.cc:75] XNNPACK CPU accelerator registered.
W litert : [compiled_model.cc:967] You should provide the `DispatchLibraryDir` option to use NPU.
I tflite : Loaded OpenCL library with dlopen.

即使是在带 TPU 的 Pixel 8(Tensor G3)上也是同样的日志。指定 Backend.GPU() 时走的是 OpenCL 的 GPU 路径,NPU 并未参与。NPU 有使用方式,但需要按 SoC 预编译模型,且模型与 SoC 的组合有限。用一个模型文件覆盖多种设备时,现实的选择仍是 GPU 与 CPU。

测量本身的偏差

LLM 推理会持续给设备施压,测量过程中设备会发热,温度升高后系统降频,处理变慢。上面这些数字都包含了发热降频的影响,尤其是耗时数分钟的长输入测量,偏差可能更大。此外多数数据只测了一次,没有评估逐次波动,应当作量级参考而非精确基准。

工程上的总原则

把上面这些点归纳起来,核心只有一句:在自己手上的一台设备上能跑,不代表在别的设备上也能一样跑。 接入端侧 LLM 时,尽早拿多台设备测试,尤其是性能较低的机型。缓存预热、GPU 探测、后端回退、上下文额度、模型版本选择,这些都不是可选的优化项,而是让功能在真实设备群上可用的必要工作。