# 配置云端 3A (/zh-CN/ai/build/harden-and-optimize/cloud-3a) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文面向使用 RTSA SDK 接入声网对话式 AI 引擎的设备开发者,介绍如何配置云端 3A(AEC、ANS 和 AGC),减少扬声器播放声音对麦克风采集造成的回声干扰。内容包括 RTSA 设备侧的音频参数配置,以及创建智能体请求中的服务端参数。 云端 3A 的基本链路如下:设备同步采集 Mic 和 Ref,将两路信号交织为双声道 PCM 后通过 RTSA SDK 上行;ConvoAI 在云端完成 AEC、ANS 和 AGC,再将处理后的音频交给 Voice Engine。Voice Engine 生成的回复音频经 RTSA SDK 下发到设备播放,实际播放链路的参考信号继续作为后续音频帧的 Ref。 本文中的服务端参数和 RTSA 参数需要结合实际的 ConvoAI 服务版本、RTSA SDK 版本及对应 API 参考确认。尤其是音频编解码参数,不要仅根据字段名称推断其收发方向或声道含义。 ## 1. 配置 RTSA 设备侧音频 [#1-配置-rtsa-设备侧音频] ### 1.1 采集和交织 Mic/Ref [#11-采集和交织-micref] 设备需要同步采集麦克风信号(Mic)和扬声器参考回采信号(Ref),并按采样点交织为双声道 PCM: | 项目 | 要求 | | --- | --- | | 上行采样率 | 16000 Hz | | 上行采样位宽 | 16-bit signed PCM,小端字节序 | | 上行声道数 | 2 | | 左声道 | Mic | | 右声道 | Ref | | 单帧时长 | 20 ms | | 每声道采样点数 | 320 | | 单帧数据长度 | 1280 字节 | 双声道数据需要按以下顺序交织: ```text Mic[0], Ref[0], Mic[1], Ref[1], ... , Mic[319], Ref[319] ``` C 语言交织示例: ```c #include #include #define SAMPLE_RATE_HZ 16000 #define FRAME_DURATION_MS 20 #define SAMPLES_PER_CHANNEL (SAMPLE_RATE_HZ * FRAME_DURATION_MS / 1000) #define CHANNEL_COUNT 2 static void interleave_mic_ref(const int16_t *mic, const int16_t *ref, int16_t *stereo, size_t samples_per_channel) { for (size_t i = 0; i < samples_per_channel; ++i) { stereo[2 * i] = mic[i]; stereo[2 * i + 1] = ref[i]; } } ``` Ref 应来自实际扬声器播放链路的参考信号或硬件回采,并与最终播放信号保持可对齐。请勿交换左右声道,也不要将两个声道混音后再发送。Mic 和 Ref 需要使用相同的采样率、位宽和帧长,并尽量保持在同一时钟域内。 ### 1.2 发送上行 PCM [#12-发送上行-pcm] RTSA SDK 的音频发送接口如下: ```c /** * @brief Send an audio frame to all channels OR specific channel. * All remote users in this channel will receive the audio frame. * @note All channels that you joined will receive the audio frame that you send * unless you stop sending the local audio to a specific channel. * @param[in] conn_id Connection identification * @param[in] data_ptr Audio frame buffer * @param[in] data_len Audio frame buffer length (bytes) * @param[in] info_ptr Audio frame info, see #audio_frame_info_t * @return * - = 0: Success * - < 0: Failure */ extern agora_api int agora_rtc_send_audio_data(connection_id_t conn_id, const void *data_ptr, size_t data_len, audio_frame_info_t *info_ptr); ``` 音频帧信息定义如下: ```c typedef struct { /** Audio data type, reference #audio_data_type_e. */ audio_data_type_e data_type; } audio_frame_info_t; ``` 发送 PCM 数据时,将 `data_type` 设置为 `AUDIO_DATA_TYPE_PCM`: ```c int16_t stereo_frame[SAMPLES_PER_CHANNEL * CHANNEL_COUNT]; audio_frame_info_t frame_info = { .data_type = AUDIO_DATA_TYPE_PCM, }; interleave_mic_ref(mic_frame, ref_frame, stereo_frame, SAMPLES_PER_CHANNEL); int ret = agora_rtc_send_audio_data(conn_id, stereo_frame, sizeof(stereo_frame), &frame_info); if (ret < 0) { /* 按业务需要记录日志或执行重试/恢复。 */ } ``` 设备应以稳定的 20 ms 周期发送,每次传入一帧完整数据。不要把多帧不规则地合并发送,也不要在输入不足时重复发送旧帧。 ### 1.3 加入 RTC 频道 [#13-加入-rtc-频道] RTSA SDK 加入频道的接口如下: ```c /** * @brief Local user joins channel. * @note Users in the same channel with the same App ID can send data to each other. * You can join more than one channel at the same time. All channels that * you join will receive the audio/video data stream that you send unless * you stop sending the audio/video data stream in a specific channel. * @param[in] conn_id Connection identification * @param[in] channel_name Channel name, whose length must be less than 64 bytes * @param[in] uid User ID in [1, 2³²-1], or 0 for SDK assignment * @param[in] token Token in [32, 512] bytes, or NULL if authorization is disabled * @param[in] options Channel options; use NULL if no options are required * @return * - = 0: Success * - < 0: Failure */ extern agora_api int agora_rtc_join_channel(connection_id_t conn_id, const char *channel_name, uint32_t uid, const char *token, rtc_channel_options_t *options); ``` `rtc_channel_options_t` 中与本接入流程相关的字段如下。结构体的完整定义和字段语义请以所用 RTSA SDK 版本的 API 参考为准: ```c typedef struct { bool auto_subscribe_audio; bool auto_subscribe_video; bool enable_audio_jitter_buffer; bool enable_audio_mixer; bool enable_audio_decode; bool enable_audio_ai_qos; bool enable_audio_downlink_aec; bool enable_audio_downlink_aec_pcm_dump; audio_codec_option_t audio_codec_opt; } rtc_channel_options_t; ``` 音频编解码配置定义如下: ```c typedef struct { audio_codec_type_e audio_codec_type; int pcm_sample_rate; int pcm_channel_num; int pcm_duration; } audio_codec_option_t; ``` 云端 3A 场景的配置示例: ```c rtc_channel_options_t options = {0}; options.auto_subscribe_audio = true; options.enable_audio_downlink_aec = true; options.enable_audio_decode = true; options.enable_audio_jitter_buffer = true; options.audio_codec_opt.audio_codec_type = AUDIO_CODEC_TYPE_G722; options.audio_codec_opt.pcm_sample_rate = 16000; options.audio_codec_opt.pcm_channel_num = 1; options.audio_codec_opt.pcm_duration = 20; int ret = agora_rtc_join_channel(conn_id, channel_name, uid, token, &options); if (ret < 0) { /* 加入频道失败,按错误码处理。 */ } ``` 如果 `uid` 传入 `0`,SDK 会在 `on_join_channel_success` 回调中返回分配的 UID。应用需要记录并维护该 UID。 > 注意:设备发送给云端 3A 的业务输入仍是“左 Mic、右 Ref”的双声道交织数据。`audio_codec_opt` 中各 PCM 参数的收发方向和声道语义可能随 RTSA SDK 版本或接入方案变化,请以目标版本 API 参考和已验证示例为准,不要仅根据字段名称推断配置。 ### 1.4 解码并播放下行音频 [#14-解码并播放下行音频] 在接收下行音频前,先将 RTSA 侧配置为: | 配置 | 推荐值 | | --- | --- | | `enable_audio_downlink_aec` | `true` | | `enable_audio_decode` | `true` | | `enable_audio_jitter_buffer` | `true` | | 音频编解码类型 | `AUDIO_CODEC_TYPE_G722` | | PCM 采样率 | `16000` | | PCM 声道数 | `1` | | PCM 帧长 | `20` ms | 云端 AEC 由服务端参数 `properties.parameters.audio3a_downstream.enable_aec` 开启。RTSA 的 `enable_audio_downlink_aec` 是设备侧 RTSA 配置项。两个参数位于不同的音频链路;是否需要同时开启以及各自的处理顺序,请以目标 SDK/服务版本的集成说明为准。 设备收到服务端下发的 G.722 音频后,由 RTSA SDK 完成解码和抖动缓冲,再向播放器输出单声道 PCM: - `enable_audio_decode = true`:启用 SDK 内置解码器。 - `enable_audio_jitter_buffer = true`:启用音频抖动缓冲,按稳定的帧间隔输出 PCM。 - `audio_codec_opt` 的具体收发方向和 PCM 声道语义请以目标 RTSA SDK 版本的 API 参考为准;不要将其默认理解为下行解码配置。 - 播放器的实际 PCM 格式、回调方式和播放线程处理应以 SDK 的音频接收接口为准。 播放器播放的音频信号需要继续作为下一帧的 Ref 输入。`subscribe_audio_num_of_channels` 表示服务端订阅的设备上行音频声道数;`pcm_channel_num` 的具体收发方向和声道含义以目标 RTSA SDK 版本的 API 参考为准,两者不要仅根据字段名称联动修改。 以上配置属于 RTSA/设备侧配置。`enable_audio_downlink_aec` 不应直接添加到创建智能体请求中。 ## 2. 配置服务端参数 [#2-配置服务端参数] 在创建智能体请求的 `properties.parameters` 中添加以下配置。以下参数是否对当前服务账号和版本开放,需要在联调前确认;如果服务端不接受这些字段,请联系声网技术支持确认开通条件。 以下示例包含云端 3A 的推荐初始值。完成基础接入后,再根据设备的扬声器音量、Mic 灵敏度和实际回声情况调整 AEC、ANS 和 AGC 参数。 ```json { "parameters": { "output_audio_codec": "G722", "audio3a_downstream": { "interleaved_reverse_stream": true, "sample_rate": 16000, "passthrough": false, "enable_aec": true, "aec_filter_length": "normal", "aec_model_type": "std_aiaec", "enable_aec_auto_reset": false, "aec_startup_max_suppress_time_in_ms": 1000, "aiaec_suppression_mode": "chat", "aec_suppression_mode": "aggressive", "enable_ans": true, "ans_mode_type": "std_aians", "ans_suppression_mode": "moderate", "enable_agc": true, "agc_max_digital_gain_db": 12, "agc_target_level_db": 6, "agc_curve_slope": 17, "enable_algorithm_log": false, "algorithm_log_level": "error", "algorithm_log_verbose": false }, "rtc": { "subscribe_audio_num_of_channels": 2 } } } ``` ### 服务端参数说明 [#服务端参数说明] | 参数 | 说明 | | --- | --- | | `output_audio_codec` | 下行音频编码格式。云端 3A 场景使用 `G722`,需要与设备侧解码配置一致。 | | `audio3a_downstream.interleaved_reverse_stream` | 声明输入采用按采样点交织的 Mic/Ref 双声道布局。设为 `true`。 | | `audio3a_downstream.sample_rate` | 云端 3A 输入采样率,设为 `16000`。 | | `audio3a_downstream.passthrough` | 是否透传原始输入。设为 `false`,让后续链路使用 3A 处理后的音频。 | | `audio3a_downstream.enable_aec` | 是否开启服务端 AEC。设为 `true`。 | | `audio3a_downstream.enable_ans` | 是否开启服务端 ANS。设为 `true`。 | | `audio3a_downstream.enable_agc` | 是否开启服务端 AGC。设为 `true`。 | | `properties.parameters.rtc.subscribe_audio_num_of_channels` | 服务端订阅的设备上行声道数。设为 `2`,以获取 Mic 和 Ref 两路信号。 | `properties.parameters.rtc` 与 `properties.rtc` 是两个独立配置对象: - `properties.parameters.rtc.subscribe_audio_num_of_channels` 用于云端 3A 订阅设备上行音频。 - `properties.rtc` 用于 RTC 媒体内容加密。 除上述关键字段外,AEC、ANS 和 AGC 的其余参数是推荐初始值,不代表所有设备的最佳值。完成基础接入后,应根据设备的扬声器音量、Mic 灵敏度、声学结构和典型噪声环境进行回声、双讲、降噪和音量测试,再调整相关参数。 ## 3. 联调检查 [#3-联调检查] 完成配置后,按以下顺序检查: 1. 确认 Mic 和 Ref 都是 16 kHz、16-bit PCM,每路每帧包含 320 个采样点。 2. 抓取发送前的音频数据,确认左声道为 Mic,右声道为 Ref,交织顺序正确,单帧长度为 1280 字节。 3. 确认 Ref 来自实际的扬声器播放链路,不是麦克风信号或静音数据。 4. 确认设备每 20 ms 发送一帧完整音频,并检查发送接口返回值。 5. 确认 Start 请求中的采样率、输出编码和订阅声道数与设备配置一致。 6. 在安静、持续噪声、近端讲话、远端播放和双方同时讲话等场景下测试回声抑制、降噪、音量稳定性和打断效果。 ## 4. 常见问题 [#4-常见问题] | 现象 | 检查项 | | --- | --- | | 仍能听到明显回声 | Ref 是否有效;左右声道是否交换;Mic 和 Ref 是否同步;`enable_aec` 是否为 `true` | | 对话侧收到静音或异常音频 | PCM 位宽、字节序、帧长度、采样率、`data_type` 和发送接口返回值 | | 回复音频无法播放 | `output_audio_codec` 是否为 `G722`;RTSA 是否开启 `enable_audio_decode`;播放器格式是否匹配 SDK 输出 | | 播放卡顿或帧间隔不均 | RTSA 是否开启 `enable_audio_jitter_buffer`;音频接收回调和播放线程是否被阻塞 | | AEC 效果随时间下降 | Mic 和 Ref 的时钟是否持续漂移;采集与播放链路是否发生动态延迟变化 | 完整的创建智能体请求字段说明请参考[创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)。