# 优化音频设置 (/zh-CN/ai/build/harden-and-optimize/audio-setup) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 在实时互动场景中,人与 AI 的对话在对话节奏、发言连续性和语音语调方面与人与人之间的对话存在显著差异。因此,为获得更好的对话体验,针对 AI 与人对话场景的音频设置显得尤为重要。 使用实时互动 iOS/Android/Web SDK 接入对话式 AI 引擎时,你可以参考本文提供的优化音频设置,提升对话的流畅度和可靠性,确保在复杂网络环境中提供更好的用户体验。 ## 服务端设置 [#服务端设置] 调用服务端 API 创建对话式智能体时,音频相关参数采用默认值即可获得最佳音频体验。 ## 客户端设置 [#客户端设置] ### 集成必需动态库 [#集成必需动态库] 对话式 AI 引擎最佳音频体验需要使用到以下插件动态库,请确保在项目中集成并加载这些动态库: Android iOS Web - AI 降噪插件:`libagora_ai_noise_suppression_extension.so` - AI 回声消除插件:`libagora_ai_echo_cancellation_extension.so` 集成方式请参考[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size/android#删除不需要的插件)。 - AI 降噪插件:`AgoraAiNoiseSuppressionExtension.xcframework` - AI 回声消除插件:`AgoraAiEchoCancellationExtension.xcframework` 集成方式请参考[减小 App 体积](/zh-CN/realtime-media/rtc/build/optimize-and-operate/reduce-app-size/ios#删除不需要的插件-1)。 - 参考[使用 AI 降噪插件](/zh-CN/realtime-media/rtc/build/extensions/web/noise-reduction)集成 AI 降噪插件:`agora-extension-ai-denoiser`。 ### 设置最佳音频参数 [#设置最佳音频参数] 客户端侧的最佳音频设置可通过以下两种方式实现: 1. (推荐)[调用客户端组件 API](#方案一使用客户端组件-api):适用于 4.5.1 及以上版本的实时互动 SDK。该方式目前仅支持 Android 和 iOS SDK。 2. [调用实时互动 SDK API](#方案二调用实时互动-sdk-api):适用于 4.3.1 及以上版本的实时互动 SDK。 #### 方案一:使用客户端组件 API [#方案一使用客户端组件-api] 声网提供一套灵活可扩展、标准化的对话式 AI 引擎客户端组件(以下简称组件)。该组件支持 iOS、Android、Web 平台,封装了多个场景化 API,你只需要调用这些 API 即可结合声网[实时互动 (RTC) SDK](/zh-CN/realtime-media/rtc) 和[实时消息 (RTM) SDK](/zh-CN/realtime-media/rtm) 的能力实现以下功能: - [打断智能体](/zh-CN/ai/build/shape-the-conversation/interrupt-agent) - [实时字幕](/zh-CN/ai/build/transcripts) - [监听智能体相关事件](/zh-CN/ai/build/handle-runtime-events/event-notifications) - [设置最佳音频参数](/zh-CN/ai/build/harden-and-optimize/audio-setup) (仅支持 Android 和 iOS) - [发送图片消息](/zh-CN/ai/build/send-multimodal-messages) ##### 前提条件 [#前提条件] 开始前,请确保完成以下准备工作: - 已集成 RTC SDK v4.5.1 及以上版本,且已在 App 中实现基本的实时音视频功能并获取相关设备权限。请参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 - 已在[控制台](https://console.shengwang.cn/)为项目启用 RTM 服务,并在 App 中实现基本的实时消息功能。请参考[实现收发消息](/zh-CN/realtime-media/rtm/get-started/quick-start)。 - 已参考[实现对话式智能体](/zh-CN/ai/get-started/quick-start)实现与智能体对话的基本逻辑。 - 确保 RTC 可用、RTM 已登录,且 RTC 和 RTM 实例的生命周期大于组件的生命周期。组件内部不负责维护 RTC,RTM 的初始化、生命周期以及鉴权/登录状态的逻辑。 ##### 集成组件 [#集成组件] Android iOS Web Maven 源码集成 #### Maven [#maven] 在 Android 项目的 `build.gradle` 文件中添加如下依赖: ```groovy implementation 'io.agora.agents:agora-agent-client-toolkit:2.10.0' ``` #### 源码集成 [#源码集成] 将 `convoaiApi` 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。 CocoaPods Swift Package Manager 源码集成 #### CocoaPods [#cocoapods] 在 `Podfile` 中添加如下依赖: ```ruby pod 'agent-client-toolkit-swift', '2.10.0' ``` #### Swift Package Manager [#swift-package-manager] 在 Xcode 中添加如下 Package URL,并将版本指定为 tag `2.10.0`: ```text https://github.com/AgoraIO/agent-client-toolkit-swift.git ``` #### 源码集成 [#源码集成-1] 将 `ConversationalAIAPI` 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。 Package Manager 源码集成 #### Package Manager [#package-manager] 根据你的项目类型安装组件依赖。 - Vanilla JS / TypeScript: ```shell pnpm add agora-agent-client-toolkit@2.10.0 ``` - React: ```shell pnpm add agora-agent-client-toolkit@2.10.0 agora-agent-client-toolkit-react@2.10.0 ``` #### 源码集成 [#源码集成-2] 将 `conversational-ai-api` 文件夹拷贝到你的项目中,并在后续调用组件 API 前引入组件。 :::info[信息] 如果在 Android 或 iOS 项目中同时集成多个声网 SDK 时出现库冲突,请参考[多 SDK 库冲突处理](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue)。 ::: ##### 初始化组件 [#初始化组件] 为 RTC 和 RTM 实例创建配置对象,之后创建组件实例: ```kotlin tab="Android" tabGroup="language" val config = ConversationalAIAPIConfig( rtcEngine = rtcEngine, rtmClient = rtmClient, renderMode = TranscriptRenderMode.Word, enableLog = true, enableRenderModeFallback = true ) val api = ConversationalAIAPIImpl(config) ``` ```swift tab="iOS" tabGroup="language" let config = ConversationalAIAPIConfig( rtcEngine: rtcEngine, rtmEngine: rtmEngine, renderMode: .words, enableLog: true, enableRenderModeFallback: true ) convoAIAPI = ConversationalAIAPIImpl(config: config) ``` ##### 设置最佳音频参数 [#设置最佳音频参数-1] Android iOS 加入 RTC 频道前,调用 `loadAudioSettings` 方法设置最佳音频参数。组件内部会监听 RTC 音频路由改变回调,并在音频路由发生变化时再次调用该方法设置最佳音频参数。 ```kotlin api.loadAudioSettings() rtcEngine.joinChannel(token, channelName, null, userId) ``` 加入 RTC 频道前,调用 `loadAudioSettings` 方法设置最佳音频参数。组件内部会监听 RTC 音频路由改变回调,并在音频路由发生变化时再次调用该方法设置最佳音频参数。 ```swift convoAIAPI.loadAudioSettings() rtcEngine.joinChannel(rtcToken: token, channelName: channelName, uid: uid, isIndependent: independent) ``` ##### 智能体加入频道 [#智能体加入频道] 调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)接口,并完成以下参数设置: - `advanced_features.enable_rtm: true` —— (必选)启动 RTM 服务 - `parameters.data_channel: "rtm"` —— (必选)开启 RTM 数据传输通道 - `parameters.enable_metrics: true` —— (按需开启)接收智能体性能数据 - `parameters.enable_error_message: true` —— (按需开启)接收智能体错误事件 调用成功后,智能体会加入指定 RTC 频道,用户可以开始与智能体互动。 ##### 销毁组件实例 [#销毁组件实例] 结束 AI 对话场景后或关闭 App 前,你需要销毁组件实例,以释放组件的所有资源。 ```kotlin tab="Android" tabGroup="language" api.destroy() ``` ```swift tab="iOS" tabGroup="language" convoAIAPI.destroy() ``` #### 方案二:调用实时互动 SDK API [#方案二调用实时互动-sdk-api] ##### 设置音频相关参数 [#设置音频相关参数] :::warning[注意] 本节内容适用于以下版本的实时互动 SDK: - Android/iOS:适用于 4.3.1 及以上版本的实时互动 SDK。对于 4.3.1 以下版本的 SDK,推荐升级至 4.5.1 及以上版本,或[联系技术支持](https://ticket.shengwang.cn/)了解配置方式。 - Web:适用于 v4.15.0 或以上版本的 Web SDK。 ::: Android iOS Web 为获得最佳 AI 对话音频体验,你需要完成以下音频相关设置: 1. **设置音频场景**:在初始化引擎时将音频场景设置为 AI 对话场景。你也可以在加入频道前调用 [`setAudioScenario`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioscenario) 方法将音频场景设置为 AI 对话场景。 2. **设置音频相关参数**:在加入频道前和音频路由变化(触发 [`onAudioRouteChanged`](/zh-CN/api-reference/rtc/android/device-management/audio-route#callback_irtcengineeventhandler_onaudioroutingchanged) 回调)时,调用 [`setParameters`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setparameters) 方法设置音频相关参数。主要包括音频 3A(回声消除(AEC)、降噪(ANS)和增益控制(AGC))插件的开关,以及音频采样率、音频处理模式等设置。各参数推荐设定的值参考示例代码。 :::warning[注意] 由于 4.3.1 \~ 4.5.0 版本的 SDK 不支持 AI 对话场景,可修改音频场景为合唱场景 (`AUDIO_SCENARIO_CHORUS`) 以提升音频体验,但无法对齐 4.5.1 及以上版本的音频体验。如需获得最佳音频体验,请升级 SDK 至 4.5.1 及以上版本。 ::: 以下示例代码封装了一个 `setAudioConfigParameters` 函数用于设置音频相关参数,并在加入频道前和音频路由发生变化时调用: ```kotlin private var rtcEngine: RtcEngineEx? = null private var mAudioRouting = Constants.AUDIO_ROUTE_DEFAULT // highlight-start // 设置音频配置参数 private fun setAudioConfigParameters(routing: Int) { mAudioRouting = routing rtcEngine?.apply { setParameters("{\"che.audio.aec.split_srate_for_48k\":16000}") setParameters("{\"che.audio.sf.enabled\":true}") setParameters("{\"che.audio.sf.stftType\":6}") setParameters("{\"che.audio.sf.ainlpLowLatencyFlag\":1}") setParameters("{\"che.audio.sf.ainsLowLatencyFlag\":1}") setParameters("{\"che.audio.sf.procChainMode\":1}") setParameters("{\"che.audio.sf.nlpDynamicMode\":1}") if (routing == Constants.AUDIO_ROUTE_HEADSET // 0 || routing == Constants.AUDIO_ROUTE_EARPIECE // 1 || routing == Constants.AUDIO_ROUTE_HEADSETNOMIC // 2 || routing == Constants.AUDIO_ROUTE_BLUETOOTH_DEVICE_HFP // 5 || routing == Constants.AUDIO_ROUTE_BLUETOOTH_DEVICE_A2DP) { // 10 setParameters("{\"che.audio.sf.nlpAlgRoute\":0}") } else { setParameters("{\"che.audio.sf.nlpAlgRoute\":1}") } setParameters("{\"che.audio.sf.ainlpModelPref\":10}") setParameters("{\"che.audio.sf.nsngAlgRoute\":12}") setParameters("{\"che.audio.sf.ainsModelPref\":10}") setParameters("{\"che.audio.sf.nsngPredefAgg\":11}") setParameters("{\"che.audio.agc.enable\":false}") } } // highlight-end // 创建并初始化 RTC 引擎 fun createRtcEngine(rtcCallback: IRtcEngineEventHandler): RtcEngineEx { val config = RtcEngineConfig() config.mContext = AgentApp.instance() config.mAppId = ServerConfig.rtcAppId config.mChannelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING // highlight-start // 设置音频场景为 AI 对话场景(4.5.1 及以上版本支持) // 4.3.1 ~ 4.5.0 版本设为合唱场景 AUDIO_SCENARIO_CHORUS config.mAudioScenario = Constants.AUDIO_SCENARIO_AI_CLIENT // 注册音频路由变化回调 config.mEventHandler = object : IRtcEngineEventHandler() { override fun onAudioRouteChanged(routing: Int) { super.onAudioRouteChanged(routing) // 设置音频相关参数 setAudioConfigParameters(routing) } } // highlight-end try { rtcEngine = (RtcEngine.create(config) as RtcEngineEx).apply { // highlight-start // 加载音频插件 loadExtensionProvider("ai_echo_cancellation_extension") loadExtensionProvider("ai_noise_suppression_extension") // highlight-end } } catch (e: Exception) { Log.e("CovAgoraManager", "createRtcEngine error: $e") } return rtcEngine!! } // 加入频道 fun joinChannel(rtcToken: String, channelName: String, uid: Int, isIndependent: Boolean = false) { // highlight-start // 初始化音频配置参数 setAudioConfigParameters(mAudioRouting) // highlight-end // 配置频道选项并加入频道 val options = ChannelMediaOptions() options.clientRoleType = CLIENT_ROLE_BROADCASTER options.publishMicrophoneTrack = true options.publishCameraTrack = false options.autoSubscribeAudio = true options.autoSubscribeVideo = false val ret = rtcEngine?.joinChannel(rtcToken, channelName, uid, options) } ``` 为获得最佳 AI 对话音频体验,你需要完成以下音频相关设置: 1. **设置音频场景**:在初始化引擎时将音频场景设置为 AI 对话场景。你也可以在加入频道前调用 [`setAudioScenario`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#api_irtcengine_setaudioscenario) 方法将音频场景设置为 AI 对话场景。 2. **设置音频相关参数**:在加入频道前和音频路由发生变化(触发 [`rtcEngine:didAudioRouteChanged:`](/zh-CN/api-reference/rtc/ios/device-management/audio-route#rtcenginedidaudioroutechanged) 回调)时,调用 [`setParameters`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_setparameters) 方法设置音频相关参数。主要包括音频 3A(回声消除(AEC)、降噪(ANS)和增益控制(AGC))插件的开关,以及音频采样率、音频处理模式等设置。各参数推荐设定的值参考示例代码。 :::warning[注意] 由于 4.3.1 \~ 4.5.0 版本的 SDK 不支持 AI 对话场景,可修改音频场景为合唱场景 (`AgoraAudioScenarioChorus`) 以提升音频体验,但无法对齐 4.5.1 及以上版本的音频体验。如需获得最佳音频体验,请升级 SDK 至 4.5.1 及以上版本。 ::: 以下示例代码封装了一个 `setAudioConfigParameters` 函数用于设置音频相关参数,并在加入频道前和音频路由发生变化时调用: ```swift class RTCManager: NSObject { private var rtcEngine: AgoraRtcEngineKit! private var audioDumpEnabled: Bool = false private var audioRouting = AgoraAudioOutputRouting.default // highlight-start // 设置音频相关参数 private func setAudioConfigParameters(routing: AgoraAudioOutputRouting) { audioRouting = routing rtcEngine.setParameters("{\"che.audio.aec.split_srate_for_48k\":16000}") rtcEngine.setParameters("{\"che.audio.sf.enabled\":true}") rtcEngine.setParameters("{\"che.audio.sf.stftType\":6}") rtcEngine.setParameters("{\"che.audio.sf.ainlpLowLatencyFlag\":1}") rtcEngine.setParameters("{\"che.audio.sf.ainsLowLatencyFlag\":1}") rtcEngine.setParameters("{\"che.audio.sf.procChainMode\":1}") rtcEngine.setParameters("{\"che.audio.sf.nlpDynamicMode\":1}") if routing == .headset || routing == .earpiece || routing == .headsetNoMic || routing == .bluetoothDeviceHfp || routing == .bluetoothDeviceA2dp { rtcEngine.setParameters("{\"che.audio.sf.nlpAlgRoute\":0}") } else { rtcEngine.setParameters("{\"che.audio.sf.nlpAlgRoute\":1}") } rtcEngine.setParameters("{\"che.audio.sf.ainlpModelPref\":10}") rtcEngine.setParameters("{\"che.audio.sf.nsngAlgRoute\":12}") rtcEngine.setParameters("{\"che.audio.sf.ainsModelPref\":10}") rtcEngine.setParameters("{\"che.audio.sf.nsngPredefAgg\":11}") rtcEngine.setParameters("{\"che.audio.agc.enable\":false}") } // highlight-end } extension RTCManager: RTCManagerProtocol { func createRtcEngine(delegate: AgoraRtcEngineDelegate) -> AgoraRtcEngineKit { let config = AgoraRtcEngineConfig() config.appId = AppContext.shared.appId config.channelProfile = .liveBroadcasting // highlight-start // 设置音频场景为 AI 对话场景(4.5.1 及以上版本支持) // 4.3.1 ~ 4.5.0 版本支持合唱场景 .chorus config.audioScenario = .aiClient rtcEngine = AgoraRtcEngineKit.sharedEngine(with: config, delegate: delegate) // 注册音频路由变化回调 rtcEngine.addDelegate(self) // highlight-end return rtcEngine } func joinChannel(rtcToken: String, channelName: String, uid: String) { // highlight-start // 初始化音频配置参数 setAudioConfigParameters(routing: audioRouting) // highlight-end // 配置频道选项并加入频道 let options = AgoraRtcChannelMediaOptions() options.clientRoleType = .broadcaster options.publishMicrophoneTrack = true options.publishCameraTrack = false options.autoSubscribeAudio = true options.autoSubscribeVideo = false let ret = rtcEngine.joinChannel(byToken: rtcToken, channelId: channelName, uid: UInt(uid) ?? 0, mediaOptions: options) } } // highlight-start // 实现 AgoraRtcEngineDelegate 接口,处理音频路由变化回调 extension RTCManager: AgoraRtcEngineDelegate { public func rtcEngine(_ engine: AgoraRtcEngineKit, didAudioRouteChanged routing: AgoraAudioOutputRouting) { setAudioConfigParameters(routing: routing) } } // highlight-end ``` 参考[使用 AI 降噪插件](/zh-CN/realtime-media/rtc/build/extensions/web/noise-reduction)了解如何集成 AI 降噪插件以提高 AI 对话音频体验。 ## 参考信息 [#参考信息] ### 示例项目 [#示例项目] 声网提供开源的示例代码,你可以参考设置音频相关参数。 Android iOS ### API 参考 [#api-参考] #### RTC SDK API [#rtc-sdk-api] Android iOS - [`setAudioScenario`](/zh-CN/api-reference/rtc/android/audio/audio-basic#api_irtcengine_setaudioscenario) - [`setParameters`](/zh-CN/api-reference/rtc/android/network#api_irtcengine_setparameters) - [`onAudioRouteChanged`](/zh-CN/api-reference/rtc/android/device-management/audio-route#callback_irtcengineeventhandler_onaudioroutingchanged) - [`setAudioScenario`](/zh-CN/api-reference/rtc/ios/audio/audio-basic#api_irtcengine_setaudioscenario) - [`setParameters`](/zh-CN/api-reference/rtc/ios/network#api_irtcengine_setparameters) - [`rtcEngine:didAudioRouteChanged:`](/zh-CN/api-reference/rtc/ios/device-management/audio-route#rtcenginedidaudioroutechanged) #### 客户端组件 API [#客户端组件-api] Android iOS - [`loadAudioSettings`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi#loadaudiosettings) - [`destroy`](/zh-CN/api-reference/conversational-ai/android/iconversationalaiapi#destroy) - [`loadAudioSettings [1/2]`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#loadaudiosettings[1/2]) - [`loadAudioSettings [2/2]`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#loadaudiosettings[2/2]) - [`destroy`](/zh-CN/api-reference/conversational-ai/ios/conversationalaiapi#destroy)