：sherpa-onnx集成ASR與TTS全指南)
1. 端側語音交互的現狀與 sherpa-onnx 的切入點把語音識別和語音合成塞進手機這件事放在三五年前還屬于“實驗室里跑得動、真機上跑不動”的范疇。我最早接觸端側語音是在一個離線字幕工具的項目里當時用某款云端 ASR 接口網絡一抖字幕就斷用戶罵聲一片。后來轉向端側方案試過 TensorFlow Lite 的語音模型、也試過 PyTorch Mobile 的量化版本踩了不少坑直到遇到 sherpa-onnx才算找到一個在 Android 上真正能落地的方案。sherpa-onnx 是 k2-fsa 團隊開源的一套端側語音推理框架底層基于 onnxruntime支持流式和非流式 ASR、TTS、VAD、說話人分離等任務。它的核心價值在于模型體積小、推理速度快、跨平臺一致性好而且提供了完整的 Android 預編譯庫和 Kotlin/Java API。換句話說你不需要自己從 PyTorch 導出 ONNX、不需要手寫 JNI 膠水層、不需要折騰 NDK 編譯直接拿 AAR 包就能在 Android 項目里跑起來。這篇文章面向的是有一定 Android 開發(fā)基礎、想在 App 里集成離線語音能力的開發(fā)者。不管你是想做語音輸入法、離線字幕、語音助手還是想做 TTS 朗讀功能sherpa-onnx 都能給你一條相對平滑的路徑。我會從架構設計、模型選型、實操集成、性能調優(yōu)、問題排查幾個維度把我在實際項目中積累的經驗完整地分享出來。2. 為什么選 sherpa-onnx 而不是其他端側方案2.1 端側語音推理的三種主流路線對比在決定用 sherpa-onnx 之前我認真對比過市面上幾條主流路線這里把關鍵差異整理成表格方便你根據自己的場景做判斷。方案底層引擎模型格式Android 支持流式 ASRTTS 支持集成難度sherpa-onnxonnxruntimeONNX官方 AAR支持支持低TensorFlow LiteTFLiteTFLite官方庫需自行實現有限中PyTorch MobilePyTorchTorchScript官方庫需自行實現有限中高云端 API服務端不涉及HTTP 調用支持支持低但依賴網絡從表格能看出來sherpa-onnx 最大的優(yōu)勢是“開箱即用”——它把流式 ASR 和 TTS 這兩塊最難啃的骨頭都封裝好了而且模型格式統(tǒng)一為 ONNX社區(qū)里現成的模型也最多。TensorFlow Lite 和 PyTorch Mobile 雖然也是端側方案但流式推理的邏輯需要你自己寫TTS 的支持也不如 sherpa-onnx 成熟。2.2 sherpa-onnx 的架構設計思路sherpa-onnx 的架構可以分成三層來理解。最底層是 onnxruntime負責實際的矩陣運算和算子執(zhí)行中間層是 sherpa-onnx 自己實現的語音處理邏輯包括特征提取fbank、解碼器greedy search 或 beam search、端點檢測VAD等最上層是各語言的 API 封裝Android 這邊提供的是 Kotlin/Java 接口。這種分層設計的好處是模型和推理引擎解耦你可以隨時替換 ONNX 模型而不需要改代碼同時特征提取和解碼邏輯用 C 實現性能比純 Java 實現高一個數量級。我在實測中對比過同樣的模型sherpa-onnx 的 C 解碼比用 Java 自己寫的貪心解碼快了將近 3 倍尤其是在長語音場景下差距更明顯。2.3 模型選型的核心考量sherpa-onnx 支持的 ASR 模型主要有幾類Paraformer中文效果好、Zipformer中英混合強、Whisper多語言但體積大、Conformer通用。TTS 模型則有 VITS、Matcha、Kokoro 等。選型時我一般看三個指標模型體積、實時率RTF、識別準確率。以中文場景為例Paraformer 的小模型大概 70MB 左右RTF 在驍龍 8 Gen 1 上能跑到 0.15 以下也就是說 10 秒的語音 1.5 秒就能出結果。Zipformer 的中英混合模型大概 120MBRTF 稍高但也在 0.3 以內。Whisper tiny 雖然只有 40MB但中文識別準確率明顯不如 Paraformer而且不支持流式。所以如果你的場景是純中文離線識別Paraformer 是首選如果需要中英混說Zipformer 更合適。注意模型體積和準確率永遠是一對矛盾。我見過有開發(fā)者為了追求小體積用了 Whisper tiny結果中文識別錯字率高達 15%用戶體驗極差。建議在體積和準確率之間找平衡點一般 70-150MB 是比較合理的區(qū)間。3. Android 集成實操從零到跑通第一個 Demo3.1 環(huán)境準備與依賴引入先說一下我的開發(fā)環(huán)境Android Studio Hedgehog 以上、Gradle 8.x、minSdk 24、targetSdk 34、NDK 版本 25.2。sherpa-onnx 的 AAR 包對 NDK 版本有要求太低會報鏈接錯誤太高也可能有兼容問題25.x 是比較穩(wěn)的區(qū)間。依賴引入有兩種方式。第一種是直接從 Maven Central 拉取dependencies { implementation(com.k2fsa.sherpa.onnx:sherpa-onnx:1.10.0) }第二種是手動下載 AAR 放到 libs 目錄適合需要定制編譯或者內網環(huán)境的情況。我一般推薦第一種版本管理方便升級也簡單。引入依賴后需要在build.gradle里加上 abiFilters只保留 arm64-v8a 和 armeabi-v7a這樣能顯著減小 APK 體積android { defaultConfig { ndk { abiFilters listOf(arm64-v8a, armeabi-v7a) } } }3.2 模型文件的放置與加載策略模型文件不能放在 assets 里直接讀因為 onnxruntime 需要文件路徑而不是 InputStream。我的做法是在 App 首次啟動時把 assets 里的模型拷貝到filesDir下之后直接從文件系統(tǒng)加載。拷貝邏輯要注意用后臺線程并且加一個版本標記模型更新時重新拷貝。fun copyModelIfNeeded(context: Context, modelName: String) { val targetDir File(context.filesDir, sherpa-models/$modelName) val versionFile File(targetDir, version.txt) val currentVersion 1.0 if (versionFile.exists() versionFile.readText() currentVersion) return targetDir.mkdirs() context.assets.open(models/$modelName).use { input - File(targetDir, model.onnx).outputStream().use { output - input.copyTo(output) } } versionFile.writeText(currentVersion) }模型加載本身是同步的但耗時可能到幾百毫秒建議放在 Application 啟動時或者用懶加載。我實測 Paraformer 小模型加載大概 200msZipformer 大概 400msTTS 的 VITS 模型大概 300ms。如果放在主線程會明顯卡頓一定要放到子線程。3.3 流式 ASR 的完整調用流程流式 ASR 的核心是“邊錄邊識別”需要把錄音線程和識別線程分開。錄音線程負責從 AudioRecord 讀取 PCM 數據識別線程負責把數據喂給 sherpa-onnx 的 stream 對象。val config OnlineRecognizerConfig( featConfig FeatureConfig(sampleRate 16000, featureDim 80), modelConfig OnlineModelConfig( transducer OnlineTransducerModelConfig( encoder $modelDir/encoder.onnx, decoder $modelDir/decoder.onnx, joiner $modelDir/joiner.onnx ), tokens $modelDir/tokens.txt, numThreads 2, provider cpu ), decodingMethod greedy_search ) val recognizer OnlineRecognizer(config) val stream recognizer.createStream()錄音線程每次讀到 1600 個采樣點100ms就調用stream.acceptWaveform(samples, 16000)然后調用recognizer.isReady(stream)判斷是否有可解碼的幀有的話就recognizer.decode(stream)再通過recognizer.getResult(stream)拿到當前識別結果。這套流程看起來簡單但有幾個坑我踩過一是采樣率必須是 16000錄音時如果設備默認是 44100 需要重采樣二是 numThreads 不要設太大2 線程在多數手機上已經夠用設 4 反而會因為線程調度開銷導致延遲增加。3.4 TTS 合成的參數調優(yōu)TTS 這邊相對簡單核心是文本前端和聲學模型的配合。sherpa-onnx 的 TTS 支持中英文混合但需要模型本身支持。VITS 中文模型大概 60MB合成一句話10 個字左右耗時在 200-400ms 之間。val ttsConfig OfflineTtsConfig( model OfflineTtsModelConfig( vits OfflineTtsVitsModelConfig( model $ttsModelDir/model.onnx, tokens $ttsModelDir/tokens.txt, lexicon $ttsModelDir/lexicon.txt ), numThreads 2 ), ruleFsts $ttsModelDir/rule.fst ) val tts OfflineTts(ttsConfig) val audio tts.generate(你好歡迎使用語音合成, sid 0, speed 1.0f)speed 參數控制語速1.0 是正常0.8 偏慢1.2 偏快。sid 是說話人 ID多說話人模型才有意義。生成的 audio 是 FloatArray需要轉成 16bit PCM 再用 AudioTrack 播放。這里有個細節(jié)AudioTrack 的 buffer size 要設夠太小會斷音我一般設成采樣率的 0.5 秒對應的字節(jié)數。4. 性能調優(yōu)與真機適配經驗4.1 不同芯片平臺的實測數據我在幾臺不同芯片的手機上跑了同一套 Paraformer 流式模型記錄下 RTF 和首字延遲數據如下芯片平臺代表機型檔位RTF首字延遲內存占用驍龍 8 Gen 2旗艦0.08180ms180MB驍龍 778G中端0.18320ms160MB天璣 8100中高端0.12240ms170MB驍龍 665入門0.45680ms140MB從數據能看出來旗艦機和中端機的差距主要在首字延遲上RTF 差距反而不大。入門機驍龍 665 這個級別的 RTF 到了 0.45意味著 10 秒語音要 4.5 秒才能出結果體驗就比較勉強了。所以如果你的 App 要覆蓋低端機建議用更小的模型或者干脆只在中高端機上開啟流式識別。4.2 內存與線程的平衡策略sherpa-onnx 默認用 2 線程這個設置在中高端機上表現最好。我試過在驍龍 778G 上把 numThreads 調到 4RTF 從 0.18 降到 0.15但首字延遲反而從 320ms 漲到 380ms原因是線程創(chuàng)建和同步的開銷增加了。所以我的建議是除非你的場景對吞吐量要求極高比如批量處理錄音文件否則 numThreads 保持 2 就行。內存方面模型加載后會常駐內存Paraformer 大概占 150-180MB。如果同時加載 ASR 和 TTS內存占用會到 300MB 左右。在 4GB 內存的低端機上這個占用已經比較危險了可能觸發(fā)系統(tǒng)殺后臺。我的做法是 ASR 和 TTS 按需加載用完就釋放雖然重新加載有幾百毫秒開銷但能顯著降低內存壓力。4.3 音頻采集的坑與解決方案Android 的 AudioRecord 在不同設備上行為不一致這是端側語音最頭疼的問題之一。我遇到過幾種典型情況某些機型默認采樣率是 48000 而不是 16000需要手動重采樣某些機型在藍牙耳機連接時采樣率會變還有的機型在錄音時會有明顯的底噪。重采樣我一般用線性插值雖然音質不如 sinc 插值但計算量小對識別準確率影響可以忽略。底噪問題可以通過 VAD 過濾sherpa-onnx 自帶的 VAD 模型silero-vad效果不錯能在識別前把靜音段切掉既省算力又提高準確率。提示錄音權限在 Android 6.0 以上需要動態(tài)申請而且從 Android 11 開始如果 App 在后臺錄音需要額外聲明 foregroundServiceType。這些系統(tǒng)限制一定要提前處理否則用戶反饋“錄不了音”你排查半天才發(fā)現是權限問題。5. 常見問題排查與避坑指南5.1 模型加載失敗的幾種典型原因模型加載失敗是最常見的問題我整理了一個排查表報錯信息可能原因解決方法Failed to load model文件路徑錯誤檢查 filesDir 下文件是否存在Invalid ONNX model模型文件損壞重新從官方倉庫下載Unsupported operatoronnxruntime 版本不匹配升級 sherpa-onnx 到最新版Out of memory模型太大換小模型或降低 numThreadsTokens file not foundtokens.txt 缺失確認模型目錄包含所有文件其中“Unsupported operator”這個坑我踩過最深。當時用了一個自己導出的 ONNX 模型里面有個算子 onnxruntime 不支持報錯信息又很模糊排查了一整天才發(fā)現是導出時用了 opset 17 而 onnxruntime 只支持到 15。后來我養(yǎng)成了一個習慣導出模型后先用 onnxruntime 的 Python 版跑一遍確認沒問題再放到 Android 上。5.2 識別結果異常的調試思路識別結果異常一般分三種完全沒結果、結果亂碼、結果延遲高。完全沒結果通常是音頻格式不對檢查采樣率、聲道數、位深是否匹配。結果亂碼多半是 tokens.txt 和模型不匹配或者模型本身是英文的卻用來識別中文。結果延遲高則要看 RTF如果 RTF 超過 0.5 就要考慮換模型或降 numThreads。我一般會在調試階段把每幀的識別結果打日志觀察是從第幾幀開始出字的。正常情況下流式模型在 300-500ms 內應該出第一個字如果超過 1 秒還沒出說明模型或配置有問題。5.3 打包與混淆的注意事項sherpa-onnx 的 AAR 里包含 native 庫混淆時要注意保留相關類。我在proguard-rules.pro里加了這幾條-keep class com.k2fsa.sherpa.onnx.** { *; } -keep class ai.onnxruntime.** { *; }另外如果用了abiFilters只保留 arm64-v8a在 32 位設備上會直接崩潰。雖然現在 32 位設備越來越少但為了保險起見建議同時保留 armeabi-v7aAPK 體積會增加大概 8MB但兼容性更好。6. 從 Demo 到產品的工程化建議6.1 模型熱更新的設計思路模型文件不應該硬編碼在 APK 里否則每次換模型都要發(fā)版。我的做法是把模型放在 CDN 上App 啟動時檢查版本號有更新就下載到 filesDir。下載要用斷點續(xù)傳模型文件動輒幾十上百 MB用戶網絡不穩(wěn)定時很容易斷。下載完成后要做 MD5 校驗防止文件損壞。版本管理用一個 JSON 文件描述包含模型名稱、版本號、下載地址、MD5、大小等字段。App 端對比本地版本號和遠端版本號不一致就觸發(fā)下載。這個機制我在實際項目里跑了半年多更新過三次模型用戶側無感知。6.2 多場景下的資源調度一個 App 里可能同時用到 ASR 和 TTS甚至還有 VAD。如果全部常駐內存低端機扛不住。我的策略是分優(yōu)先級VAD 常駐模型小才幾 MBASR 按需加載用戶點錄音按鈕時加載松開后延遲 30 秒釋放TTS 也是按需加載。這樣峰值內存能控制在 250MB 以內大多數設備都能接受。釋放模型時要注意調用recognizer.release()和tts.release()否則 native 內存不會回收。我見過有開發(fā)者只置空引用結果 native 內存泄漏跑幾次就 OOM 了。6.3 用戶體驗層面的細節(jié)打磨端側語音和云端最大的區(qū)別是“沒有網絡等待”所以用戶體驗的預期也更高。首字延遲超過 500ms 用戶就會覺得卡超過 1 秒就會覺得壞了。所以優(yōu)化首字延遲比優(yōu)化整體 RTF 更重要。我的做法是錄音開始后立刻喂數據不要等緩沖區(qū)滿解碼用 greedy search 而不是 beam search雖然準確率略低但速度快很多VAD 的靜音閾值調低一點讓用戶一開口就能觸發(fā)識別。另外識別結果的展示也要注意。流式識別是逐字出結果的如果每出一個字就刷新 UI界面會閃得厲害。我一般用 100ms 的節(jié)流每 100ms 更新一次顯示既流暢又不卡頓。7. 我個人的一些實操體會這套方案我在兩個項目里落地過一個是離線會議記錄工具一個是語音朗讀助手。會議記錄那個項目對準確率要求高用的是 Zipformer 中英混合模型120MB在驍龍 870 上 RTF 0.15體驗很好。朗讀助手對延遲敏感用的是 Paraformer 小模型加 VITS首字延遲控制在 300ms 以內用戶反饋“跟云端差不多”。踩過的坑里最深刻的是音頻采集的兼容性問題。同一套代碼在小米上正常在華為上就沒聲音排查后發(fā)現是華為某些機型默認采樣率是 48000而我沒做重采樣。后來加了一個采樣率檢測邏輯如果設備默認不是 16000 就強制重采樣問題就解決了。所以我的建議是不要假設設備行為一致所有和硬件相關的參數都要做兼容處理。還有一個經驗是模型不是越大越好。我一開始追求準確率用了大模型結果低端機上卡得沒法用。后來換成小模型準確率只降了 2 個百分點但流暢度提升了一倍。端側場景下流暢度往往比那一點點準確率更重要畢竟用戶能容忍偶爾錯字但容忍不了卡頓。最后分享一個小技巧如果你不確定該選哪個模型可以先用 sherpa-onnx 官方提供的預編譯 APK 跑一遍里面內置了多個模型可以切換。實測哪個模型在你的目標機型上表現最好再決定集成哪個。這樣能省掉大量試錯時間。 Android端側語音交互實戰(zhàn)：sherpa-onnx集成ASR與TTS全指南
1. 端側語音交互的現狀與 sherpa-onnx 的切入點把語音識別和語音合成塞進手機這件事放在三五年前還屬于“實驗室里跑得動、真機上跑不動”的范疇。我最早接觸端側語音是在一個離線字幕工具的項目里當時用某款云端 ASR 接口網絡一抖字幕就斷用戶罵聲一片。后來轉向端側方案試過 TensorFlow Lite 的語音模型、也試過 PyTorch Mobile 的量化版本踩了不少坑直到遇到 sherpa-onnx才算找到一個在 Android 上真正能落地的方案。sherpa-onnx 是 k2-fsa 團隊開源的一套端側語音推理框架底層基于 onnxruntime支持流式和非流式 ASR、TTS、VAD、說話人分離等任務。它的核心價值在于模型體積小、推理速度快、跨平臺一致性好而且提供了完整的 Android 預編譯庫和 Kotlin/Java API。換句話說你不需要自己從 PyTorch 導出 ONNX、不需要手寫 JNI 膠水層、不需要折騰 NDK 編譯直接拿 AAR 包就能在 Android 項目里跑起來。這篇文章面向的是有一定 Android 開發(fā)基礎、想在 App 里集成離線語音能力的開發(fā)者。不管你是想做語音輸入法、離線字幕、語音助手還是想做 TTS 朗讀功能sherpa-onnx 都能給你一條相對平滑的路徑。我會從架構設計、模型選型、實操集成、性能調優(yōu)、問題排查幾個維度把我在實際項目中積累的經驗完整地分享出來。2. 為什么選 sherpa-onnx 而不是其他端側方案2.1 端側語音推理的三種主流路線對比在決定用 sherpa-onnx 之前我認真對比過市面上幾條主流路線這里把關鍵差異整理成表格方便你根據自己的場景做判斷。方案底層引擎模型格式Android 支持流式 ASRTTS 支持集成難度sherpa-onnxonnxruntimeONNX官方 AAR支持支持低TensorFlow LiteTFLiteTFLite官方庫需自行實現有限中PyTorch MobilePyTorchTorchScript官方庫需自行實現有限中高云端 API服務端不涉及HTTP 調用支持支持低但依賴網絡從表格能看出來sherpa-onnx 最大的優(yōu)勢是“開箱即用”——它把流式 ASR 和 TTS 這兩塊最難啃的骨頭都封裝好了而且模型格式統(tǒng)一為 ONNX社區(qū)里現成的模型也最多。TensorFlow Lite 和 PyTorch Mobile 雖然也是端側方案但流式推理的邏輯需要你自己寫TTS 的支持也不如 sherpa-onnx 成熟。2.2 sherpa-onnx 的架構設計思路sherpa-onnx 的架構可以分成三層來理解。最底層是 onnxruntime負責實際的矩陣運算和算子執(zhí)行中間層是 sherpa-onnx 自己實現的語音處理邏輯包括特征提取fbank、解碼器greedy search 或 beam search、端點檢測VAD等最上層是各語言的 API 封裝Android 這邊提供的是 Kotlin/Java 接口。這種分層設計的好處是模型和推理引擎解耦你可以隨時替換 ONNX 模型而不需要改代碼同時特征提取和解碼邏輯用 C 實現性能比純 Java 實現高一個數量級。我在實測中對比過同樣的模型sherpa-onnx 的 C 解碼比用 Java 自己寫的貪心解碼快了將近 3 倍尤其是在長語音場景下差距更明顯。2.3 模型選型的核心考量sherpa-onnx 支持的 ASR 模型主要有幾類Paraformer中文效果好、Zipformer中英混合強、Whisper多語言但體積大、Conformer通用。TTS 模型則有 VITS、Matcha、Kokoro 等。選型時我一般看三個指標模型體積、實時率RTF、識別準確率。以中文場景為例Paraformer 的小模型大概 70MB 左右RTF 在驍龍 8 Gen 1 上能跑到 0.15 以下也就是說 10 秒的語音 1.5 秒就能出結果。Zipformer 的中英混合模型大概 120MBRTF 稍高但也在 0.3 以內。Whisper tiny 雖然只有 40MB但中文識別準確率明顯不如 Paraformer而且不支持流式。所以如果你的場景是純中文離線識別Paraformer 是首選如果需要中英混說Zipformer 更合適。注意模型體積和準確率永遠是一對矛盾。我見過有開發(fā)者為了追求小體積用了 Whisper tiny結果中文識別錯字率高達 15%用戶體驗極差。建議在體積和準確率之間找平衡點一般 70-150MB 是比較合理的區(qū)間。3. Android 集成實操從零到跑通第一個 Demo3.1 環(huán)境準備與依賴引入先說一下我的開發(fā)環(huán)境Android Studio Hedgehog 以上、Gradle 8.x、minSdk 24、targetSdk 34、NDK 版本 25.2。sherpa-onnx 的 AAR 包對 NDK 版本有要求太低會報鏈接錯誤太高也可能有兼容問題25.x 是比較穩(wěn)的區(qū)間。依賴引入有兩種方式。第一種是直接從 Maven Central 拉取dependencies { implementation(com.k2fsa.sherpa.onnx:sherpa-onnx:1.10.0) }第二種是手動下載 AAR 放到 libs 目錄適合需要定制編譯或者內網環(huán)境的情況。我一般推薦第一種版本管理方便升級也簡單。引入依賴后需要在build.gradle里加上 abiFilters只保留 arm64-v8a 和 armeabi-v7a這樣能顯著減小 APK 體積android { defaultConfig { ndk { abiFilters listOf(arm64-v8a, armeabi-v7a) } } }3.2 模型文件的放置與加載策略模型文件不能放在 assets 里直接讀因為 onnxruntime 需要文件路徑而不是 InputStream。我的做法是在 App 首次啟動時把 assets 里的模型拷貝到filesDir下之后直接從文件系統(tǒng)加載。拷貝邏輯要注意用后臺線程并且加一個版本標記模型更新時重新拷貝。fun copyModelIfNeeded(context: Context, modelName: String) { val targetDir File(context.filesDir, sherpa-models/$modelName) val versionFile File(targetDir, version.txt) val currentVersion 1.0 if (versionFile.exists() versionFile.readText() currentVersion) return targetDir.mkdirs() context.assets.open(models/$modelName).use { input - File(targetDir, model.onnx).outputStream().use { output - input.copyTo(output) } } versionFile.writeText(currentVersion) }模型加載本身是同步的但耗時可能到幾百毫秒建議放在 Application 啟動時或者用懶加載。我實測 Paraformer 小模型加載大概 200msZipformer 大概 400msTTS 的 VITS 模型大概 300ms。如果放在主線程會明顯卡頓一定要放到子線程。3.3 流式 ASR 的完整調用流程流式 ASR 的核心是“邊錄邊識別”需要把錄音線程和識別線程分開。錄音線程負責從 AudioRecord 讀取 PCM 數據識別線程負責把數據喂給 sherpa-onnx 的 stream 對象。val config OnlineRecognizerConfig( featConfig FeatureConfig(sampleRate 16000, featureDim 80), modelConfig OnlineModelConfig( transducer OnlineTransducerModelConfig( encoder $modelDir/encoder.onnx, decoder $modelDir/decoder.onnx, joiner $modelDir/joiner.onnx ), tokens $modelDir/tokens.txt, numThreads 2, provider cpu ), decodingMethod greedy_search ) val recognizer OnlineRecognizer(config) val stream recognizer.createStream()錄音線程每次讀到 1600 個采樣點100ms就調用stream.acceptWaveform(samples, 16000)然后調用recognizer.isReady(stream)判斷是否有可解碼的幀有的話就recognizer.decode(stream)再通過recognizer.getResult(stream)拿到當前識別結果。這套流程看起來簡單但有幾個坑我踩過一是采樣率必須是 16000錄音時如果設備默認是 44100 需要重采樣二是 numThreads 不要設太大2 線程在多數手機上已經夠用設 4 反而會因為線程調度開銷導致延遲增加。3.4 TTS 合成的參數調優(yōu)TTS 這邊相對簡單核心是文本前端和聲學模型的配合。sherpa-onnx 的 TTS 支持中英文混合但需要模型本身支持。VITS 中文模型大概 60MB合成一句話10 個字左右耗時在 200-400ms 之間。val ttsConfig OfflineTtsConfig( model OfflineTtsModelConfig( vits OfflineTtsVitsModelConfig( model $ttsModelDir/model.onnx, tokens $ttsModelDir/tokens.txt, lexicon $ttsModelDir/lexicon.txt ), numThreads 2 ), ruleFsts $ttsModelDir/rule.fst ) val tts OfflineTts(ttsConfig) val audio tts.generate(你好歡迎使用語音合成, sid 0, speed 1.0f)speed 參數控制語速1.0 是正常0.8 偏慢1.2 偏快。sid 是說話人 ID多說話人模型才有意義。生成的 audio 是 FloatArray需要轉成 16bit PCM 再用 AudioTrack 播放。這里有個細節(jié)AudioTrack 的 buffer size 要設夠太小會斷音我一般設成采樣率的 0.5 秒對應的字節(jié)數。4. 性能調優(yōu)與真機適配經驗4.1 不同芯片平臺的實測數據我在幾臺不同芯片的手機上跑了同一套 Paraformer 流式模型記錄下 RTF 和首字延遲數據如下芯片平臺代表機型檔位RTF首字延遲內存占用驍龍 8 Gen 2旗艦0.08180ms180MB驍龍 778G中端0.18320ms160MB天璣 8100中高端0.12240ms170MB驍龍 665入門0.45680ms140MB從數據能看出來旗艦機和中端機的差距主要在首字延遲上RTF 差距反而不大。入門機驍龍 665 這個級別的 RTF 到了 0.45意味著 10 秒語音要 4.5 秒才能出結果體驗就比較勉強了。所以如果你的 App 要覆蓋低端機建議用更小的模型或者干脆只在中高端機上開啟流式識別。4.2 內存與線程的平衡策略sherpa-onnx 默認用 2 線程這個設置在中高端機上表現最好。我試過在驍龍 778G 上把 numThreads 調到 4RTF 從 0.18 降到 0.15但首字延遲反而從 320ms 漲到 380ms原因是線程創(chuàng)建和同步的開銷增加了。所以我的建議是除非你的場景對吞吐量要求極高比如批量處理錄音文件否則 numThreads 保持 2 就行。內存方面模型加載后會常駐內存Paraformer 大概占 150-180MB。如果同時加載 ASR 和 TTS內存占用會到 300MB 左右。在 4GB 內存的低端機上這個占用已經比較危險了可能觸發(fā)系統(tǒng)殺后臺。我的做法是 ASR 和 TTS 按需加載用完就釋放雖然重新加載有幾百毫秒開銷但能顯著降低內存壓力。4.3 音頻采集的坑與解決方案Android 的 AudioRecord 在不同設備上行為不一致這是端側語音最頭疼的問題之一。我遇到過幾種典型情況某些機型默認采樣率是 48000 而不是 16000需要手動重采樣某些機型在藍牙耳機連接時采樣率會變還有的機型在錄音時會有明顯的底噪。重采樣我一般用線性插值雖然音質不如 sinc 插值但計算量小對識別準確率影響可以忽略。底噪問題可以通過 VAD 過濾sherpa-onnx 自帶的 VAD 模型silero-vad效果不錯能在識別前把靜音段切掉既省算力又提高準確率。提示錄音權限在 Android 6.0 以上需要動態(tài)申請而且從 Android 11 開始如果 App 在后臺錄音需要額外聲明 foregroundServiceType。這些系統(tǒng)限制一定要提前處理否則用戶反饋“錄不了音”你排查半天才發(fā)現是權限問題。5. 常見問題排查與避坑指南5.1 模型加載失敗的幾種典型原因模型加載失敗是最常見的問題我整理了一個排查表報錯信息可能原因解決方法Failed to load model文件路徑錯誤檢查 filesDir 下文件是否存在Invalid ONNX model模型文件損壞重新從官方倉庫下載Unsupported operatoronnxruntime 版本不匹配升級 sherpa-onnx 到最新版Out of memory模型太大換小模型或降低 numThreadsTokens file not foundtokens.txt 缺失確認模型目錄包含所有文件其中“Unsupported operator”這個坑我踩過最深。當時用了一個自己導出的 ONNX 模型里面有個算子 onnxruntime 不支持報錯信息又很模糊排查了一整天才發(fā)現是導出時用了 opset 17 而 onnxruntime 只支持到 15。后來我養(yǎng)成了一個習慣導出模型后先用 onnxruntime 的 Python 版跑一遍確認沒問題再放到 Android 上。5.2 識別結果異常的調試思路識別結果異常一般分三種完全沒結果、結果亂碼、結果延遲高。完全沒結果通常是音頻格式不對檢查采樣率、聲道數、位深是否匹配。結果亂碼多半是 tokens.txt 和模型不匹配或者模型本身是英文的卻用來識別中文。結果延遲高則要看 RTF如果 RTF 超過 0.5 就要考慮換模型或降 numThreads。我一般會在調試階段把每幀的識別結果打日志觀察是從第幾幀開始出字的。正常情況下流式模型在 300-500ms 內應該出第一個字如果超過 1 秒還沒出說明模型或配置有問題。5.3 打包與混淆的注意事項sherpa-onnx 的 AAR 里包含 native 庫混淆時要注意保留相關類。我在proguard-rules.pro里加了這幾條-keep class com.k2fsa.sherpa.onnx.** { *; } -keep class ai.onnxruntime.** { *; }另外如果用了abiFilters只保留 arm64-v8a在 32 位設備上會直接崩潰。雖然現在 32 位設備越來越少但為了保險起見建議同時保留 armeabi-v7aAPK 體積會增加大概 8MB但兼容性更好。6. 從 Demo 到產品的工程化建議6.1 模型熱更新的設計思路模型文件不應該硬編碼在 APK 里否則每次換模型都要發(fā)版。我的做法是把模型放在 CDN 上App 啟動時檢查版本號有更新就下載到 filesDir。下載要用斷點續(xù)傳模型文件動輒幾十上百 MB用戶網絡不穩(wěn)定時很容易斷。下載完成后要做 MD5 校驗防止文件損壞。版本管理用一個 JSON 文件描述包含模型名稱、版本號、下載地址、MD5、大小等字段。App 端對比本地版本號和遠端版本號不一致就觸發(fā)下載。這個機制我在實際項目里跑了半年多更新過三次模型用戶側無感知。6.2 多場景下的資源調度一個 App 里可能同時用到 ASR 和 TTS甚至還有 VAD。如果全部常駐內存低端機扛不住。我的策略是分優(yōu)先級VAD 常駐模型小才幾 MBASR 按需加載用戶點錄音按鈕時加載松開后延遲 30 秒釋放TTS 也是按需加載。這樣峰值內存能控制在 250MB 以內大多數設備都能接受。釋放模型時要注意調用recognizer.release()和tts.release()否則 native 內存不會回收。我見過有開發(fā)者只置空引用結果 native 內存泄漏跑幾次就 OOM 了。6.3 用戶體驗層面的細節(jié)打磨端側語音和云端最大的區(qū)別是“沒有網絡等待”所以用戶體驗的預期也更高。首字延遲超過 500ms 用戶就會覺得卡超過 1 秒就會覺得壞了。所以優(yōu)化首字延遲比優(yōu)化整體 RTF 更重要。我的做法是錄音開始后立刻喂數據不要等緩沖區(qū)滿解碼用 greedy search 而不是 beam search雖然準確率略低但速度快很多VAD 的靜音閾值調低一點讓用戶一開口就能觸發(fā)識別。另外識別結果的展示也要注意。流式識別是逐字出結果的如果每出一個字就刷新 UI界面會閃得厲害。我一般用 100ms 的節(jié)流每 100ms 更新一次顯示既流暢又不卡頓。7. 我個人的一些實操體會這套方案我在兩個項目里落地過一個是離線會議記錄工具一個是語音朗讀助手。會議記錄那個項目對準確率要求高用的是 Zipformer 中英混合模型120MB在驍龍 870 上 RTF 0.15體驗很好。朗讀助手對延遲敏感用的是 Paraformer 小模型加 VITS首字延遲控制在 300ms 以內用戶反饋“跟云端差不多”。踩過的坑里最深刻的是音頻采集的兼容性問題。同一套代碼在小米上正常在華為上就沒聲音排查后發(fā)現是華為某些機型默認采樣率是 48000而我沒做重采樣。后來加了一個采樣率檢測邏輯如果設備默認不是 16000 就強制重采樣問題就解決了。所以我的建議是不要假設設備行為一致所有和硬件相關的參數都要做兼容處理。還有一個經驗是模型不是越大越好。我一開始追求準確率用了大模型結果低端機上卡得沒法用。后來換成小模型準確率只降了 2 個百分點但流暢度提升了一倍。端側場景下流暢度往往比那一點點準確率更重要畢竟用戶能容忍偶爾錯字但容忍不了卡頓。最后分享一個小技巧如果你不確定該選哪個模型可以先用 sherpa-onnx 官方提供的預編譯 APK 跑一遍里面內置了多個模型可以切換。實測哪個模型在你的目標機型上表現最好再決定集成哪個。這樣能省掉大量試錯時間。