早些年做语音产品总觉得离线识别和合成是稀罕事直到真把 sherpa-onnx 跑在 Android 上才意识到本地 ASR / TTS 的门槛可以压得非常低。用云端方案当然省事但网络一抖就抓瞎还会带来延迟和隐私问题。这阵子我重新把模型塞进手机里基于 sherpa-onnx 做了一套完整流程从 ASR 到 TTS 都离线可用识别快、合成稳彻底摆脱了服务器依赖。这篇博客就聊聊整个处理过程中最关键的工程决策和实操细节包括模型怎么选、Android 工程怎么配、音频流怎么喂、推理结果怎么用以及那些真机调试时才暴露出来的坑。适合准备给 App 增加离线语音能力的移动端开发也对做边缘推理的语音工程师有参考价值。1. 为什么值得把 ASR/TTS 模型搬到本机三个绕不开的现实问题1.1 云端语音方案的隐性成本很多团队一开始都倾向于用云端 API因为接入简单识别率也漂亮。但只有当用户开始在高铁上、地下车库、弱网环境里使用你的功能时问题才会集中爆发。丢包、延迟、超时都会让原本流畅的对话变得断断续续用户录了一段话却迟迟得不到识别结果体验非常糟糕。云端的网络请求还会带来流量消耗。大部分语音识别 API 需要上传完整音频短则几秒钟长则一两分钟按录音时长计费。如果产品里大量使用语音输入这笔流量费会实实在在压在用户身上而 TTS 功能如果要每次播放都从网络拉取合成音频同样会产生重复流量和延迟等待。隐私也是一个敏感点。在某些场景下语音内容会涉及账号密码、身份证号、地址等个人信息一旦用户意识到自己的录音要传到服务器做处理心理门槛就会抬高甚至直接放弃使用。把这些能力搬回本机录音从头到尾不离开设备是实打实的产品卖点尤其适合健康、金融、会议记录等对数据敏感的场景。1.2 sherpa-onnx 在边缘推理生态里的位置有人会问ONNX Runtime 本身就能跑模型为什么还要引入 sherpa-onnx答案在于所有语音相关的脏活累活都有人替你做了。语音识别不是丢一个音频进去就能出文本的简单过程它至少包含特征提取、声学模型、解码器三个环节还涉及流式处理、端点检测、标点恢复语音合成同样需要处理音素、时长、音高和最终波形生成。直接用 ONNX Runtime你得自己实现这些算法还要处理不同模型格式之间的兼容问题。sherpa-onnx 是一个专门面向移动端和嵌入式设备的语音推理工具包它把上面这些模块统一封装成稳定的 API。你只需要配置好模型路径调用一个识别或合成方法剩下的采样率变换、特征提取、解码流程全部在内部处理。它同时支持 ASR 和 TTS底层模型可以是多种类型的 ONNX 模型换模型时不需要改业务代码这在实际项目中省去大量调试时间。它还有一个好处是运行时依赖干净。不需要额外安装 Python 环境Android 端只引入一个动态库和几个 Java/Kotlin 接口甚至纯 C 语言的项目也能直接用。对比某些需要捆绑数百兆底层框架的方案sherpa-onnx 对 APK 体积的影响相对可控更适合嵌入式形态的产品。1.3 本地推理带来的产品形态变化把模型塞进手机后最大的感受是产品逻辑变得非常干净。过去一个语音按钮需要先检查网络、获取 token、回调结果每一步都可能出错现在按下按钮本地立刻开始监听麦克风识别结果实时上屏TTS 合成也能在几百毫秒内开始播音所有流程都在一个进程里闭环。这也让应用可以做成真正的离线工具。比如一个语音助手类 App在没有网络的情况下依然可以完成语音唤醒、口令识别、播报回复这在车载导航、户外运动、教育学习等场景非常有用。还能把 TTS 结果缓存下来频繁重复播放的固定内容直接从缓存读取连实时合成的时间都省掉。值得一提的是移动端设备算力这些年提升很快哪怕只是中端手机跑一个中等大小的语音模型也能在 CPU 上拿到不错的实时率。sherpa-onnx 本身就针对 ARM 平台做了不少性能优化配合量化模型基本能做到“实时率小于 1”也就是处理一秒钟的音频耗时不到一秒体验上接近云端水平。2. Android 工程集成前的准备依赖、模型文件与项目骨架2.1 Gradle 依赖注入与最低版本要求在动手写代码之前先把工程环境理顺。我通常在 Android Studio 里新建一个原生项目然后通过 Maven Central 引入 sherpa-onnx 的 Android 版依赖。核心依赖坐标是io.github.k2-fsa:sherpa-onnx包含预编译的动态库和 Java 接口层。具体版本号可以在仓库页面查最新稳定版建议选你项目里验证过的版本不要每次启动都用 nightly。build.gradle 里大概是这样dependencies { implementation io.github.k2-fsa:sherpa-onnx:1.x.x }如果希望兼顾 TTS 和 ASR这一款依赖已经覆盖。项目的最低 SDK 版本建议不低于 24因为较旧版本在 JNI 库加载和音频接口上会有兼容性问题。目标 SDK 建议跟随当前主流版本不需要额外开任何敏感权限麦克风权限照常申请但所有推理都在本地完成后网络权限甚至可以不申请这对隐私审核非常有利。依赖包会自动把 so 文件打包到 APK。默认支持 arm64-v8a、armeabi-v7a 和 x86_64 三种架构。调试时建议优先用 arm64-v8a 的真机x86_64 架构主要用于模拟器但模拟器跑语音模型会比较吃力性能数据也不具参考性。2.2 模型文件下载和放置策略模型是另一块重头戏。sherpa-onnx 社区提供了很多现成的 ONNX 模型涵盖中文、英文、中英文混合等。不要一上来就下载最大的模型先看自己实际场景是命令词识别、连续大段听写还是多语种混合场景。下载下来的模型通常是一整个二进制文件后缀为.onnx大小从几十 MB 到几百 MB 不等。TTS 模型还要区分声学模型和声码器某些模型需要两个文件同时配置。把模型的路径填进配置之前务必先确认模型支持的采样率常见的是 16kHz但部分 TTS 模型要求 22.05kHz 或 44.1kHz格式不匹配时合成出来的音频会出现音调扭曲或明显噪声。放置位置建议使用 Android 的 assets 目录这样打包时比较简单但是 APK 体积会显著增加。我习惯的做法是把模型编译成下载资源在 App 首次启动时从服务端拉取并解压到私有目录比如getFilesDir()下的models文件夹避免每次升级都重新打包大文件。解压过程要放在后台线程用ModelLoader管理进度确保完成前不触发启动页跳转。2.3 初始化配置类的核心参数sherpa-onnx 的初始化核心是几个 config 类分别对应特征提取、模型信息、解码器。以 ASR 为例需要设置FeatureConfig中的采样率通常为 16000DecoderConfig中指定识别模型文件路径、tokens 文件路径以及可选的热词文件。tokens 文件是普通文本列出模型使用的全部字符标记缺少这个文件时启动会直接报错。还有一个容易忽略的参数是enable_endpoint_detection开启后识别器会在检测到停顿后自动结束一句话适合按句输出的交互场景。在流式识别中还要区分StreamingRecognizer和普通的OfflineRecognizer前者适合边说边出结果后者适合一次性喂入整段音频。初始化代码放在 Application 的onCreate()里做预加载这样用户进入语音页时模型已经常驻内存基本无等待。3. ASR 实时识别从麦克风数据流到上屏文本的完整链路3.1 获取麦克风 PCM 数据并喂给识别器Android 上标准做法是使用AudioRecord拿到原始 PCM 数据。配置采样率 16000、声道单声道、编码格式ENCODING_PCM_16BIT创建成功后用一个循环线程不停读取音频缓冲区。关键点在于读取到的字节数组必须转换成浮点数组再馈入 sherpa-onnx 的识别器。转换时把每两个字节合成一个 16 位整数再除以 32768 归一化到[-1.0, 1.0]。我最初直接用字节流喂进去识别结果全是乱码就是因为跳过了归一化。这个步骤看似简单却是整个链路里最容易翻车的地方。代码骨架大致如下int bufferSize AudioRecord.getMinBufferSize(16000, AudioFormat.CHANNEL_IN_MONO, AudioFormat.ENCODING_PCM_16BIT); audioRecord new AudioRecord(MediaRecorder.AudioSource.VOICE_RECOGNITION, 16000, AudioFormat.CHANNEL_IN_MONO, AudioFormat.ENCODING_PCM_16BIT, bufferSize); short[] rawBuffer new short[2048]; float[] floatBuffer new float[2048]; // 循环读取并喂给 recognizer.acceptWaveform()AudioSource.VOICE_RECOGNITION经过系统预处理对语音识别友好但要提醒的是部分设备在用它时增益较低如果官方测出的识别率偏低可以换用MIC并自己加前置增益。3.2 流式识别与结果回调sherpa-onnx 的流式接口设计很像手写输入法创建识别器独立实例持续调用acceptWaveform()把音频片段加入流中然后按你需要的时间间隔取出当前识别结果。我的策略是每 200ms 取一次临时结果实时上屏当端点检测触发或用户松手时调用finalResult()拿到完整句子。需要特别注意的是识别器的所有操作必须在同一个线程上进行不能在多个线程里并发调用同一个StreamingRecognizer。否则会出现内部状态错乱结果忽多忽少。通常的做法是单独开一个音频线程循环读麦克风、循环喂数据、在回调里通过 Handler 切换到主线程更新 UI。回调里拿到的结果是一段文本但实际接口还会提供一个时间戳信息。如果你做的是字幕或点读场景可以利用这个信息精确定位每个字对齐的音频位置。不过默认配置下时间戳不一定开启需要配置enable_timestamps并传入一个数组来接收。3.3 半句识别与端点检测的联动端点检测是提升交互感的重要环节。如果不开启它用户录完一句话后系统会一直等后续音频直到用户手动停止。开启后识别器会分析到语音结束的静音段自动终止当前句子并返回结果整个交互就像按下对讲机松开自动发送一样。静音阈值参数值得反复调。默认阈值在安静环境下不错但如果在车上或嘈杂的户外容易提前切断句子尾部。我通常把静音时长阈值从 1.2 秒提高到 1.8 秒同时开启rule1、rule2、rule3三组组合规则这样在噪音环境下也能较稳定地在完整句子后断句。调参时用录好的真实场景音频反复测试不要依赖测试人员和你说“大概可以”。4. TTS 离线合成从文本到扬声器的完整链路4.1 TTS 配置与模型初始化TTS 部分同样由配置类驱动核心是OfflineTtsConfig里面需要指定声学模型路径和声码器路径。某些新模型把声学模型和声码器融在一个文件里那么只需要配置一个模型路径老式 VITS 类模型则通常直接生成最终音频无需额外声码器。合成之前还要设置说话人 ID。有的模型内置多个音色比如在不同 ID 下生成不同性别的成人音或童音。即使是单音色模型也要显式传入 ID 为 0跳过默认值可能会触发边界异常。初始化 TTS 对象同样是重量级操作建议放在启动阶段做完不要每次进入页面时重新创建。代码示例val ttsConfig OfflineTtsConfig( model OfflineTtsModelConfig( vits OfflineTtsVitsModelConfig( model $modelDir/tts.onnx, tokens $modelDir/tokens.txt, speakerId 0 ) ) ) val tts OfflineTts(ttsConfig)4.2 合成过程的控制与长文本分段synthesize()方法接受文本输入返回一个音频采样数组。实际使用中不要一次性丢一大段文本进去推理时间会成倍增长而且某些模型对输入长度有上限超出后报错或截断。把文本按标点切分成长度适当的句子逐句合成再按顺序播放这是最稳妥的方案。切分逻辑不能只按逗号和句号。有一次我按句子切分后数字串被切成两半合成结果把“2024年”读成了“二十零二十四年”。建议在分段上加上正则规则比如连续数字中间不断开地名和单位前后位置尽量保留在同一个片段里。虽然这些细节看起来琐碎但直接决定合成音频听上去会不会像机器在“掰字”。合成后的音频数组一般以 16 位 PCM 格式返回。播放前需要确定采样率是多少通常与模型输出的采样率一致用AudioTrack播放时设置同样的采样率和格式。如果播放出来音调不对十有八九是采样率设置错了。4.3 AudioTrack 播放与打断控制播放 TTS 结果我推荐直接用AudioTrack而不是MediaPlayer因为它省掉写临时文件的步骤直接把字节数组写成 PCM 流。初始化时设为MODE_STREAM然后不断调用write()写入合成数据。合成是耗时操作播放是异步操作需要设计一个生产消费队列。用户可能随时打断播放比如语音助手说完话后用户立刻说了新的指令。这种情况下要停止合成线程清空播放队列再让AudioTrack执行pause()和flush()。如果不清理队列新的语音会被旧内容覆盖或重叠播放体验会变得一团糟。我踩过这个坑后专门封装了一个TtsPlayer单例统一管理播放任务、打断信号和释放资源。还有一个细节AudioTrack的输出声音默认是经过系统音效处理的如果设置了会调合成语音在下一句开始前容易出现爆音。建议在播放过程中调用AudioManager.requestAudioFocus申请短暂焦点并关闭其它音效。实测下来声音干净很多。5. 模型选择与压缩策略不要只看体积要看三段式指标5.1 不同 ASR 模型的实测对比模型选型在整个项目中影响最大也最容易只凭直觉判断。社区里能跑的中文模型不少比如基于 Paraformer 架构的中文小模型、基于 Zipformer 的通用模型、以及一些满足特殊需求的流式模型。它们的差异不仅体现在识别准确率上还体现在实时率和内存占用上。我自己的对比经验可以整理成一张表模型类型体积范围中英文支持实时率手机 CPU适合场景Paraformer 小模型50MB 左右中文为主0.5 左右命令词、短句识别Zipformer 通用模型150MB 以上中英混合0.8 左右大段听写、语音记录流式小模型30MB 左右特定领域0.3 左右实时按键对话这里说的实时率是指处理一秒音频所需的时间小于 1 意味着能跟上说话速度。实际项目中如果用户手机性能偏中低端就算实时率超过 1.2也还是勉强能用的但会有越来越大的延迟积累长时间说话以后结果明显落后。5.2 量化模型和裁剪策略ONNX 模型可以用量化工具压缩常见的是 int8 动态量化。量化后的模型体积通常缩小 3 到 4 倍推理速度也能提升一到两倍代价是识别率会轻微下降中文场景可能把相近读音的字搞得含糊不清。实际测试中如果原本准确率在 94% 以上量化后掉到 91% 左右在非专业场景下基本可接受。裁剪策略要克制。我见过有人把模型里所有的嵌入层和注意力头都减掉结果识别率直接崩盘。比较稳妥的做法是只移除确定多余的输出分支比如不使用标点恢复功能时可以把对应的后处理分支关闭或者把热词列表压缩到最精简。更有效的优化方向是调整解码器参数比如把 beam 宽度从 5 减到 3能省下不少计算量直观感受不明显。5.3 多语言混合需求的针对性处理中英文混合识别是个深坑。早期我选用一个只训练过中文的模型然后让系统识别少量英文结果“OK”被识别成“哦克”“Wi-Fi”变成“歪饭”。后来换了专门做过中英混合微调的模型情况才好起来。选模型时别只盯着备注里的“支持中文”三个字要看它是否明确提到“中英混说”或“code-switch”。如果你只需要固定英文指令更简单的办法是不换整套模型而是使用热词表。把高频词组直接写入 hotwords 文件并调高热词权重识别器会把相近结果强行拉向热词。热词表的缺点是容易误伤把“快手”写成热词后可能把“快受”“快守”都拉过去所以权重不能设得太离谱。6. 真机调试中的高频问题与排查链路6.1 识别结果全是乱码或空白先从采样率查起这是最高频的问题没有之一。现象是麦克风录了好几个字节进识别器最后返回的字符串却是空或者偶尔冒出一个无法理解的乱码。排查链路要按顺序走先确认配置里的采样率是 16000再确认AudioRecord构造时采样率也是 16000然后打日志确认每次acceptWaveform()里浮点数组的最大绝对值在 0.1 到 0.9 之间。如果值长期低于 0.05说明输入增益太小模型直接听不见如果值接近 1.0 且频繁削顶说明有噪音干扰。有一次我在自定义 ROM 的测试设备上遇到问题格式化后录音文件用系统播放器听完全正常但喂给模型就是空结果。最后发现是这个设备把AudioRecord底层的音频路由到了麦克风阵列的远场波束导致原始 PCM 相位异常。解决办法是改采样源为UNPROCESSED绕过设备的降噪和波束处理识别率立刻恢复。6.2 模型加载即闪退或 so 找不到闪退问题常见于只打包了 arm64 而测试机是老旧的 armeabi-v7a 机型。你在 Android Studio 里看安装是真装上了但一调用 JNI 就崩溃logcat 提示library not found for xxx.so。解决办法是检查 APK 里lib目录是否包含目标架构的 so 文件或者干脆在abiFilters里显式指定支持的架构。还有一个被忽略的问题是压缩对齐。如果模型文件放在 assets 里系统在加载时可能把它当成二进制资源直接映射而某些模型文件数据超过 2GB 时需要注意分区问题。在实测中发现某个 300MB 模型在低内存手机上加载时会被系统直接杀死因为同时加载了 ASR 和 TTS 两个大模型。后来调整策略ASR 模型初始化后先不预热等用户进入输入页再加载TTS 模型则延迟到第一次需要播报时初始化错开峰值内存。6.3 内存占用居高不下的排查sherpa-onnx 模型加载后内存分成三块模型本身占用的参数空间、内部特征缓冲、运行时临时张量。参数量化到 int8 后内存下降明显但运行时临时张量依然可能几十兆。性能分析工具可以抓分配到 Java 堆之外的 native 内存你会发现模型对象本身并不算在常规堆统计里。如果App整体内存压力大一个实用技巧是给识别过程设置“会话式释放”当用户结束一次识别后调用recognizer.free()释放当前流式的内部状态经常使用的模型对象可以保留但不再实际持有激活流这样能把峰值内存降下来。释放操作要在音频线程停止之后再调用避免刚释放又被写入数据导致崩溃。6.4 UI 卡顿和回调线程纪律识别结果回调发生在音频线程绝对不能在回调里直接刷新TextView。每次识别出临时结果时我用runOnUiThread或 Handler 把文本送到主线程再更新界面。有一次我图省事直接在回调里调了TextView.setText偶尔能出一次结果但多几次后就会伴随 ANR因为 Android 主线程被跨线程访问破坏。TTS 播放线程同理。播放进度更新、结束回调都要统一切回主线程。这不是 sherpa-onnx 特有的问题而是所有音视频处理项目里最常见的纪律问题。宁可多写两个 Handler也不要让线程安全问题在下一次崩溃里等着你。7. 从“能跑”到“好用”进阶优化和可扩展方向7.1 冷启动预加载与模型预热模型加载时间通常是 TTS/ASR 页面最大的等待来源。一个简单的预热方案是在 Application 启动后切入后台线程把核心模型实例创建出来但不调用任何推理。预热还有一个隐藏作用让操作系统提前分配足够连续内存避免真正调用时发生明显 GC。实测中预加载后进入语音页面速度从 1.5 秒左右降到 0.2 秒以内体验完全是两个档位。要注意的是Application 级预加载会占用全局内存如果App还有地图、视频等大内存模块需要做好权衡。对于内存吃紧的设备可以做一个开关只有用户打开过语音页面才在后台缓存模型实例下次再进直接命中。7.2 把 ASR/TTS 封装成系统级能力当模型在应用内稳定工作后可以尝试进一步扩展。比如把 ASR 封装成一个前台服务配合通知栏常驻这样别的页面也能随时调用语音输入也可以定义一个全局的 TTS 服务统一管理朗读队列让阅读类、消息播报类界面共享同一个语音引擎。这种封装对代码结构要求更高需要把模型实例、音频线程、播放控制器全部交给单例管理同时处理好生命周期边界。我在项目中用MediaSession做播放控制系统媒体面板可以直接暂停合成语音用户锁屏后也能通过耳机键打断播报体验接近系统级语音服务。7.3 结合 VAD 与语义纠错的延展思路sherpa-onnx 自带的基础能力足够做很多玩法但要做成智能助理还需要叠加自己的逻辑。加入 VAD 端点检测后用户不需要一直按住说话按钮语音助手可以像对讲机一样自动判断开始和结束这个层级的体验已经相当接近专业语音产品。识别结果上屏后可以再接一层语义理解。本地跑一个小型语义分类模型把转写文本映射到“打开音乐”“关闭屏幕”“设置提醒”等意图再分发给不同的业务模块。整个过程全部离线完成不需要把原始录音发出去既快又保护隐私。这已经是从“塞进手机”到“变成手机能力”的进阶地图了也是我认为未来所有语音应用都会走向的形态。