诊断与日志

在接入和使用 TiRTC AI 对讲时，如果遇到异常情况，可以通过本文提供的自助排障清单和日志特征进行快速定位。

常见问题排查指南

遇到故障时，首先尝试在下方表格中找到对应的现象，并根据建议收集日志或执行检查：

现象	诊断方向 / 日志特征	排查建议
获取角色失败 / 返回空	服务端返回 HTTP 401 或 403，或是控制台列表中找不到该角色。	先在探鸽开放平台确认应用与角色存在。如果是 401，请检查 TGV1 鉴权中的时间戳与 AppId。
获取凭证失败	调用 /v1/token/aichat 时返回 HTTP 401，错误码 AuthFailure.SignatureFailure 等。	检查 TGV1 签名计算，特别是 CanonicalURI 必须与请求路径强一致，X-Tg-Date 不能偏差过大，以及检查 Body 的 SHA-256 是否正确。
TiRtcWhipConnect 失败	回调中的 err != 0，或者控制台报错超时。	重新申请凭证，凭证可能已过期。确认设备所处网络没有屏蔽 UDP 端口，DNS 能正确解析 api-tirtc.tange365.com 等探鸽云端域名。
建连成功但无回复	从网络抓包或 SDK 日志中看到未发出 start_session 请求。或者服务端返回 Invalid audio format 报错。	检查 TIRTC_AI_SIGNALING (如 0x2100) 命令通道是否发送了合法的 JSON-RPC start_session 请求，确保其中的 device_id 与申请凭证时一致。
上行说话无字幕	发送了音频，但没有收到 caption 下发事件。	检查 fi.stream_id、fi.media、以及 fi.flags（如 TIRTC_AUDIOSAMPLE_16K16B1C）是否与 start_session 中的声明完全对应。如果格式错乱会导致云端解码或 VAD 识别失败。
有字幕但无声音	收到 caption 事件并在更新，但设备端未发声。	检查设备下行解码逻辑。确保已按 start_session 响应中的 output_audio 格式初始化了解码器。确认播放缓冲区没有在此时触发了打断（interrupt）的清空逻辑。
打断无效	用户按键或说话打断时，播报仍继续。	确认设备已发出 JSON-RPC interrupt 方法，且使用的是正确的保留命令字（如 0x2100）。
会话无法彻底结束	第二次调用 AI 对讲建连时报错或串音。	确认是否已将“主动结束、平台下发 end_session、断网、业务超时”等场景全部归口到同一个本地资源销毁函数，彻底执行 TiRtcClose 和流清理。

提交流程与必要信息

如果在自助排查后问题依然无法解决，请在联系技术支持或提交工单时，务必包含以下信息，以便我们快速定位：

1. 环境与标识信息
   • 设备 device_id
   • 应用 AppId 以及对应的 role_id
   • 问题发生的确切时间及你所在的时区
2. 设备端 SDK 日志
   • 提供 TiRTC SDK 的运行日志文件或调用日志上传接口后得到的 logId。
3. 关键载荷截图或文本
   • 脱敏的本次 peer_id 字符串（请不要提供完整的加密 token）。
   • 发送 start_session 的脱敏 payload 文本、发送时指定的 fi.media 和 fi.flags。
4. 复现路径
   • 从“获取 role_id -> 申请凭证 -> 建立连接 -> 发送 start_session -> 发音频 -> 接收事件”的最短必现路径说明。