华为官方开发者文档过于庞大所以非常多基础说明的文档是复用的如果你是第一次接触接入华为的能力很容易被相互引用的链接跳转绕晕所以我整理了一下从基础配置准备到真正接入实时语音识别完整的过程每一节也附上了官方链接如果下面没有讲清的跳转官方文档再次查看即可一、华为后台准备1. 创建或选择 AGC 应用官方文档 https://developer.huawei.com/consumer/cn/doc/app/agc-help-createapk-0000001912873100进入 AppGallery Connect选择对应的项目如果还没有则新创建一个。创建完项目进入选择【常规】选项卡点击添加应用然后最重要的填写你将要接入的项目的包名到【应用包名】2. 开通服务在我的项目找到顶部【API 管理】选项卡在列表里找到机器学习服务勾选在 AGC 或华为开发者控制台中确认机器学习服务、实时语音识别相关能力已经开通。3. 获取 API key在项目设置页面找到顶部【常规】选项卡找到项目复制 apikey使用同一个 AGC 应用对应的 API key。API key 必须与applicationId和agconnect-services.json属于同一个应用身份。签名证书指纹按官方流程建议配置但当前 ASR 调试链路没有验证为强制项。但是我看这个 key 又是在【项目】的类别我感觉像是多个应用共用一个 key4. 下载 agconnect-services.json官方文档https://developer.huawei.com/consumer/cn/doc/AppGallery-connect-Guides/agc-get-started-android-0000001058210705#section113292017144从同一个 AGC 应用下载agconnect-services.json放到 app 模块目录app/agconnect-services.json下载后可以用下面命令确认 JSON 包名jq-r.client.package_nameapp/agconnect-services.json输出必须是和你项目包名一直二、Android 工程配置官方文档https://developer.huawei.com/consumer/cn/doc/AppGallery-connect-Guides/agc-get-started-android-0000001058210705#section1132920171441. 华为 Maven 仓库settings.gradle需要包含华为 Maven 仓库pluginManagement{repositories{google()mavenCentral()gradlePluginPortal()maven{urlhttps://developer.huawei.com/repo/}}}dependencyResolutionManagement{repositories{google()mavenCentral()maven{urlhttps://developer.huawei.com/repo/}}}2. AGC Gradle 插件根 build.gradle声明 AGC 插件buildscript{repositories{google()mavenCentral()maven{urlhttps://developer.huawei.com/repo/}}dependencies{classpathcom.huawei.agconnect:agcp:1.9.6.300}}当前工程使用 AGP 9.2.1旧 AGC 插件可能依赖已移除的AppExtension/applicationVariantsAPI因此这里使用1.9.6.300。app 模块应用 AGC 插件apply plugin:com.huawei.agconnect构建时应能看到类似日志Using the AGConnect-Config file: .../app/agconnect-services.json processDebugAGCPlugin3. SDK 依赖官方文档https://developer.huawei.com/consumer/cn/doc/hiai-Guides/asr-sdk-0000001050124643插件dependencies{ // 引入实时语音识别服务插件 implementation com.huawei.hms:ml-computer-voice-asr-plugin:3.15.1.301 }sdk 集成dependencies{ // 引入实时语音识别服务SDK implementation (com.huawei.hms:ml-computer-voice-asr:3.15.1.301) { exclude group : com.huawei.hms, module: network-embedded } implementation com.huawei.hms:network-embedded:7.0.3.300 }4. Android 权限ASR lib manifest 需要声明uses-permissionandroid:nameandroid.permission.INTERNET/uses-permissionandroid:nameandroid.permission.RECORD_AUDIO/uses-permissionandroid:nameandroid.permission.ACCESS_NETWORK_STATE/uses-permissionandroid:nameandroid.permission.ACCESS_WIFI_STATE/RECORD_AUDIO是运行时权限本 Demo 由:asr内部申请。三、运行时初始化和设置监听初始化华为 SDK这里主要是设置 key参考文档https://developer.huawei.com/consumer/cn/doc/hiai-Guides/sdk-data-security-0000001229909424#section2688102310166MLApplication.initialize(appContext)MLApplication.getInstance().setUserRegion(MLApplication.REGION_DR_CHINA)MLApplication.getInstance().apiKeyapiKey设置语音识别监听参考文档https://developer.huawei.com/consumer/cn/doc/hiai-Guides/ml-asr-0000001050066212#section699935381711// 1. context为应用上下文信息。MLAsrRecognizermSpeechRecognizerMLAsrRecognizer.createAsrRecognizer(context);// 2.设置回调mSpeechRecognizer.setAsrListener(newSpeechRecognitionListener());// 3.实现回调实现MLAsrListener接口实现接口中的方法。protectedclassSpeechRecognitionListenerimplementsMLAsrListener{OverridepublicvoidonStartListening(){// 录音器开始接收声音。}OverridepublicvoidonStartingOfSpeech(){// 用户开始讲话即语音识别器检测到用户开始讲话。}OverridepublicvoidonVoiceDataReceived(byte[]data,floatenergy,Bundlebundle){// 返回给用户原始的PCM音频流和音频能量该接口并非运行在主线程中返回结果需要在子线程中处理。}OverridepublicvoidonRecognizingResults(BundlepartialResults){// 从MLAsrRecognizer接收到持续语音识别的文本该接口并非运行在主线程中返回结果需要在子线程中处理。}OverridepublicvoidonResults(Bundleresults){// 语音识别的文本数据该接口并非运行在主线程中返回结果需要在子线程中处理。}OverridepublicvoidonError(interror,StringerrorMessage){// 识别发生错误后调用该接口该接口并非运行在主线程中返回结果需要在子线程中处理。}OverridepublicvoidonState(intstate,Bundleparams){// 通知应用状态发生改变该接口并非运行在主线程中返回结果需要在子线程中处理。}}语法识别参数配置// 新建Intent用于配置语音识别参数。IntentmSpeechRecognizerIntentnewIntent(MLAsrConstants.ACTION_HMS_ASR_SPEECH);// 通过Intent进行语音识别参数设置。mSpeechRecognizerIntent// 设置识别语言为英语若不设置则默认识别英语。支持设置zh-CN:中文en-US:英语fr-FR:法语es-ES:西班牙语de-DE:德语it-IT:意大利语ar: 阿拉伯语ru-RU:俄语thTH泰语ms-MY马来语fil-PH菲律宾语tr-TR土耳其语。.putExtra(MLAsrConstants.LANGUAGE,en-US)// 设置识别文本返回模式为边识别边出字若不设置默认为边识别边出字。支持设置// MLAsrConstants.FEATURE_WORDFLUX通过onRecognizingResults接口识别同时返回文字// MLAsrConstants.FEATURE_ALLINONE识别完成后通过onResults接口返回文字。.putExtra(MLAsrConstants.FEATURE,MLAsrConstants.FEATURE_WORDFLUX)// 静音检测时长发音前可设置3000到60000毫秒毫秒.putExtra(MLAsrConstants.VAD_START_MUTE_DURATION,6000)// 静音检测时长发音后毫秒.putExtra(MLAsrConstants.VAD_END_MUTE_DURATION,700)// 是否设置标点.putExtra(MLAsrConstants.PUNCTUATION_ENABLE,true)// 设置使用场景MLAsrConstants.SCENES_SHOPPING表示购物仅支持中文该场景对华为商品名识别进行了优化。.putExtra(MLAsrConstants.SCENES,MLAsrConstants.SCENES_SHOPPING);// 启动语音识别。mSpeechRecognizer.startRecognizing(mSpeechRecognizerIntent);四、常见问题1. Manifest merger placeholder 报错现象requires a placeholder substitution but no value for ... is provided原因通常是把真实 key 写成了${真实key}。正确做法是 manifest 保留${asrApiKey}真实 key 通过local.properties或 Gradle 参数注入。2. 11203/3002 Service unavailable优先检查应用身份是否一致applicationId是否等于agconnect-services.json.client.package_name。API key 是否来自同一个 AGC 应用。AGC 上机器学习服务/实时语音识别是否已开通。构建日志是否执行了processDebugAGCPlugin。设备网络是否能访问华为服务。3. API key 为空现象 Demo 会在启动 provider 时返回ProviderUnavailable日志中会有api key is empty。检查grep-E^(asr\.apiKey|asrApiKey)local.properties gradle.properties4. AGC 插件不兼容如果使用旧版本 AGC 插件在 AGP 9 上可能出现AppExtension或applicationVariants不存在。使用新版插件classpathcom.huawei.agconnect:agcp:1.9.6.3005. JSON 放错位置agconnect-services.json必须放在 app 模块根目录app/agconnect-services.json不是项目根目录也不是:asr模块目录。