屏译端侧LLM实现原理:llama.cpp Android移植、CMake构建与多序列批推理设计

原创2026-10-16 21:50:421,331 阅读
文章标签:移动开发人工智能大模型本地部署计算机视觉语音

屏译端侧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翻译游戏画面对比:左原图右叠加中文译文

端侧 LLM 翻译结果直接叠加在游戏画面上,全程无需联网

llama.cpp 移植思路:submodule 直读 + CMake 运行时打补丁

移植的核心原则是保持上游 submodule 零改动。第三方源码通过 git submodule 固定在 third_party/llama.cpp/,构建脚本 CMakeLists.txt 从它直读源码,git submodule update --remote 即可同步上游。

那么屏译自己的功能(性能统计、会话重置、多序列接口)怎么加进去?答案是在 CMake 配置期做字符串级打补丁:

  1. 精确匹配守卫:file(READ) 读入上游的 ai_chat.cpp,对每一段"原始代码"做 string(FIND) 精确匹配,匹配失败就 message(FATAL_ERROR) 直接中止配置。这样上游一旦改了结构,会在构建期显式报错,而不是静默丢功能。
  2. 生成新翻译单元:替换/追加完成后,把整份源码写入构建目录的 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 侧的核心流程分四步:

  1. 序列规划:sequence 0 固定保留可复用的 system prompt KV,sequence 1~8 各自独立(llama_multi_sequence.inc)。每序列独立创建 common_sampler,互不串扰。
  2. 共享前缀复用:先对所有 prompt 做 token 级最长公共前缀计算,公共部分只在 sequence 0 上 decode 一次,再用 llama_memory_seq_cp 把这段 KV 拷贝给其余序列(llama_multi_sequence.inc)。由于各 prompt 共享同一 system 模板,这一步省掉的 prefill 相当可观。
  3. 分序列 prefill:各序列剩余 token 拼进同一个 llama_batch,只有每序列最后一个 token 标记 want_logits,一次 decode 全部就位(llama_multi_sequence.inc)。
  4. 批量生成循环: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 态自愈,这三件事决定了端侧大模型"能不能被用户每天用起来"。
登录后查看全文
overlay-translator