AI降临派 TCP 通信协议文档

Version 2.4
Last Updated: 2025-07-15

1. 文档信息

1.1 版本历史

版本	日期	描述
2.5	2025-01-15	新增VAD（语音活动检测）功能，支持auto/manual两种模式，自动检测用户说话结束
2.4.1	2025-08-11	新增入参 input_audio_format，支持裸 Opus 输入（2字节长度前缀 + 60ms 帧），ASR 前统一转 PCM；文档更新
2.4	2025-07-15	新增SPEAK消息类型，支持让角色直接说指定内容
2.3	2025-07-10	修改连接超时为5分钟，认证超时为5秒，心跳包不再推荐，新增关闭连接操作
2.2	2025-04-23	新增音频格式选择功能，支持PCM和Opus格式
2.1	2025-03-15	支持新版模型AnyoneV2.1
1.32	2025-01-03	增加认证消息可选参数，新增prompt回执消息
1.31	2024-12-29	消息头尾标记改为##START和##END，修改了文档中一些误导性描述
1.30	2024-12-27	统一消息结构，新增END_FRAME帧类型

2. 系统架构

2.1 服务器配置

测试环境会有最新的功能，但每周会不定期部署，可能会造成服务闪断。
正式环境只有当所用功能都测试完毕后才会升级，升级频率一般在一到两个月一次。

测试环境

beta-tcp.adventists.cn:8009

正式环境

stable-tcp.adventists.cn:8007

开发环境

nightly-tcp.adventists.cn:8010

2.2 性能参数

认证超时：5秒

会话超时：300秒（5分钟）

最大消息大小：64KB

3. 连接管理

3.1 连接建立

客户端发起TCP连接

服务器接受连接

客户端必须在5秒内发送认证消息

认证成功后建立会话

3.2 连接维护

会话超时时间：300秒（5分钟）

心跳包机制：

# 客户端发送心跳包
##START\x0500000000[0000]##PING##END

# 服务器响应
##START\x0500000000[0000]##INFO:PONG##END

注：

心跳包使用 STATUS 类型（\x05）

使用系统任务ID（00000000）

使用固定序列号（0000）

心跳包功能仍可使用，但不再作为推荐的连接保持方式

3.3 连接关闭

客户端可以主动关闭连接，也可以等待服务器超时关闭。

3.3.1 主动关闭

客户端可以发送关闭消息主动断开连接：

##START\x0500000000[0000]##DISCONNECT##END

3.3.2 关闭响应

服务器收到关闭消息后会响应：

##START\x0500000000[0000]##INFO:DISCONNECT 3 seconds##END

3.3.3 关闭流程

客户端发送关闭消息

服务器发送关闭响应

等待3秒后服务器关闭TCP连接

客户端检测到连接关闭

3.3.4 异常关闭

如果客户端直接断开TCP连接，服务器会检测到并清理相关资源

如果服务器异常关闭，客户端应实现重连机制

4. 消息协议

4.1 基础消息结构

所有消息遵循统一格式：

##START[消息类型][任务ID][序列号][消息内容]##END

注：方括号[]仅用于表示格式，实际数据中不包含

4.2 消息类型定义（1字节）

AUTH        : b'\x01'  # 认证消息
AUDIO_FRAME : b'\x02'  # 音频帧数据
END_FRAME   : b'\x03'  # 结束帧标记
TEXT        : b'\x04'  # 文本消息
STATUS      : b'\x05'  # 状态消息（客户端可用于心跳包）
MCP         : b'\x06'  # MCP消息（可选扩展）
SPEAK       : b'\x07'  # 说指定内容（2.4新增）

4.3 消息字段说明

4.3.1 帧标记

起始标记：b'##START'

结束标记：b'##END'

4.3.2 消息类型 (1字节)

使用单字节表示消息类型

有效值：b'\x01' 到 b'\x05'

4.3.3 任务ID (8字节)

固定8字节的ASCII字符串

特殊值：00000000（用于系统消息）

其他值：客户端自定义，只要保证8字节长度即可

建议使用：字母、数字的组合

示例：

00000000 - 系统消息

task0001 - 普通任务

abcd1234 - 普通任务

4.3.4 序列号 (4字节)

固定4字节的ASCII字符串

范围：0000-9999

按顺序递增

特殊值：0000（用于状态消息）

5. 认证机制

5.1 认证消息格式

##START\x0100000000[0000]JWT_TOKEN##[参数1]:[值1]##[参数2]:[值2]...##END

5.2 可选参数列表

