功能概述
本文介绍三段式(Cascade,
ASR → LLM → TTS)模式的最短接入路径,五步跑通一轮语音对话:签发 UserSig → 客户端集成 SDK 进房 → 服务端创建 AI 对话任务 → 监听事件回调 → 结束任务
创建任务后,AI Bot 以虚拟用户身份加入 TRTC 房间并订阅指定用户的音频流,用户开口说话即开始一轮「识别 → 推理 → 播报」的实时对话,全程可打断。
前提条件与配额
项目 | 要求 |
TRTC 服务 | 已开通并完成实名认证。 |
SdkAppId | TRTC 应用 ID,用于所有服务端接口调用。 |
房间号 | 支持数字房间号( RoomIdType=0)与字符串房间号(RoomIdType=1,推荐)。 |
接口频率 | 20 次/秒。 |
单应用并发 | 100 个任务。 |
空闲回收 | 默认 30 秒( AgentConfig.MaxIdleTime 可调,范围 5~86400 秒)。 |
说明:
超出频率或并发上限时接口返回
FailedOperation.RestrictedConcurrency / FailedOperation.RequestLimitExceeded,请实现指数退避重试。接入步骤
步骤1:签发 UserSig
业务后端为 App 用户和 AI Bot 各签发一份 UserSig:
Bot 的 UserSig:即创建任务时
AgentConfig.UserSig,由业务后端保管;App 用户的 UserSig:由业务后端下发给客户端,用于进房。
步骤2:客户端集成 TRTC SDK 并进房
// 1. 创建 TRTC 实例TRTCCloud trtc = TRTCCloud.sharedInstance(context.getApplicationContext());// 2. 开启音量回调与 VAD 通知,用于 UI 展示用户是否正在说话TRTCAudioVolumeEvaluateParams volumeParams = new TRTCAudioVolumeEvaluateParams();volumeParams.enableVadDetection = true;trtc.enableAudioVolumeEvaluation(true, volumeParams);// 3. 开启音频采集(通话音质)trtc.setSystemVolumeType(TRTCSystemVolumeTypeMedia);trtc.startLocalAudio(TRTC_AUDIO_QUALITY_SPEECH);// 4. 如需静音采集,可设置采集音量为 0trtc.setAudioCaptureVolume(0);// 5. 进房TRTCParams params = new TRTCParams();params.sdkAppId = <sdkAppId>;params.userId = <localUserId>;params.userSig = <userSig>;params.roomId = <roomId>;params.role = TRTCRoleAnchor;trtc.enterRoom(params, TRTC_APP_SCENE_VIDEOCALL);
进房成功条件:
TRTCCloudListener.onEnterRoom(result > 0)。步骤3:服务端创建 AI 对话任务
{"SdkAppId": 14000000,"RoomId": "12345","RoomIdType": 0,"ConversationMode": "Cascade","AgentConfig": {"UserId": "test2","UserSig": "eJyrVgrxCdYrzkxXslJQyvEs...","TargetUserId": ["Trtc_User_0"],"MaxIdleTime": 60,"SubtitleMode": 0,"TurnDetectionMode": "Auto","TTSPushRoomParams": { "UserId": "tts-bot-001" }},"STTConfig": {"Provider": "trtc","Params": "{\\"engine_model_type\\":\\"bigmodel\\",\\"language\\":\\"zh\\",\\"vad_silence_time\\":\\"1000\\"}"},"LLMConfig": {"LLMType": "openai","Model": "gpt-4o-mini","APIKey": "<YOUR_API_KEY>","APIUrl": "https://api.openai.com/v1/chat/completions","SystemPrompt": "你是一个简洁的对话助手。","Timeout": 20000,"Temperature": 0.7},"TTSConfig": {"Provider": "trtc","Params": "{\\"Model\\":\\"flow_02_turbo\\",\\"VoiceId\\":\\"v-female-R2s4N9qJ\\",\\"Speed\\":1.0}"},"DialogConfig": {"InterruptMode": 0,"InterruptSpeechDuration": 200,"WelcomeMessage": "你好,我是AI助手,有什么可以帮你的?"}}
关键字段速览:
字段 | 说明 |
AgentConfig.UserId / UserSig | AI Bot 的房间身份与进房凭证。 |
AgentConfig.TargetUserId | Bot 订阅哪些用户的音频(当前最多 1 个)。 |
AgentConfig.MaxIdleTime | 房间无人说话时的空闲回收时间。 |
STTConfig / LLMConfig / TTSConfig | 三段链路配置,均可更换厂商。 |
DialogConfig.WelcomeMessage | Bot 进房后自动播报的欢迎语(便于验证链路)。 |
DialogConfig.InterruptMode | 打断模式(0=自动 / 1=手动 / 2=关键词)。 |
接口返回
TaskId 即表示任务创建成功,Bot 已进房并订阅目标用户音频。配置了 WelcomeMessage 时,Bot 进房后会自动播报欢迎语,可直接验证 TTS 链路;随后对 Bot 说一句话,即开始一轮完整对话。说明:
TTSPushRoomParams.UserId 用于指定 TTS 语音播报流所使用的独立用户 ID。如果省略该参数,则默认使用 AgentConfig.UserId 作为播报方。使用独立 ID 可便于客户端区分 Bot 的主逻辑身份和播报身份。步骤4:配置事件回调并校验签名
在控制台(或通过工单)配置业务后端的回调 URL 与回调密钥,并实现
X-TRTC-Signature 签名校验,即可落库 ASR / LLM 结果、AI 状态流转、任务启动 / 结束等事件。步骤5:结束任务
说明:
也可依赖空闲回收:房间内持续
MaxIdleTime 无有效音频,任务自动结束。验证对话链路
任务运行期间向 Bot 说一句话,可通过三个通道确认链路工作正常:
