89 lines
4.0 KiB
Markdown
89 lines
4.0 KiB
Markdown
|
# 简化聊天接口（DIRECT-CHAT-1）
|
|||
|
|
|
|||
|
|
本文保留旧版 DIRECT-CHAT-1 协议说明。当前实现以 [老人专属智能体与设备聊天接口](elder-agent-flow.md) 为准：每位老人一个智能体，S2S 配置由服务器提交火山，不再发给设备。
|
|||
|
|
|
|||
|
|
## 流程
|
|||
|
|
|
|||
|
|
1. 设备向后端请求本次聊天参数。
|
|||
|
|
2. 设备将 params 交给火山 RTC SDK，直接和火山进行语音聊天。
|
|||
|
|
3. 火山通过每通独立的回调地址给后端发送文字，后端保存，设备不上传文字。
|
|||
|
|
4. 设备停止 SDK，通知后端本次聊天结束。
|
|||
|
|
|
|||
|
|
基础地址：`https://121.41.46.238`。设备接口使用已有设备身份鉴权和 HTTPS，不再增加会话加密/证明包。
|
|||
|
|
|
|||
|
|
## 1. 开始聊天
|
|||
|
|
|
|||
|
|
`POST /api/v1/device/chat/start`
|
|||
|
|
|
|||
|
|
设备生成本次唯一 session_id，重试时不变；boot_id 为本次开机编号。
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{"session_id":"<本次会话UUID>","boot_id":"<本次开机UUID>"}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
成功响应的 data：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"session_id": "<原会话UUID>",
|
|||
|
|
"bot_id": "<火山智能体ID>",
|
|||
|
|
"params": {
|
|||
|
|
"PlatformTaskID": "<原会话UUID>",
|
|||
|
|
"Config": {
|
|||
|
|
"S2SConfig": "<后端现有豆包配置对象>",
|
|||
|
|
"MemoryConfig": {"Enable": false},
|
|||
|
|
"SubtitleConfig": {"SubtitleMode": 1, "DisableRTSSubtitle": true}
|
|||
|
|
},
|
|||
|
|
"AgentConfig": {
|
|||
|
|
"WelcomeMessage": "你好，今天想聊些什么？",
|
|||
|
|
"ServerMessageURLForRTS": "<本通专属回调地址>",
|
|||
|
|
"ServerMessageSignatureForRTS": "<本通回调校验值>"
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
"lease_expires_at_ms": 0,
|
|||
|
|
"expires_at_ms": 0
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
上面 S2SConfig 和时间戳为示意，不是可直接运行的完整配置。params 序列化后传给 SDK；PlatformTaskID 由设备 SDK 适配层用于 GetRTCConfig 的唯一任务编号。
|
|||
|
|
|
|||
|
|
记忆：本版读取平台当前已授权的记忆内容，放进 S2SConfig 的会话上下文；不启用火山共享原生记忆库，不给设备数据库密码。不能声称这一版支持火山自动长期记忆同步。
|
|||
|
|
|
|||
|
|
内部保活复用 start 接口，每 10 秒自动请求一次同一 session_id，参数保持不变。租约最长 45 秒；解绑、授权撤回、记忆撤销或失联时停止音频。小程序不参与这一步，没有新增 heartbeat 接口。
|
|||
|
|
|
|||
|
|
缺少 S2S 配置返回 CHAT_S2S_CONFIG_REQUIRED；无需发布原来的 H01–H12 profile。首次供应商设备注册仍只做一次，单独保存设备级凭据，不是每通聊天步骤。
|
|||
|
|
|
|||
|
|
## 2. 火山回传文字
|
|||
|
|
|
|||
|
|
`POST /callbacks/v1/volcengine/chat?session_id=<本次会话UUID>`
|
|||
|
|
|
|||
|
|
使用火山原生格式：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{"message":"<Base64字幕消息>","signature":"<本通回调校验值>"}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
后端验证 signature、解码字幕，按 session_id 保存。相同说话人、roundId、sequence 的重复文字只存一次；不能用“设备最新会话”猜测归属。结束后晚到的文字仍写回原会话。
|
|||
|
|
|
|||
|
|
收到每句最终文字就保存，不要求火山最后一次性返回整段记录。未知说话人保留 UNKNOWN，不冒充用户记忆。字幕没有完整性结束证明时，不宣称记录百分之百完整。
|
|||
|
|
|
|||
|
|
## 3. 结束聊天
|
|||
|
|
|
|||
|
|
`POST /api/v1/device/chat/end`
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{"session_id":"<本次会话UUID>","reason":"hangup","sdk_stopped":true}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
reason 可为 hangup、start_failed、disconnected、reboot、timeout。sdk_stopped 只有 SDK 确认停止才为 true。
|
|||
|
|
|
|||
|
|
成功响应 data：`{"session_id":"<本次会话UUID>","ended":true}`。
|
|||
|
|
|
|||
|
|
失败自动重试；断电保留待结束编号，重新联网后补报。服务端已接受结束的会话不能重新启动。此响应表示平台已登记结束，不冒充火山远端停止证明，不再要求人工对账才能开下一通。
|
|||
|
|
|
|||
|
|
## 小程序记录
|
|||
|
|
|
|||
|
|
沿用上一版的 `/api/v1/memories/calls/query` 和 `/api/v1/memories/calls/turns`，小程序页面无需另换接口。
|
|||
|
|
|
|||
|
|
官方依据：[硬件动态配置](https://www.volcengine.com/docs/6348/1807452)、[实时字幕](https://www.volcengine.com/docs/6348/1337284)。部署、编译测试与真实火山对话实测是不同验证层次，实测结果以交付记录为准。
|