参数名	类型	默认值	说明
voiceid	string	角色默认音色	本轮对话希望使用的音色，如不填，会使用角色默认音色
lang	string	string	语言设置，可使用自然语言配置， "default", "auto", "中文", "English" , "JA" ,"kr"
format	string	pcm	输出音频格式设置，影响服务器返回的音频数据，可选值：`pcm`, `opus`
input_audio_format	string	pcm	输入音频格式设置，影响客户端上行的音频解析，可选：`pcm`，`opus`（裸流：2字节长度前缀 + 60ms 帧）
mode	string	manual	音频处理模式，可选值：`manual`（手动模式）, `vad`（自动VAD模式）
emoji_mode	string	false	表情包模式，可选值：`true`（默认模式，25种表情）, `dimi`（DIMI模式，3500种表情）, `false`（关闭）
voice_print	boolean	false	声纹识别开关
device_id	string		推荐填写设备ID，用于单设备登录

5.3 认证示例

# 基础认证（仅token）
##START\x01000000000000JWT_TOKEN##END

# 带单个参数
##START\x01000000000000JWT_TOKEN##voiceid:voice1##END

# 带多个参数
##START\x01000000000000JWT_TOKEN##voiceid:voice1##stage_mode:true##fast_mode:true##END

# 设置输出音频格式为 opus（下行）
##START\x01000000000000JWT_TOKEN##format:opus##END

# 设置输入音频格式为裸 Opus（上行）
##START\x01000000000000JWT_TOKEN##input_audio_format:opus##END

# 设置为auto模式（启用VAD自动检测）- 2.5新增
##START\x01000000000000JWT_TOKEN##mode:auto##input_audio_format:opus##END

# 使用PCM格式的auto模式
##START\x01000000000000JWT_TOKEN##mode:auto##input_audio_format:pcm##END

5.4 认证响应

成功：##START\x0500000000[0000]##INFO:认证成功，NPCID: <npcid>, 模式: <mode>##END

失败：##START\x0500000000[0000]##ERROR:token error##END

5.5 VAD模式说明（2.5新增）

5.5.1 Manual模式（默认）

客户端完全控制音频录制的开始和结束

必须发送END_FRAME来标记音频结束

兼容所有现有客户端实现

适用于按键说话、手动控制的场景

5.5.2 Auto模式（VAD自动检测）

服务器通过VAD自动检测用户说话的开始和结束

支持PCM和Opus格式：推荐使用input_audio_format:opus以获得更好的性能

客户端无需发送END_FRAME

服务器主动发送监听状态消息

适用于免提对话、自然交互的场景

5.5.3 监听状态消息（Auto模式专用）

服务器会主动发送监听状态消息给客户端：

# 开始监听
##START\x05[任务ID][0000]##LISTEN:{"session_id":"<会话ID>","type":"listen","state":"start","mode":"auto"}##END

# 停止监听
##START\x05[任务ID][0000]##LISTEN:{"session_id":"<会话ID>","type":"listen","state":"stop","mode":"auto"}##END

# 噪音过滤提示
##START\x05[任务ID][0000]##INFO:检测到噪音或空白，继续监听##END

5.6 快速开始（PCM，推荐起步）

推荐在首版集成中使用 PCM，接入最简单：

认证阶段无需设置 format/input_audio_format（或均设为 pcm）

上行直接发送 16kHz、单声道、16bit PCM 字节（可按 60ms 分帧，但非必需）

发送完一段语音后务必发送 END_FRAME

下行将收到 PCM 音频帧，直接播放或按需缓存即可。

6. 数据传输

6.1 文本消息传输

6.1.1 客户端发送

1. 文本帧：
##START\x04[任务ID][0000][文本内容]##END

2. 结束帧：
##START\x03[任务ID][0001]##END

6.1.2 服务器响应

1. 提示词回执：
##START\x05[任务ID][0000]##INFO:prompt: [提示词内容]##END

2. 响应文本：
##START\x04[任务ID][0000][响应内容]##END

3. 音频数据（如果有）：
##START\x02[任务ID][0001][音频数据1]##END
##START\x02[任务ID][0002][音频数据2]##END
...

4. 结束帧：
##START\x03[任务ID][最后序号+1]##END

6.2 音频消息传输

6.2.1 客户端发送

1. 音频帧序列：
##START\x02[任务ID][0000][音频数据1]##END
##START\x02[任务ID][0001][音频数据2]##END
...

2. 结束帧：
##START\x03[任务ID][最后序号+1]##END

6.2.2 服务器响应

1. 文本响应：
##START\x04[任务ID][0000][回应文本]##END

2. 音频响应序列：
##START\x02[任务ID][0001][音频数据1]##END
##START\x02[任务ID][0002][音频数据2]##END
...

3. 结束帧：
##START\x03[任务ID][最后序号+1]##END

6.2.3 音频格式说明（入/出分离）

输出音频格式由 format 控制：pcm 或 opus

opus 为裸流：每帧 60ms，帧前有 2 字节大端长度前缀，负载为连续的若干帧级联；服务器会尽量将多个完整帧打包到一个网络帧发送

输入音频格式由 input_audio_format 控制：pcm 或 opus

当为 opus 时，客户端需采用与“出”一致的裸 Opus 帧流（2 字节长度前缀 + 60ms 帧，采样率 16k，单声道）。服务器端在 ASR 前将其统一解码为 PCM 再处理

6.2.4 进阶指南：Opus（可选）

适用场景：移动网络、带宽受限或需降低流量成本时

开启步骤：

下行：认证时设置 format:opus

上行：认证时设置 input_audio_format:opus

打包策略：每帧 60ms，帧前 2 字节大端长度，多个帧可顺序级联发送；每个网络包可包含任意数量的完整帧

对齐原则：务必保持每个“长度前缀 + 帧”结构完整，不要跨包拆分单帧

6.2.4.1 入端 Opus 帧流规范（input_audio_format=opus）

编码与帧长：Opus，60ms/帧（16kHz 单声道，约 960 样本/帧）

帧边界：每帧前置 2 字节“大端”无符号帧长，随后紧跟该帧的 Opus 载荷

载荷组织：多个“长度前缀 + 帧”可以顺序级联形成上行负载

网络打包：

支持多种策略：1 帧/包，或多帧聚合成 1 个包均可

建议每个 AUDIO_FRAME 的负载大小控制在约 1KB 左右以内，以减少分片与粘包风险

严禁跨包拆分单个“长度前缀 + 帧”结构（必须保持帧完整）

结束标志：一段语音结束时必须发送 END_FRAME，服务器将聚合全部上行帧后统一识别

兼容性：若 input_audio_format 未设置或取值非法，服务器按 pcm 处理

6.3 SPEAK消息传输（2.4新增）

6.3.1 客户端发送

用于让角色直接说出指定内容（无需经过LLM推理，直接TTS播报）：

##START\x07[任务ID][序列号][文本内容]##END

[任务ID]：8字节，客户端自定义

[序列号]：4字节，建议从0000开始

[文本内容]：要让角色说的话

6.3.2 服务器响应

服务器收到SPEAK消息后，直接将文本内容转为音频流返回，格式与普通音频响应一致：

1. 音频数据帧：
##START\x02[任务ID][0001][音频数据1]##END
##START\x02[任务ID][0002][音频数据2]##END
...

2. 结束帧：
##START\x03[任务ID][最后序号+1]##END

3. 状态消息（可选）：
##START\x05[任务ID][0000]##INFO:语音合成完成##END

6.3.3 使用场景

需要让角色直接播报某段文本（如系统提示、外部指令等）

不经过推理，直接播报

适用于外部控制、定制播报等场景

7. 错误处理

7.1 错误消息格式

##START\x05[任务ID][0000]##ERROR:错误描述##END

7.2 错误类型

认证错误

TOKEN_ERROR: 令牌无效

AUTH_TIMEOUT: 认证超时

INVALID_NPCID: 无效的NPCID

协议错误

INVALID_FORMAT: 消息格式错误

SEQUENCE_ERROR: 序列号错误

FRAME_INCOMPLETE: 帧不完整

业务错误

AUDIO_PROCESS_ERROR: 音频处理失败

TEXT_PROCESS_ERROR: 文本处理失败

RESOURCE_ERROR: 资源不可用

8. 最佳实践

8.1 实现建议

使用帧标记正确解析消息边界

实现断线重连机制

维护心跳检测

合理设置超时时间

8.2 性能优化

控制音频帧大小

使用消息队列

实现消息压缩

优化内存使用

9. 示例

9.1 完整会话流程（PCM，推荐起步）

# 认证（不显式设置格式，默认上下行均为 PCM）
C -> S: ##START\x01000000000000JWT_TOKEN##voiceid:voice1##END
S -> C: ##START\x05000000000000##INFO:认证成功，NPCID: <npcid>##END

# 文本对话
C -> S: ##START\x04123456780000你好##END
C -> S: ##START\x03123456780001##END

