AI实时互动FAQ

功能相关

• AI智能体是否需要部署在客户源站上

• 大模型部署在阿里云百炼平台上，怎么跟AI智能体进行联动

集成相关

• 启动通话时报错

• 开始消息对话时客户端报错“AgentNotFound”

• 开始消息对话时，客户端报错“UnsupportedWorkflowType”

• 如何调整客户端音频采集采样率

• 如何调整智能体播报采样率

AI智能体是否需要部署在客户源站上

AI智能体是阿里云提供的公共云服务，无需客户进行云端部署。客户只需通过控制台的界面配置并调用OpenAPI，即可构建和调用AI智能体。

大模型部署在阿里云百炼平台上，怎么跟AI智能体进行联动

AI智能体在产品设计上已与阿里云百炼实现了打通，您只需在控制台指定必要的参数，即可调用阿里云百炼上的大模型。详情请参见LLM 大语言模型。

启动通话时报错

开始消息对话时客户端报错“AgentNotFound”

在客户端代码中检查agentId及区域的设置是否配置正确。

在智能媒体服务控制台左侧菜单选择AI实时互动 > 智能体管理，确认页面顶部所选区域与代码中配置的区域一致，在智能体列表的智能体ID/名称列获取正确的 agentId。

客户端代码：

String mAgentId = "XXX";          // 智能体ID -> 控制台创建消息对话智能体的ID
String mRegion = "cn-shanghai";   // 设置智能体所在区域 -> 控制台消息对话智能体所在的区域
ARTCAIChatAgentInfo agentInfo = new ARTCAIChatEngine.ARTCAIChatAgentInfo(mAgentId, mRegion)

// 智能体ID -> 控制台创建消息对话智能体的ID
let agentInfo = ARTCAIChatAgentInfo(agentId: "xxxx")
// 设置智能体所在区域 -> 控制台消息对话智能体所在的区域
agentInfo.region = "cn-shanghai"

开始消息对话时，客户端报错“UnsupportedWorkflowType”

当错误详情是“The specified workflowType \"VoiceChat\" is not supported by this interface. Please use a compatible workflowType: [\"MessageChat\"]”时，请检查智能体Id，该智能体的Id关联的工作流类型是否是“消息对话”。

在智能体管理列表页面中，找到目标智能体，查看其对应的智能体工作流ID列，确认关联的工作流类型是否为消息对话（MessageChat）。

如何调整客户端音频采集采样率

AI实时互动在采集端目前对音频参数如下：

• 48K采样率，单声道

• 16K采样率，单声道

AICallKit SDK默认支持48K采样率，如果需要切换到16K，可以参考如下示例代码：

self.engine.audioConfig = ARTCAICallAudioConfig(audioProfile: .BasicQualityMode, audioScenario: .MusicMode)
// 调用其他api
...  
// 发起通话
self.engine.call(...)

ARTCAICallEngine.ARTCAICallConfig artcaiCallConfig = new ARTCAICallEngine.ARTCAICallConfig();
artcaiCallConfig.audioConfig.audioProfile = ARTCAICallAudioBasicQualityMode;
engine.init(artcaiCallConfig);

如何调整智能体播报采样率

AI实时互动目前在智能体音频播报参数如下：

• 48K采样率，单/双声道

• 16K采样率，单声道

AI实时互动默认支持48K采样率单声道，需要在启动通话的接口进行调整，不同的发起通话方式的调整播报采样率的方法如下：

方式一：通过服务端生成AI智能体通话实例发起通话

您可以通过新增AgentConfig参数，构造AIAgentConfig中的ExperimentalConfig字段。

// AudioQualityMode：Integer    
// Rtc输出的采样率模式。
// 0: 48k单声道 
// 1: 48k双声道
// 2: 16k单声道
// ExperimentalConfig的值必须要为json字符串
{
    "ExperimentalConfig":"{\"AudioQualityMode\":2}"
}

方式二：通过服务端启动智能体实例发起通话

您可以通过新增AgentConfig参数，构造AIAgentConfig中的ExperimentalConfig字段。

// AudioQualityMode：Integer    
// Rtc输出的采样率模式。
// 0: 48k单声道 
// 1: 48k双声道
// 2: 16k单声道
// ExperimentalConfig的值必须要为json字符串
{
    "ExperimentalConfig":"{\"AudioQualityMode\":2}"
}

