屏译端侧LLM实现原理:llama.cpp Android移植、CMake构建与多序列批推理设计
屏译端侧LLM实现原理:llama.cpp Android移植、CMake构建与多序列批推理设计
屏译(overlay-translator)是一款无需 ROOT 的开源 Android 屏幕实时翻译工具,其端侧 LLM 模块基于 llama.cpp 实现 Android 移植,把 GGUF 大模型跑在手机 CPU/GPU 上,让游戏、视觉小说和漫画翻译完全离线完成。本文带你完整拆解这条技术链路:CMake 构建如何不动一行 submodule 源码完成移植,以及多序列批推理如何把一帧 OCR 出的多个文本块合并成一次推理。
端侧 LLM 在屏译流水线中的位置
屏译的完整流程是:MediaProjection / Shizuku 截屏 → 端侧或云端 OCR → 翻译引擎(机器翻译或 LLM)→ 悬浮窗叠加显示。端侧 LLM 是其中"翻译引擎"的一种选项,面向两个内置模型:
| 模型 | 定位 | 体积 | 语言支持 |
|---|---|---|---|
| Sakura-1.5B (Qwen2.5, Q5KS) | 日漫 / 视觉小说 / galgame 专用 | 约 1.26 GB | 仅日语 → 简中 |
| Hy-MT2-1.8B (Q4_K_M) | 通用多语种离线翻译 | 约 1.13 GB | 跟随设置 |
两者的元数据(GGUF 文件名、量化选择理由、语言限制)集中定义在 LlmModelKind.kt。量化档位的选择很克制:Hy-MT2 官方还发布了 2bit 版本,但因为依赖未合入 llama.cpp 主线的 kernel,屏译坚持选 Q4_K_M,避免用户下载后加载失败。
端侧 LLM 翻译结果直接叠加在游戏画面上,全程无需联网
llama.cpp 移植思路:submodule 直读 + CMake 运行时打补丁
移植的核心原则是保持上游 submodule 零改动。第三方源码通过 git submodule 固定在 third_party/llama.cpp/,构建脚本 CMakeLists.txt 从它直读源码,git submodule update --remote 即可同步上游。
那么屏译自己的功能(性能统计、会话重置、多序列接口)怎么加进去?答案是在 CMake 配置期做字符串级打补丁:
- 精确匹配守卫:
file(READ)读入上游的ai_chat.cpp,对每一段"原始代码"做string(FIND)精确匹配,匹配失败就message(FATAL_ERROR)直接中止配置。这样上游一旦改了结构,会在构建期显式报错,而不是静默丢功能。 - 生成新翻译单元:替换/追加完成后,把整份源码写入构建目录的
gameocr_ai_chat.cpp参与编译,submodule 本身不被污染。
屏译注入的能力包括:
- 日志边界:Debug 版接入 Android Logcat,Release 版安装 no-op 回调并连格式化参数都不求值(gameocr_logging.h);
- 会话重置修正:每个 OCR 文本块是独立翻译请求,保留 system prompt、丢弃其余对话历史(CMakeLists.txt);
- 性能打点:在 prefill / 达到长度上限 / 生成结束等路径注入
llama_perf_context统计,输出 Prefill 与 Decode 的 tok/s; - 只读指标 JNI:追加了 6 个
Java_com_gameocr_app_llm_LlamaPromptMetrics_*导出函数,让 Kotlin 侧能查询上下文大小、批次容量、序列容量、system prompt token 数(CMakeLists.txt); - 多序列批推理:把独立的 llama_multi_sequence.inc 整段追加进同一翻译单元,复用其进程级的 model / context / 对话模板(CMakeLists.txt)。
一键构建:Gradle 与 CMake 参数全景
原生构建由 llama-android/build.gradle.kts 驱动,Kotlin binding 源码通过 srcDirs 直指 submodule,本模块不维护任何副本(build.gradle.kts)。关键构建决策如下:
| 参数 / 决策 | 取值 | 原因 |
|---|---|---|
abiFilters |
仅 arm64-v8a |
与 :app 模块一致;非 arm64 在 CMake 层直接 FATAL_ERROR(CMakeLists.txt) |
GGML_VULKAN |
ON | 支持 GPU 卸载;CMake 里额外桥接 NDK 自带的 SPIR-V headers 与 glslc,免去安装 Vulkan SDK(CMakeLists.txt) |
GGML_CPU_ALL_VARIANTS |
ON | 必须:BACKEND_DL=ON 模式下 ggml 靠 dlopen 扫描多变体 .so,少了会报 "no backends are loaded" 导致模型加载必败 |
GGML_CPU_KLEIDIAI / GGML_OPENMP |
arm64 下开启 | 启用 KleidiAI 与 OpenMP 提升 CPU 推理吞吐 |
GAMEOCR_NATIVE_LOGCAT |
Debug=ON,Release=OFF | 编译期常量决定日志开关,系统属性无法在 Release 上"翻案"(build.gradle.kts) |
推理线程数由 llama_thread_policy.cpp 按可用核数映射(≤4 核用 2 线程、≤6 核用 4 线程、更多则 6 线程),Kotlin 侧通过 Os.setenv 把线程数、Vulkan 开关、采样参数注入环境后触发 loadModel,见 LlamaEngineHolder.kt。
多序列批推理:8 路独立请求共享一次 llama_decode
一帧游戏画面 OCR 出 8 段对话时,逐段串行推理意味着 8 倍调度开销。屏译的方案是多序列批推理:把 N 段文本挂到同一个 llama 上下文的不同 sequence 上,用一次 llama_decode 批量推进。
Kotlin 侧入口是 LlamaMultiSequence.kt:generate(prompts, predictLengths) 校验 1~8 条序列后经 JNI 调 native,并顺带取回一组性能指标(init / prefill / decode 耗时、输入输出 token 数)。native 侧的核心流程分四步:
- 序列规划:sequence 0 固定保留可复用的 system prompt KV,sequence 1~8 各自独立(llama_multi_sequence.inc)。每序列独立创建
common_sampler,互不串扰。 - 共享前缀复用:先对所有 prompt 做 token 级最长公共前缀计算,公共部分只在 sequence 0 上 decode 一次,再用
llama_memory_seq_cp把这段 KV 拷贝给其余序列(llama_multi_sequence.inc)。由于各 prompt 共享同一 system 模板,这一步省掉的 prefill 相当可观。 - 分序列 prefill:各序列剩余 token 拼进同一个
llama_batch,只有每序列最后一个 token 标记want_logits,一次 decode 全部就位(llama_multi_sequence.inc)。 - 批量生成循环:
while (batch.n_tokens > 0)循环里,每轮 decode 后对每个未完成的序列独立采样;某序列遇到 EOG、token 上限或行数上限就退出,其余序列继续(llama_multi_sequence.inc)。行数上限特别处理了 token 边界——按字节切分、把超出行数的半截 token 丢弃,可选在输出末尾追加<|gameocr_line_limit|>哨兵标记,让上层能识别"译文被截断"并降级处理。
Kotlin 侧的 LocalLlmNativeBatchPolicy.kt 负责把一帧的文本块切成"装得下"的批次:同时校验每序列上下文、统一 KV 总量、JNI 序列容量(8)与 prefill 批次 token 上限四个约束,支持 1/2/4/8 四档批量大小,超约束的项自动落回小批次,保证任何输入都不会撑爆 native 侧容量。
引擎生命周期:预热、复用与自愈
模型常驻是端侧 LLM 体验的关键。LlamaEngineHolder.kt 作为全进程单例保证:
- Background prewarm:选择本地翻译模型后,悬浮翻译 Service 启动即调
ensureLoaded预热;预热未完成时首次翻译复用同一把Mutex等待,绝不重复加载; - Idle unload:每次使用重置 5 分钟倒计时,到点自动
cleanUp释放 440~1024 MB 内存。注意只卸权重不destroy——binding 的 engine 实例销毁后无法再次加载; - 状态自愈:上一次加载失败会让 engine 卡在
Error态、后续loadModel全部被拒;ensureLoaded每次先检查状态,Error 态先cleanUp拉回Initialized再加载; - 串行保护:binding 的
sendUserPrompt一次只能处理一段请求,屏译用LlamaEngineLifecycleGate强制端侧请求串行,覆盖推理、token 统计、模型切换与卸载,保护 native 进程级状态。
上手体验:离线跑起来的翻译效果
悬浮窗锁定状态下,端侧 LLM 的译文随画面实时更新,可拖动到任意位置
安装只需在应用内下载对应 GGUF 模型(Android 13+,仅 arm64 设备),设置里选择本地翻译引擎后即可离线工作。README 附有真实设备的基准数据:Sakura 单段约 7~9 秒、Hy-MT2 约 5~8 秒起,长页面多段时会用到上述批量能力压缩总耗时,详见 README.md 的"端侧翻译基准测试"一节。
弧形菜单支持循环翻译、区域选择等快捷操作,与端侧翻译引擎无缝配合
小结:这套设计给端侧 AI 项目的三点启示
- 不动 submodule 的移植方式:CMake 配置期"精确匹配 + 字符串打补丁 + 生成新翻译单元",把同步上游的成本从改代码降为跑一次构建;
- 批量约束前置到规划层:把 KV 容量、批次上限、序列容量等约束全部在 Kotlin 规划层算清楚,native 层只做校验与执行,失败原因清晰可定位;
- 生命周期与状态机同等重要:预热、空闲卸载、Error 态自愈,这三件事决定了端侧大模型"能不能被用户每天用起来"。


