
在 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 峰值:
| maxNumTokens | PSS 峰值 |
|---|---|
| 不指定 | 2,716 MB |
| 8192 | 2,942 MB |
| 16384 | 3,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 5G | 44.7 分 | 27.6 分 | CPU 快 1.6 倍 |
| Mali-G68 / Galaxy A54 5G | 21.4 分 | 21.5 分 | 基本持平 |
| Mali-G715 / Pixel 8 | 13.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 探测、后端回退、上下文额度、模型版本选择,这些都不是可选的优化项,而是让功能在真实设备群上可用的必要工作。