需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

优化音频设置

更新时间不可用

了解对话式 AI 引擎中优化音频设置相关内容的适用场景、配置步骤、实现要点和注意事项。

在实时互动场景中，人与 AI 的对话在对话节奏、发言连续性和语音语调方面与人与人之间的对话存在显著差异。因此，为获得更好的对话体验，针对 AI 与人对话场景的音频设置显得尤为重要。

使用实时互动 iOS/Android/Web SDK 接入对话式 AI 引擎时，你可以参考本文提供的优化音频设置，提升对话的流畅度和可靠性，确保在复杂网络环境中提供更好的用户体验。

服务端设置

调用服务端 API 创建对话式智能体时，音频相关参数采用默认值即可获得最佳音频体验。

客户端设置

集成必需动态库

对话式 AI 引擎最佳音频体验需要使用到以下插件动态库，请确保在项目中集成并加载这些动态库：

  • AI 降噪插件：libagora_ai_noise_suppression_extension.so
  • AI 回声消除插件：libagora_ai_echo_cancellation_extension.so

集成方式请参考减小 App 体积。

  • AI 降噪插件：AgoraAiNoiseSuppressionExtension.xcframework
  • AI 回声消除插件：AgoraAiEchoCancellationExtension.xcframework

集成方式请参考减小 App 体积。

设置最佳音频参数

客户端侧的最佳音频设置可通过以下两种方式实现：

  1. （推荐）调用客户端组件 API：适用于 4.5.1 及以上版本的实时互动 SDK。该方式目前仅支持 Android 和 iOS SDK。
  2. 调用实时互动 SDK API：适用于 4.3.1 及以上版本的实时互动 SDK。

方案一：使用客户端组件 API

声网提供一套灵活可扩展、标准化的对话式 AI 引擎客户端组件（以下简称组件）。该组件支持 iOS、Android、Web 平台，封装了多个场景化 API，你只需要调用这些 API 即可结合声网实时互动 (RTC) SDK 和实时消息 (RTM) SDK 的能力实现以下功能：

前提条件

开始前，请确保完成以下准备工作：

  • 已集成 RTC SDK v4.5.1 及以上版本，且已在 App 中实现基本的实时音视频功能并获取相关设备权限。请参考实现音视频互动。
  • 已在控制台为项目启用 RTM 服务，并在 App 中实现基本的实时消息功能。请参考实现收发消息。
  • 已参考实现对话式智能体实现与智能体对话的基本逻辑。
  • 确保 RTC 可用、RTM 已登录，且 RTC 和 RTM 实例的生命周期大于组件的生命周期。组件内部不负责维护 RTC，RTM 的初始化、生命周期以及鉴权/登录状态的逻辑。
集成组件

Maven (Maven)

在 Android 项目的 build.gradle 文件中添加如下依赖：

groovy
implementation 'io.agora.agents:agora-agent-client-toolkit:2.10.0'

源码集成 (源码集成)

将 convoaiApi 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。

agent-client-toolkit-kotlin

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

源码集成 (源码集成)

将 ConversationalAIAPI 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。

agent-client-toolkit-swift

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

源码集成 (源码集成)

将 conversational-ai-api 文件夹拷贝到你的项目中，并在后续调用组件 API 前引入组件。

agent-client-toolkit-ts

信息

如果在 Android 或 iOS 项目中同时集成多个声网 SDK 时出现库冲突，请参考多 SDK 库冲突处理。

初始化组件

为 RTC 和 RTM 实例创建配置对象，之后创建组件实例：

Kotlin
val config = ConversationalAIAPIConfig(
    rtcEngine = rtcEngine,
    rtmClient = rtmClient,
    renderMode = TranscriptRenderMode.Word,
    enableLog = true,
    enableRenderModeFallback = true
)

val api = ConversationalAIAPIImpl(config)
设置最佳音频参数

加入 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 创建对话式智能体接口，并完成以下参数设置：

  • advanced_features.enable_rtm: true —— （必选）启动 RTM 服务
  • parameters.data_channel: "rtm" —— （必选）开启 RTM 数据传输通道
  • parameters.enable_metrics: true —— （按需开启）接收智能体性能数据
  • parameters.enable_error_message: true —— （按需开启）接收智能体错误事件

调用成功后，智能体会加入指定 RTC 频道，用户可以开始与智能体互动。

销毁组件实例