方式三：通过客户端call接口发起通话

如果已经使用callConfig方式来作为启动通话的参数，并且使用call(xxx)接口来创建与开始通话，那么可以使用该方式修改智能体播报采样率。

let callConfig = ...   // 创建并初始化ARTCAICallConfig，可以参考使用指南文档
let agentConfig = ARTCAICallAgentConfig()         // 创建ARTCAICallAgentConfig对象
agentConfig.experimentalConfig = [
    "AudioQualityMode": 2
]
...                                                  // 根据业务需要设置参数
callConfig.agentConfig = agentConfig
self.engine.call(config: callConfig)                 // 发起通话

ARTCAICallEngine.ARTCAICallConfig artcaiCallConfig = new ARTCAICallEngine.ARTCAICallConfig();
artcaiCallConfig.agentConfig.experimentalConfig = new JSONObject();
try {
    artcaiCallConfig.agentConfig.experimentalConfig.put("AudioQualityMode", 2);
} catch (JSONException e) {
    e.printStackTrace();
}
engine.init(artcaiCallConfig);

集成时提示“找不到应用或应用被禁用”如何处理？

集成时需使用智能体 ID（而非百炼应用 ID）：在智能体详情页获取对应的应用标识与密钥，并确保服务端生成鉴权 Token 时使用的智能体配置与客户端一致。

如何向百炼应用或工作流传递自定义参数？

• 通过 SDK 传参时，业务参数需嵌套在 biz_params 字段下传入（例如将参数放入百炼应用参数的 biz_params 对象中），直接平铺传入不会生效。

• 每次通话需传入客户信息时，可通过 UserData 传递。

• 语音通话的“人设”可通过透传给百炼提示词实现；头像、人设、音色等参数可在发起通话时通过智能体配置对象动态传入。

通话与消息连接类报错如何排查？

• 提示频道 ID 已被占用：每次发起通话需生成新的唯一频道 ID，通话结束后及时挂断并等待资源释放，并发场景避免复用同一频道 ID。

• 发送消息提示未连接：需先启动智能体并监听连接状态，监听到已连接事件后再发送消息。

• 引擎状态回调始终未就绪、启动会话无响应：需注册获取鉴权 Token 的回调，并由服务端下发 Token 完成鉴权；监听事件建议使用持续监听而非一次性监听。

智能体响应慢、用户话未说完就被打断怎么调？

• 响应慢：检查语义分句等待时长（turnDetectionConfig 中的语义等待参数），适当调小可明显提升响应速度。

• 被提前打断：可通过智能体配置中的用户静默等待参数调整，当前最大支持约 1200 毫秒。

• 对讲机模式下智能体回答两遍：多为语音活动检测与按住说话同时拾音导致两次独立输入，需确保对讲机模式生效后再开启拾音。

• 自定义音色不生效：语音合成配置需补充与音色匹配的语言标识，并确认音色已在对应地域审核通过；识别语言可通过智能体配置中的识别语言参数指定。

智能体回调收不到如何排查？

• 回调地址需为 HTTPS 且返回公网 CA 签发的完整证书链，建议使用阿里云免费 SSL 证书。

• 服务端需正确接收 POST 请求并返回 200；并确认已调用启动智能体实例的接口获取实例标识。

• 回调数据不包含大模型 Token 消耗信息，Token 用量需到百炼控制台查看。

端侧集成与能力边界

• 微信 H5：支持。需将页面部署在已备案的 HTTPS 域名下并通过 web-view 加载，首次调用麦克风需用户授权，并关注实时通信能力的兼容性，建议真机验证。

• 小程序：不支持直接使用实时通信拉流协议，同样需通过 web-view 嵌入 HTTPS 域名下的 Web 页面，并配置业务域名。

• 实时通信服务域名由系统自动分配与绑定，无需单独配置媒体传输域名。

• 能力边界：支持语音输入，文字可通过发送文本接口传入，输出始终为语音；支持接入符合 OpenAI 接口规范的自训练模型，需提供模型标识、密钥与 HTTPS 地址；可在工作流中通过大语言模型选项配置已发布的百炼智能体。