RTranslator离线模型部署完全指南：如何5分钟搞定1.2GB模型安装，告别卡在3%的进度条-平芜编程栈

RTranslator离线模型部署完全指南：如何5分钟搞定1.2GB模型安装，告别卡在3%的进度条

【免费下载链接】RTranslatorOpen source real-time translation app for Android that runs locally项目地址: https://gitcode.com/GitHub_Trending/rt/RTranslator

你有没有被这个画面劝退过：RTranslator装好之后，首启页面是一条停在 3% 纹丝不动的下载进度条，手机在桌上充了两小时电，它还在慢慢爬？RTranslator 是一款完全本地运行的开源 Android 实时翻译应用，语音识别和文本翻译全部在手机上完成，数据不离开设备——代价是首次启动必须装下 10 个模型文件，总计约 1.2GB。下载源离你越远，这个"一次性投入"就越像一场灾难。这篇文章给你一套项目官方支持的RTranslator 离线模型部署办法：5 到 10 分钟装完，全程不用陪跑进度条。

先看懂它到底在下载什么：1.2GB 从何而来

RTranslator 的翻译引擎是 Meta 的 NLLB-Distilled-600M，语音识别用的是 OpenAI 的 Whisper-Small-244M。项目把两个模型转成 ONNX 格式并做了 INT8 量化、KV 缓存分离等优化，内存占用从约 3.9GB 压到约 2.2GB，翻译执行时间缩短约 4 倍——但文件总大小依然接近 1.2GB。

下载页面上只显示一条总进度条，实际上应用是逐个下载下面 10 个.onnx文件的，每下载完一个就会先校验、再迁移到应用私有目录，然后才开始下一个。任何一环卡住，整个队列就停在原地：

文件名	负责模块	大致体积
`NLLB_cache_initializer.onnx`	翻译缓存初始化	约 23MB
`NLLB_decoder.onnx`	翻译解码器	约 167MB
`NLLB_embed_and_lm_head.onnx`	嵌入层与语言模型头	约 488MB
`NLLB_encoder.onnx`	翻译编码器	约 248MB
`Whisper_cache_initializer.onnx`	语音识别缓存初始化	约 14MB
`Whisper_cache_initializer_batch.onnx`	批处理语音识别缓存	约 14MB
`Whisper_decoder.onnx`	语音识别解码器	约 169MB
`Whisper_detokenizer.onnx`	语音识别解标记器	约 0.5MB
`Whisper_encoder.onnx`	语音识别编码器	约 86MB
`Whisper_initializer.onnx`	语音识别初始化器	约 0.1MB

💡 完整的下载地址和体积定义在源码 DownloadFragment.java 的DOWNLOAD_URLS数组里，全部指向项目 2.0.0 版本 release 页的附件目录。手动部署时，你要下载的就是这 10 个文件。

三条部署路线：动手前先选对路

路线	原理	适合人群	需要工具	时间成本
应用内置自动下载	首次启动时从 release 页逐个拉取	网络环境好的用户	无	视网速而定，可能数小时
手动部署（sideloading）	电脑上下好文件，U 盘式拷进手机	所有用户，最稳妥	电脑 + 数据线	5-10 分钟
ADB 命令行部署	用一条命令替代"拷贝"环节	多机/批量装机	ADB + 开发者模式	2-5 分钟

下面按推荐顺序展开。手动部署是官方文档 Sideloading.md 描述的标准做法，也是本文的主角。

手动部署的完整步骤（sideloading 五步法）

⚠️ 开始前确认两件事：① 应用版本需为2.0.3 及以上（官方从该版本起支持手动放入模型，仓库当前版本 2.1.2 完全支持）；② 手机可用存储建议1.9GB 以上——1.2GB 模型总大小，加上约 800MB 的内外存迁移余量，空间不足时应用会主动弹出警告。

步骤一：在电脑上备齐 10 个模型文件

从项目 2.0.0 版本的 release 页附件里下载全部.onnx文件（就是上一节表格里的 10 个），存到电脑一个干净的文件夹，比如models/。

💡 下载完先数一遍：必须是 10 个文件、一个不缺。缺文件或损坏的文件，应用会在部署环节单独触发真实下载，不会让你整个流程重来。

步骤二：先启动一次应用，让它"把门打开"