结束 AI 对话场景后或关闭 App 前，你需要销毁组件实例，以释放组件的所有资源。

Kotlin
api.destroy()

方案二：调用实时互动 SDK API

设置音频相关参数

注意

本节内容适用于以下版本的实时互动 SDK：

  • Android/iOS：适用于 4.3.1 及以上版本的实时互动 SDK。对于 4.3.1 以下版本的 SDK，推荐升级至 4.5.1 及以上版本，或联系技术支持了解配置方式。
  • Web：适用于 v4.15.0 或以上版本的 Web SDK。

为获得最佳 AI 对话音频体验，你需要完成以下音频相关设置：

  1. 设置音频场景：在初始化引擎时将音频场景设置为 AI 对话场景。你也可以在加入频道前调用 setAudioScenario 方法将音频场景设置为 AI 对话场景。
  2. 设置音频相关参数：在加入频道前和音频路由变化（触发 onAudioRouteChanged 回调）时，调用 setParameters 方法设置音频相关参数。主要包括音频 3A（回声消除（AEC）、降噪（ANS）和增益控制（AGC））插件的开关，以及音频采样率、音频处理模式等设置。各参数推荐设定的值参考示例代码。

注意

由于 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

// 设置音频配置参数
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}")
    }
}

// 创建并初始化 RTC 引擎
fun createRtcEngine(rtcCallback: IRtcEngineEventHandler): RtcEngineEx {
    val config = RtcEngineConfig()
    config.mContext = AgentApp.instance()
    config.mAppId = ServerConfig.rtcAppId
    config.mChannelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING
    // 设置音频场景为 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)
        }
    }
    try {
        rtcEngine = (RtcEngine.create(config) as RtcEngineEx).apply {
            // 加载音频插件
            loadExtensionProvider("ai_echo_cancellation_extension")
            loadExtensionProvider("ai_noise_suppression_extension")
        }
    } catch (e: Exception) {
        Log.e("CovAgoraManager", "createRtcEngine error: $e")
    }
    return rtcEngine!!
}

// 加入频道
fun joinChannel(rtcToken: String, channelName: String, uid: Int, isIndependent: Boolean = false) {

    // 初始化音频配置参数
    setAudioConfigParameters(mAudioRouting)

    // 配置频道选项并加入频道
    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 方法将音频场景设置为 AI 对话场景。
  2. 设置音频相关参数：在加入频道前和音频路由发生变化（触发 rtcEngine:didAudioRouteChanged: 回调）时，调用 setParameters 方法设置音频相关参数。主要包括音频 3A（回声消除（AEC）、降噪（ANS）和增益控制（AGC））插件的开关，以及音频采样率、音频处理模式等设置。各参数推荐设定的值参考示例代码。

注意

由于 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

    // 设置音频相关参数
    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}")
    }
}

extension RTCManager: RTCManagerProtocol {

    func createRtcEngine(delegate: AgoraRtcEngineDelegate) -> AgoraRtcEngineKit {
        let config = AgoraRtcEngineConfig()
        config.appId = AppContext.shared.appId
        config.channelProfile = .liveBroadcasting
        // 设置音频场景为 AI 对话场景(4.5.1 及以上版本支持)
        // 4.3.1 ~ 4.5.0 版本支持合唱场景 .chorus
        config.audioScenario = .aiClient
        rtcEngine = AgoraRtcEngineKit.sharedEngine(with: config, delegate: delegate)
        // 注册音频路由变化回调
        rtcEngine.addDelegate(self)
        return rtcEngine
    }

    func joinChannel(rtcToken: String, channelName: String, uid: String) {

        // 初始化音频配置参数
        setAudioConfigParameters(routing: audioRouting)

        // 配置频道选项并加入频道
        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)
    }
}

// 实现 AgoraRtcEngineDelegate 接口，处理音频路由变化回调
extension RTCManager: AgoraRtcEngineDelegate {
    public func rtcEngine(_ engine: AgoraRtcEngineKit, didAudioRouteChanged routing: AgoraAudioOutputRouting) {
        setAudioConfigParameters(routing: routing)
    }
}

参考使用 AI 降噪插件了解如何集成 AI 降噪插件以提高 AI 对话音频体验。

参考信息

示例项目

声网提供开源的示例代码，你可以参考设置音频相关参数。

CovRtcManager.kt

RTCManager.swift

API 参考

RTC SDK API

客户端组件 API

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利