S -> C: ##START\x04123456780000你好，很高兴见到你##END
S -> C: ##START\x02123456780001[音频数据1]##END
S -> C: ##START\x02123456780002[音频数据2]##END
S -> C: ##START\x03123456780003##END

9.2 进阶示例（Opus Manual模式）

# 认证（下行与上行均启用 Opus）
C -> S: ##START\x01000000000000JWT_TOKEN##voiceid:voice1##format:opus##input_audio_format:opus##END
S -> C: ##START\x05000000000000##INFO:认证成功，NPCID: <npcid>, 模式: manual##END

# 上行音频（帧流：2字节长度前缀 + 60ms 帧，可多帧/包）
C -> S: ##START\x02task00010000[长度+帧][长度+帧]...##END
...
C -> S: ##START\x03task00010001##END

# 下行音频（服务器按多帧尽量聚合打包返回）
S -> C: ##START\x02task00010001[音频数据1]##END
S -> C: ##START\x02task00010002[音频数据2]##END
S -> C: ##START\x03task00010003##END

9.3 Auto模式示例（VAD自动检测）- 2.5新增

# 认证（启用auto模式 + Opus格式）
C -> S: ##START\x01000000000000JWT_TOKEN##mode:auto##input_audio_format:opus##format:opus##END
S -> C: ##START\x05000000000000##INFO:认证成功，NPCID: <npcid>, 模式: auto##END

# 服务器主动发送开始监听
S -> C: ##START\x05000000000000##LISTEN:{"session_id":"00000000","type":"listen","state":"start","mode":"auto"}##END

# 客户端开始发送音频流（无需END_FRAME）
C -> S: ##START\x02task00010000[长度+帧][长度+帧]...##END
C -> S: ##START\x02task00010001[长度+帧][长度+帧]...##END
...

# VAD检测到语音结束，服务器发送停止监听
S -> C: ##START\x05task00010000##LISTEN:{"session_id":"task0001","type":"listen","state":"stop","mode":"auto"}##END

# 服务器处理并返回响应
S -> C: ##START\x05task00010000##INFO:prompt: 用户说的话##END
S -> C: ##START\x04task00010000AI的回应文本##END
S -> C: ##START\x02task00010001[音频数据1]##END
S -> C: ##START\x02task00010002[音频数据2]##END
S -> C: ##START\x03task00010003##END

# 响应完成后，服务器重新开始监听
S -> C: ##START\x05000000000000##LISTEN:{"session_id":"00000000","type":"listen","state":"start","mode":"auto"}##END

# 循环：客户端继续发送音频，服务器自动检测...

# 强制结束对话示例
C -> S: ##START\x0500000000[0000]##STOP_VAD##END
S -> C: ##START\x0500000000[0000]##INFO:强制结束对话，处理当前音频##END
S -> C: ##START\x0500000000[0000]##LISTEN:{"session_id":"00000000","type":"listen","state":"start","mode":"auto"}##END

9.4 Auto模式噪音处理示例

# 客户端发送音频
C -> S: ##START\x02task00020000[环境噪音]##END
C -> S: ##START\x02task00020001[环境噪音]##END

# VAD检测到"语音结束"但STT识别结果无效
S -> C: ##START\x05task00020000##LISTEN:{"session_id":"task0002","type":"listen","state":"stop","mode":"auto"}##END
S -> C: ##START\x05task00020000##INFO:检测到噪音或空白，继续监听##END

# 服务器立即重新开始监听，无需用户重新操作
S -> C: ##START\x05task00020000##LISTEN:{"session_id":"task0002","type":"listen","state":"start","mode":"auto"}##END

10. 常见问题

10.1 连接问题

Q: 连接超时如何处理？
A: 服务器端会在300秒无数据交互后断开连接，客户端应该：

实现心跳机制保持连接活跃（可选）

在连接断开时自动重连

在重连后重新发送认证消息

或者主动发送关闭消息来断开连接

10.2 消息问题

Q: 如何确保消息完整性？
A: 通过帧起始标记（##START）和结束标记（##END）确保。

10.3 安全问题

Q: 如何保证通信安全？
A: 使用JWT认证

10.4 视频对话

Q: 如何进行视频对话？
A: 通过upload_image上传最近的图像记忆。角色挂载vision function,即可自动调用最近的图像记忆对话。
图像记忆的上传时机跟对话本身解耦，可以根据场景自行决定调用upload_image的时机，比如按下通话键时，或者每隔5秒钟等。

10.5 音频格式选择

Q: 如何选择合适的音频格式？
A:

PCM格式为无损格式，音质好但数据量大