安装 RTranslator（如果手机里装过旧版本，先重置应用）。
启动应用，接受通知权限（该通知只用于在对话/步话机模式后台运行时提醒你）。
接受完权限后直接退出应用，不要点"继续"。

这一步的目的不是配置，而是让应用创建好存放模型的目录。

步骤三：连接电脑，把文件拷到指定路径

用 USB 数据线把手机连到刚才下载模型的电脑。
如果手机此前已连过这台电脑，请拔线重插——否则文件管理器即使刷新也看不到刚创建的文件夹。
打开手机的Android/data/nie.translator.rtranslator/files目录，把 10 个.onnx文件全部拷进去。

💡 插了 SD 卡的手机不知道放内存还是外存？看内存储存该目录下files里有没有 readme 文件：有，就放内存；没有，去 SD 卡里找同路径目录。

步骤四：重新打开应用，完成校验与迁移

重新打开 RTranslator，继续首次配置。
走到下载页面时，不要再等进度条——应用会直接从你刚放好文件的目录里读取模型，并逐个做完整性校验（进度区显示的是"完整性校验 xxx"而不是"正在下载"）。只有校验失败的损坏文件才会真正联网下载。
全部通过后，files目录里那 10 个文件会自动消失：它们被搬进了应用私有存储，从此你只需用手机管应用，不用管文件。

手动部署全流程一图看懂

进阶：用 ADB 把"拷贝"环节变成一条命令

ADB 部署和手动部署唯一的区别，就是步骤三从"用文件管理器拖文件"换成一条push命令。目录仍必须由步骤二预先创建，顺序不能省。手机开启 USB 调试后：

# 确认设备已被识别 adb devices # 一次性推送全部模型文件到目标目录 adb push ./models/*.onnx /sdcard/Android/data/nie.translator.rtranslator/files/ # 回看文件数量和大小，确认 10 个文件都到位 adb shell ls -l /sdcard/Android/data/nie.translator.rtranslator/files/

⚠️ 如果adb push报"目录不存在"，十有八九是步骤二没做——目录只会在应用首次启动时生成，ADB 帮不了你造目录。

部署成功的验证：看这 3 个信号

怎么判断模型真的装好了？对照下面三个现象：

下载页面的进度区显示"完整性校验"字样，而不是"正在下载 xxx.onnx"；
files目录里的 10 个.onnx文件逐个消失（迁移到应用私有目录是成功标志，不是异常）；
应用跳入加载页，随后进入主界面，对话模式、步话机模式和文本翻译模式都能正常选择语言。

离线部署常见的几种错误及处理办法

界面提示	含义	你该做什么
下载出错（error_download）	某个文件的网络下载任务失败	检查网络后点界面重试按钮；或直接改用手动部署绕开下载
迁移出错（error_transfer）	文件从外存搬到应用私有存储的中途被中断	保持应用开着重试；如果插着 SD 卡，先别拔
模型加载出错（error_models_loading）	模型文件损坏或不完整	重启应用；仍不行就点修复按钮，只会重下损坏的文件，不用全部重来
缺少 TTS 引擎（error_missing_tts）	系统没有可用的 Google 文字转语音引擎	安装 Google TTS 引擎后重启应用
存储空间警告	内/外可用空间不足约 1.9GB	清理空间后再走流程，警告会随空间恢复而消失

💡 以上提示文案的出处都在 strings.xml，对照着看能帮你快速定位卡在哪一环。

装好之后的进阶调优

8GB 以下内存的手机：进设置打开"支持低质量语言"开关，Whisper 模型的内存占用会从约 0.9GB 降到约 0.5GB，代价是语音识别稍慢，换来的是不闪退（开关实现见 SupportLanguagesQuality.java）。
设备基线：官方建议稳定运行至少6GB RAM，存储预留 2GB 以上更从容。
装完就断网：模型全部在本地推理，之后拔卡、飞行模式都能正常翻译，这正是 RTranslator 的核心价值。

备选方案：把下载源换成镜像（长期用户）

如果你要反复重装应用，或者要给一批手机装机，可以一劳永逸地把应用内置的下载地址改成镜像目录：10 个下载 URL 硬编码在 DownloadFragment.java 中，共享同一个前缀（项目 release 页的 2.0.0 目录）。做法是用 APK 编辑工具反编译 APK，把 dex 里的公共前缀字符串替换为镜像站的对应目录，再重新打包签名安装。