簡介這份資源面向安卓開發(fā)者與語音交互方向的初學(xué)者提供在Android Studio中集成科大訊飛AIKit語音喚醒功能的完整工程示例幫助解決喚醒詞配置、麥克風(fēng)權(quán)限申請(qǐng)、誤喚醒調(diào)試等常見問題。壓縮包共647個(gè)文件約45.56MB以xml布局與配置、json與flat資源、class與dex字節(jié)碼、jar與aar依賴庫、so動(dòng)態(tài)庫及ivw系列喚醒詞模型文件為主另含少量java源碼、gradle構(gòu)建腳本與pcm音頻樣本結(jié)構(gòu)貼近真實(shí)項(xiàng)目。已有719人學(xué)習(xí)下載適合對(duì)照工程結(jié)構(gòu)理解SDK接入流程。讀者可從中獲得可運(yùn)行的喚醒模塊參考實(shí)現(xiàn)、喚醒詞與識(shí)別閾值等定制參數(shù)示例以及權(quán)限聲明、依賴配置和兼容性處理的排錯(cuò)思路便于快速搭建自己的語音喚醒功能并在此基礎(chǔ)上二次開發(fā)。1. 從零接入 AIKit 語音喚醒為什么我建議你先跑通再談定制去年幫一個(gè)做智能硬件的團(tuán)隊(duì)調(diào) Android 端的離線喚醒他們之前用的是某開源方案誤喚醒率高得離譜半夜電視里說句話都能把設(shè)備叫醒。后來換到訊飛 AIKit 的語音喚醒能力同樣的麥克風(fēng)陣列誤喚醒直接壓下去了。這件事讓我意識(shí)到離線語音喚醒這個(gè)事真不是隨便找個(gè)模型塞進(jìn)去就完事。AIKit 是訊飛面向 Android 平臺(tái)的一套離線 AI 能力集合語音喚醒是其中使用頻率最高的模塊之一。它的核心價(jià)值在于不需要聯(lián)網(wǎng)、不需要把音頻傳到云端在本地就能完成關(guān)鍵詞檢測。對(duì)于智能家居中控、車載語音助手、會(huì)議終端這類對(duì)延遲和隱私敏感的場景離線喚醒幾乎是必選項(xiàng)。這篇筆記面向的是已經(jīng)會(huì)用 Android Studio 建工程、能看懂 Gradle 配置的開發(fā)者我會(huì)把從環(huán)境準(zhǔn)備到參數(shù)調(diào)優(yōu)的完整鏈路拆開講包括我踩過的幾個(gè)坑。如果你正在找一份能直接照著跑通的 AIKit 語音喚醒接入指南下面的內(nèi)容應(yīng)該能省你不少時(shí)間。2. 環(huán)境準(zhǔn)備與 SDK 接入Gradle 配置和 so 庫的那些事2.1 先搞清楚 AIKit 的包結(jié)構(gòu)下載完 AIKit 的 Android SDK 之后不要急著往工程里拖。先花五分鐘把目錄結(jié)構(gòu)看清楚后面能少走很多彎路。典型的包結(jié)構(gòu)是這樣的AIKit_Android/ ├── libs/ │ ├── aikit-core.jar # 核心接口層 │ ├── aikit-wakeup.jar # 語音喚醒模塊 │ └── jniLibs/ │ ├── arm64-v8a/ # 64 位 ARM 庫 │ ├── armeabi-v7a/ # 32 位 ARM 庫 │ └── x86_64/ # 模擬器調(diào)試用 ├── assets/ │ └── wakeup/ │ ├── keyword_xxx.bin # 喚醒詞模型文件 │ └── config.json # 喚醒參數(shù)配置 └── sample/ # 官方示例工程這里有幾個(gè)關(guān)鍵點(diǎn)。aikit-core.jar是必須的它提供了資源管理和授權(quán)校驗(yàn)的接口。aikit-wakeup.jar是喚醒模塊的業(yè)務(wù)層。jniLibs下面是 native 庫語音喚醒的推理引擎全在這里面Java 層只是殼。assets/wakeup/里放的是喚醒詞模型這個(gè)文件決定了你的設(shè)備能識(shí)別什么詞。我一般會(huì)先把sample工程用 Android Studio 打開跑一遍確認(rèn) SDK 本身沒問題再往自己的工程里搬。這樣做的好處是如果后面接入出問題你能快速判斷是 SDK 的問題還是自己工程配置的問題。2.2 Gradle 配置別被 sourceSets 坑了把 jar 和 so 庫放進(jìn)工程之后Gradle 配置是第一個(gè)容易翻車的地方。很多人直接把 jar 丟進(jìn)libs目錄就以為完事了結(jié)果編譯過了運(yùn)行時(shí)卻報(bào)UnsatisfiedLinkError。原因是 so 庫沒有被正確打包進(jìn) APK。正確的做法是在app/build.gradle里顯式指定 jniLibs 的路徑android { // ... 其他配置 sourceSets { main { // 告訴 Gradle 去哪里找 so 庫 jniLibs.srcDirs [libs/jniLibs] // 如果喚醒詞模型放在 assets 下不需要額外配置 // 但如果放在自定義目錄需要在這里指定 assets.srcDirs [src/main/assets] } } // 如果用了 abiFilters確保包含 SDK 支持的架構(gòu) defaultConfig { ndk { abiFilters arm64-v8a, armeabi-v7a } } } dependencies { // 引入 jar 包 implementation files(libs/aikit-core.jar) implementation files(libs/aikit-wakeup.jar) // 如果 SDK 依賴了其他庫按官方文檔補(bǔ)充 }這段配置里jniLibs.srcDirs是最關(guān)鍵的。默認(rèn)情況下 Gradle 會(huì)去src/main/jniLibs找 so 庫但 SDK 通常把 so 放在libs/jniLibs下面不顯式指定就會(huì)漏掉。abiFilters也要注意如果你只保留了arm64-v8a在 32 位設(shè)備上跑就會(huì)直接崩。我一般兩個(gè)都保留除非包體積卡得很死。還有一個(gè)細(xì)節(jié)如果你用的是 Android Studio 的新版本implementation files這種方式引入本地 jar 是沒問題的但要注意 jar 之間的依賴順序。aikit-wakeup.jar依賴aikit-core.jar雖然 Gradle 通常能處理但如果遇到NoClassDefFoundError可以試著調(diào)整一下引入順序。2.3 權(quán)限與初始化別等到運(yùn)行時(shí)才發(fā)現(xiàn)少了東西語音喚醒需要錄音權(quán)限這個(gè)大家都知道。但 AIKit 還可能需要讀取外部存儲(chǔ)的權(quán)限用來加載模型文件。如果你把模型放在 assets 里通過AssetManager讀取那就不需要存儲(chǔ)權(quán)限。但如果模型文件比較大放在 SD 卡上那就得在AndroidManifest.xml里聲明uses-permission android:nameandroid.permission.RECORD_AUDIO / uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE /運(yùn)行時(shí)權(quán)限的申請(qǐng)邏輯我就不展開寫了Android 6.0 以上的標(biāo)準(zhǔn)寫法。這里要提醒的是錄音權(quán)限被拒絕之后AIKit 的初始化會(huì)直接失敗但錯(cuò)誤碼可能不夠直觀。我建議在申請(qǐng)權(quán)限的回調(diào)里如果用戶拒絕了直接給一個(gè)明確的提示而不是讓 SDK 拋一個(gè)模糊的錯(cuò)誤。初始化 AIKit 的代碼通常長這樣// 在 Application 或主 Activity 的 onCreate 中調(diào)用 public class MyApp extends Application { Override public void onCreate() { super.onCreate(); // 初始化 AIKit 核心 AiKitCore.init(this, new AiKitInitListener() { Override public void onSuccess() { Log.d(AIKit, 核心初始化成功); // 核心初始化成功后再初始化喚醒模塊 initWakeup(); } Override public void onError(int code, String msg) { Log.e(AIKit, 初始化失敗: code code , msg msg); } }); } private void initWakeup() { // 喚醒模塊的初始化參數(shù)配置在下一章展開 } }AiKitCore.init()是異步的不要在它還沒回調(diào)成功的時(shí)候就去調(diào)用喚醒模塊的接口否則會(huì)拿到空指針或者未初始化的錯(cuò)誤。我一般會(huì)把喚醒模塊的初始化放在onSuccess回調(diào)里確保順序正確。3. 喚醒模塊的初始化與參數(shù)配置從能跑到好用3.1 喚醒引擎的創(chuàng)建與資源加載核心初始化完成之后下一步是創(chuàng)建喚醒引擎。AIKit 的喚醒模塊通常提供一個(gè)WakeupEngine或者類似的類你需要把喚醒詞模型和配置文件傳給它。public class WakeupManager { private IWakeupEngine wakeupEngine; private Context context; public WakeupManager(Context context) { this.context context; } public void init() { // 創(chuàng)建喚醒引擎實(shí)例 wakeupEngine WakeupEngineFactory.create(context); // 配置喚醒參數(shù) WakeupConfig config new WakeupConfig(); // 設(shè)置喚醒詞模型路徑assets 中的相對(duì)路徑 config.setKeywordPath(wakeup/keyword_xxx.bin); // 設(shè)置配置文件路徑 config.setConfigPath(wakeup/config.json); // 設(shè)置喚醒閾值范圍通常是 0.0 ~ 1.0 config.setThreshold(0.7f); // 設(shè)置是否返回音頻數(shù)據(jù)調(diào)試用正式環(huán)境建議關(guān)閉 config.setReturnAudio(false); // 初始化引擎 int ret wakeupEngine.init(config); if (ret ! 0) { Log.e(Wakeup, 引擎初始化失敗錯(cuò)誤碼: ret); return; } // 設(shè)置喚醒回調(diào) wakeupEngine.setWakeupListener(new IWakeupListener() { Override public void onWakeup(String keyword, int score) { // 喚醒成功keyword 是命中的詞score 是置信度 Log.i(Wakeup, 喚醒成功: keyword , 置信度: score); // 在這里觸發(fā)你的業(yè)務(wù)邏輯 } Override public void onError(int code, String msg) { Log.e(Wakeup, 喚醒出錯(cuò): code - msg); } }); } }這段代碼里有幾個(gè)參數(shù)值得展開說。setThreshold(0.7f)是喚醒閾值值越高越不容易誤喚醒但也越難喚醒。0.7 是一個(gè)比較中庸的起點(diǎn)實(shí)際項(xiàng)目里要根據(jù)場景調(diào)。setReturnAudio(false)控制是否在回調(diào)里返回音頻數(shù)據(jù)調(diào)試階段可以設(shè)為true來聽一下喚醒時(shí)的音頻質(zhì)量正式環(huán)境關(guān)掉能省一點(diǎn)內(nèi)存。wakeupEngine.init(config)返回 0 表示成功非 0 就是失敗。常見的錯(cuò)誤碼包括模型文件找不到、授權(quán)校驗(yàn)失敗、音頻設(shè)備被占用。如果返回非 0先檢查assets里的模型文件路徑對(duì)不對(duì)再檢查權(quán)限。3.2 喚醒參數(shù)怎么調(diào)閾值、靈敏度與場景匹配喚醒模塊的參數(shù)配置是決定體驗(yàn)好壞的關(guān)鍵。AIKit 的config.json里通常包含以下幾類參數(shù)參數(shù)名含義典型值調(diào)整建議threshold喚醒置信度閾值0.6 ~ 0.8嘈雜環(huán)境調(diào)高安靜環(huán)境調(diào)低sensitivity麥克風(fēng)靈敏度1 ~ 5遠(yuǎn)場場景調(diào)高近場調(diào)低wakeup_timeout喚醒后靜默時(shí)長(ms)3000 ~ 5000避免連續(xù)喚醒a(bǔ)udio_channel音頻通道數(shù)1 或 2單麥用 1陣列用 2sample_rate采樣率16000一般不用改threshold是最常調(diào)的。我做過一個(gè)車載場景發(fā)動(dòng)機(jī)噪音比較大閾值設(shè)到 0.75 才把誤喚醒壓住。但同一個(gè)模型放到安靜的會(huì)議室里0.75 就太遲鈍了得降到 0.65 左右。所以這個(gè)值沒有標(biāo)準(zhǔn)答案得在你的實(shí)際場景里測。sensitivity這個(gè)參數(shù)在不同版本的 SDK 里叫法可能不一樣有的叫mic_gain有的叫agc_level。它的作用是放大麥克風(fēng)采集到的信號(hào)。遠(yuǎn)場喚醒比如 5 米外需要調(diào)高但調(diào)太高會(huì)把背景噪音也放大反而增加誤喚醒。我一般從 3 開始試根據(jù)喚醒距離和誤喚醒情況微調(diào)。wakeup_timeout是喚醒之后的冷卻時(shí)間。比如你設(shè)了 3000ms那喚醒一次之后3 秒內(nèi)不會(huì)再觸發(fā)。這個(gè)參數(shù)能有效避免一句話被重復(fù)識(shí)別成多次喚醒。3.3 音頻采集與引擎的對(duì)接喚醒引擎需要持續(xù)的音頻流輸入。AIKit 通常提供了兩種模式一種是引擎內(nèi)部自己管理錄音設(shè)備你只需要調(diào)用start()就行另一種是你自己采集音頻把 PCM 數(shù)據(jù)喂給引擎。第一種更省事第二種更靈活。如果你用內(nèi)部錄音模式代碼大概是這樣// 啟動(dòng)喚醒監(jiān)聽 int ret wakeupEngine.start(); if (ret ! 0) { Log.e(Wakeup, 啟動(dòng)失敗: ret); } // 停止喚醒監(jiān)聽 // wakeupEngine.stop();但這里有個(gè)坑start()之后引擎會(huì)占用麥克風(fēng)。如果你的 App 里還有其他功能需要錄音比如語音識(shí)別、錄音機(jī)就會(huì)沖突。解決辦法是在喚醒和錄音之間做互斥喚醒到之后先stop()等業(yè)務(wù)處理完再重新start()。如果你用外部音頻模式就需要自己創(chuàng)建AudioRecord把讀到的 PCM 數(shù)據(jù)通過writeAudio()喂給引擎// 外部音頻模式下的數(shù)據(jù)寫入 byte[] audioBuffer new byte[bufferSize]; int read audioRecord.read(audioBuffer, 0, bufferSize); if (read 0) { // 把 PCM 數(shù)據(jù)寫入喚醒引擎 wakeupEngine.writeAudio(audioBuffer, read); }外部模式的好處是你可以對(duì)音頻做預(yù)處理比如降噪、增益、波束成形。如果你的設(shè)備有麥克風(fēng)陣列外部模式幾乎是必須的因?yàn)殛嚵械脑紨?shù)據(jù)需要你自己做波束成形之后再送給引擎。4. 避坑與排查那些讓我加班到凌晨的問題4.1 喚醒沒反應(yīng)日志里什么都沒有現(xiàn)象App 跑起來了權(quán)限也給了但對(duì)著麥克風(fēng)喊喚醒詞一點(diǎn)反應(yīng)都沒有Logcat 里也沒有任何喚醒相關(guān)的日志。原因最常見的原因是喚醒引擎根本沒啟動(dòng)成功但錯(cuò)誤被吞掉了。wakeupEngine.start()返回了非 0但代碼里沒處理返回值。另一個(gè)原因是音頻設(shè)備被其他 App 占用比如你同時(shí)開著錄音機(jī)或者語音通話。解決先檢查start()的返回值非 0 就打印錯(cuò)誤碼。然后檢查有沒有其他 App 在占用麥克風(fēng)。如果是內(nèi)部錄音模式可以試著先stop()再start()有時(shí)候是狀態(tài)機(jī)沒復(fù)位。還有一個(gè)隱蔽的原因某些定制 ROM 會(huì)限制后臺(tái) App 的錄音權(quán)限即使你申請(qǐng)了RECORD_AUDIO切到后臺(tái)之后錄音會(huì)被靜默掐斷。這種情況需要在設(shè)置里手動(dòng)允許后臺(tái)錄音。4.2 誤喚醒率高電視里說話也能觸發(fā)現(xiàn)象設(shè)備放在客廳電視里播放的節(jié)目偶爾會(huì)觸發(fā)喚醒一天誤喚醒十幾次。原因喚醒閾值設(shè)得太低或者喚醒詞本身和電視節(jié)目里的某些發(fā)音接近。另外如果sensitivity調(diào)得太高背景噪音被放大也會(huì)增加誤喚醒。解決先把threshold調(diào)高 0.05 到 0.1觀察誤喚醒是否減少。如果還是不行檢查喚醒詞的選擇——盡量選音節(jié)組合比較特殊的詞避免用“你好”“打開”這種常見詞。如果設(shè)備有麥克風(fēng)陣列開啟波束成形把拾音方向?qū)?zhǔn)用戶所在區(qū)域能顯著降低側(cè)面和背面的噪音干擾。我那個(gè)車載項(xiàng)目最后就是把閾值從 0.65 調(diào)到 0.78配合波束成形誤喚醒從每天十幾次降到了一周一次以內(nèi)。4.3 喚醒延遲大喊完要等一兩秒才響應(yīng)現(xiàn)象喊了喚醒詞之后設(shè)備要過一兩秒才給出反饋體驗(yàn)很割裂。原因可能是音頻緩沖區(qū)設(shè)得太大導(dǎo)致引擎拿到音頻數(shù)據(jù)的延遲高。也可能是喚醒之后的業(yè)務(wù)邏輯太重比如在回調(diào)里直接做了網(wǎng)絡(luò)請(qǐng)求或者大量計(jì)算。解決檢查AudioRecord的bufferSize一般 16kHz 采樣率下1024 或 2048 個(gè)采樣點(diǎn)就夠了別設(shè)太大。喚醒回調(diào)里只做最輕量的操作比如發(fā)一個(gè)廣播或者設(shè)置一個(gè)標(biāo)志位把重邏輯放到其他線程去處理。另外如果用了外部音頻模式確保writeAudio()的調(diào)用頻率和音頻采集頻率匹配不要攢一大塊再寫。4.4 換設(shè)備之后喚醒失效報(bào) UnsatisfiedLinkError現(xiàn)象在測試機(jī)上跑得好好的換了一臺(tái)設(shè)備就崩日志里是UnsatisfiedLinkError提示找不到某個(gè) so 庫。原因新設(shè)備的 CPU 架構(gòu)和你打包的 so 庫不匹配。比如你只打包了arm64-v8a但新設(shè)備是armeabi-v7a?；蛘吣愦虬藊86_64但真機(jī)是 ARM 架構(gòu)。解決在build.gradle的abiFilters里把a(bǔ)rm64-v8a和armeabi-v7a都加上。如果包體積允許x86_64也加上方便在模擬器上調(diào)試。另外檢查一下 so 庫是不是完整有時(shí)候從壓縮包里解壓出來會(huì)丟文件。4.5 授權(quán)校驗(yàn)失敗提示 license 無效現(xiàn)象引擎初始化返回錯(cuò)誤碼提示授權(quán)校驗(yàn)失敗。原因AIKit 通常需要綁定應(yīng)用包名或者簽名。如果你換了包名或者用了 debug 簽名而 SDK 綁定的是 release 簽名就會(huì)校驗(yàn)失敗。解決確認(rèn)你的applicationId和申請(qǐng) SDK 時(shí)填的包名一致。如果 SDK 綁定了簽名確保你用的簽名文件一致。有些 SDK 還要求把授權(quán)文件放在特定目錄檢查一下有沒有漏掉。這個(gè)問題沒有通用解法只能對(duì)著 SDK 的授權(quán)說明逐條核對(duì)。5. 進(jìn)階技巧用喚醒命令詞做輕量級(jí)離線交互喚醒只是第一步。實(shí)際產(chǎn)品里用戶喚醒之后通常還會(huì)說一個(gè)指令比如“打開燈光”“調(diào)高溫度”。如果每次喚醒之后都要走云端識(shí)別延遲和隱私問題又回來了。AIKit 除了喚醒模塊通常還提供命令詞識(shí)別Command Word能力可以和喚醒串聯(lián)起來做一套完全離線的語音交互。思路是這樣的喚醒引擎檢測到喚醒詞之后先stop()喚醒然后啟動(dòng)命令詞識(shí)別引擎把接下來的音頻流喂給它。命令詞識(shí)別命中之后執(zhí)行對(duì)應(yīng)動(dòng)作再重新start()喚醒。整個(gè)鏈路都在本地完成延遲可以壓到 200ms 以內(nèi)。// 喚醒回調(diào)里切換到命令詞識(shí)別 Override public void onWakeup(String keyword, int score) { // 先停掉喚醒釋放麥克風(fēng) wakeupEngine.stop(); // 啟動(dòng)命令詞識(shí)別 commandEngine.start(); // 命令詞識(shí)別的結(jié)果在它的回調(diào)里處理 } // 命令詞識(shí)別回調(diào) Override public void onCommandRecognized(String command) { // 執(zhí)行對(duì)應(yīng)動(dòng)作 executeCommand(command); // 動(dòng)作執(zhí)行完重新啟動(dòng)喚醒 commandEngine.stop(); wakeupEngine.start(); }這里的關(guān)鍵是狀態(tài)切換的時(shí)序。stop()和start()之間要留一點(diǎn)間隔否則音頻設(shè)備可能還沒釋放完新的引擎啟動(dòng)會(huì)失敗。我一般會(huì)在stop()之后延遲 100ms 再start()另一個(gè)引擎。另外命令詞識(shí)別也有自己的閾值和超時(shí)時(shí)間超時(shí)沒識(shí)別到就自動(dòng)回到喚醒狀態(tài)避免用戶喚醒之后不說話導(dǎo)致設(shè)備一直等著。驗(yàn)證這套鏈路是否正常我通常會(huì)用以下幾個(gè)步驟先單獨(dú)測喚醒確認(rèn)喚醒率和誤喚醒率達(dá)標(biāo)再單獨(dú)測命令詞確認(rèn)識(shí)別率最后串聯(lián)起來測切換時(shí)的延遲和失敗率。如果串聯(lián)之后喚醒率下降多半是狀態(tài)切換的時(shí)序有問題檢查stop()和start()之間有沒有足夠的間隔。還有一個(gè)技巧如果你的設(shè)備有多個(gè)麥克風(fēng)可以在喚醒階段就用波束成形把拾音方向?qū)?zhǔn)用戶這樣喚醒和命令詞的識(shí)別率都會(huì)提升。波束成形的參數(shù)通常不在 AIKit 里配需要你在音頻采集層自己做。我一般會(huì)用簡單的延遲求和波束成形效果已經(jīng)夠用了。從那以后我每次接入新的語音 SDK都會(huì)先把官方 sample 跑通再在自己的工程里復(fù)現(xiàn)最后才做定制。這個(gè)習(xí)慣幫我省了很多來回折騰的時(shí)間。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取