Opus格式有压缩，数据量小但需要额外解码步骤

在带宽充足的场景下建议使用PCM

在带宽受限的场景下建议使用Opus

移动设备上通常建议使用Opus以节省流量

若需要上行也使用 Opus，请在认证时设置 input_audio_format:opus，并按"入端 Opus 帧流规范（6.2.4.1）"打包

10.6 VAD模式选择（2.5新增）

Q: Manual模式和Auto模式应该如何选择？
A:

Manual模式：

适用于按键说话的场景

完全由客户端控制录音时机

兼容性最好，支持所有音频格式

适合需要精确控制的应用

Auto模式：

适用于免提对话的场景

提供更自然的交互体验

支持PCM和Opus格式（推荐input_audio_format:opus）

自动过滤环境噪音

适合智能音箱、车载系统等场景

10.7 VAD相关问题

Q: Auto模式下如何处理网络延迟？
A: VAD处理在服务器端进行，网络延迟可能影响响应速度。建议：

使用稳定的网络连接

适当调整VAD参数（联系技术支持）

对于实时性要求极高的场景，考虑使用Manual模式

Q: Auto模式支持哪些音频格式？
A: Auto模式支持PCM和Opus两种格式：

PCM格式：无损音质，处理简单，适合本地网络

Opus格式：更好的压缩率，减少网络传输延迟，适合移动网络

推荐使用Opus格式以获得更好的实时性能

Q: Auto模式下频繁触发噪音检测怎么办？
A: 可能的原因和解决方案：

环境噪音过大：改善录音环境

麦克风灵敏度过高：调整客户端录音设置

VAD阈值不合适：联系技术支持调整参数

Q: Auto模式下如何强制结束当前对话？
A: 可以发送特殊的STATUS消息强制结束当前对话：

# 强制结束当前对话（仅Auto模式有效）
##START\x0500000000[0000]##STOP_VAD##END

功能说明：

立即处理当前累积的音频数据（如果有）

重置VAD状态

清空音频缓冲区

重新开始监听

仅在Auto模式下有效，Manual模式下会返回提示信息

使用场景：

用户想要立即结束当前说话

系统检测到异常情况需要重置

客户端需要主动控制对话流程

TCP接入

AI降临派 TCP 通信协议文档#

目录#

1. 文档信息#

1.1 版本历史#

2. 系统架构#

2.1 服务器配置#

测试环境#

正式环境#

开发环境#

2.2 性能参数#

3. 连接管理#

3.1 连接建立#

3.2 连接维护#

3.3 连接关闭#

3.3.1 主动关闭#

3.3.2 关闭响应#

3.3.3 关闭流程#

3.3.4 异常关闭#

4. 消息协议#

4.1 基础消息结构#

4.2 消息类型定义（1字节）#

4.3 消息字段说明#

4.3.1 帧标记#

4.3.2 消息类型 (1字节)#

4.3.3 任务ID (8字节)#

4.3.4 序列号 (4字节)#

5. 认证机制#

5.1 认证消息格式#

5.2 可选参数列表#

5.3 认证示例#

5.4 认证响应#

5.5 VAD模式说明（2.5新增）#

5.5.1 Manual模式（默认）#

5.5.2 Auto模式（VAD自动检测）#

5.5.3 监听状态消息（Auto模式专用）#

5.6 快速开始（PCM，推荐起步）#

6. 数据传输#

6.1 文本消息传输#

6.1.1 客户端发送#

6.1.2 服务器响应#

6.2 音频消息传输#

6.2.1 客户端发送#

6.2.2 服务器响应#

6.2.3 音频格式说明（入/出分离）#

6.2.4 进阶指南：Opus（可选）#

6.2.4.1 入端 Opus 帧流规范（input_audio_format=opus）#

6.3 SPEAK消息传输（2.4新增）#

6.3.1 客户端发送#

6.3.2 服务器响应#

6.3.3 使用场景#

7. 错误处理#

7.1 错误消息格式#

7.2 错误类型#

8. 最佳实践#

8.1 实现建议#

8.2 性能优化#

9. 示例#

9.1 完整会话流程（PCM，推荐起步）#

9.2 进阶示例（Opus Manual模式）#

9.3 Auto模式示例（VAD自动检测）- 2.5新增#

9.4 Auto模式噪音处理示例#

10. 常见问题#

10.1 连接问题#

10.2 消息问题#

10.3 安全问题#

10.4 视频对话#

10.5 音频格式选择#

10.6 VAD模式选择（2.5新增）#

10.7 VAD相关问题#