VoxCPM2 语音合成服务镜像

简介

基于 VoxCPM2 的实时语音合成（TTS）服务镜像，提供：

• WebSocket 鉴权接口（端口 8765）：供业务 / App 调用
• WebUI 控制台（端口 8080）：网页可视化操作与试听

已预装 Python 3.11、CUDA 12.8（cu128）flash-attn 及全部依赖，实例启动后服务自动运行，无需手动执行脚本。

运行环境

项目	版本
GPU 驱动 / CUDA	12.8
Python	3.11
深度学习框架	PyTorch（cu128）+ flash-attn
模型	VoxCPM2（默认路径 /models/VoxCPM2）

使用方式

1. 用本镜像创建 GPU 实例（建议选择与 12.8 驱动匹配的机型）。
2. 等待实例启动，服务会自动拉起，无需登录执行命令。
3. 访问入口（请将 <实例IP> 替换为控制台显示的实例 IP）：
   • WebSocket：ws://<实例IP>:8765
   • WebUI：http://<实例IP>:8080

端口

• 8765：WebSocket 鉴权接口
• 8080：WebUI 控制台

需在控制台「防火墙 / 自定义端口」中放行 8765、8080。

WebSocket 接口说明

协议概述

• 连接地址：ws://<实例IP>:8765
• 帧类型：文本帧（JSON）+ 二进制帧（float32 PCM 音频）
• 全双工：客户端指令与服务端消息并行，同一连接同时只有一个活跃合成任务（新 synthesize 会自动取消旧的）
• 音频格式：float32 LE、单声道、采样率 48000 Hz（以 ready / start 返回的 sample_rate 为准）；App 端在注入通话前需自行重采样到 16000 Hz

连接与鉴权流程

1. 连接建立后，服务端先下发 ready（含 auth_required、auth_enabled）。
2. 若 auth_required=true，客户端须在 AUTH_TIMEOUT（默认 5 秒）内发送 auth 帧，否则连接被关闭（策略码 1008）。
3. 校验通过后服务端下发 auth_ok，随后即可发送业务指令。

鉴权帧：

{"op":"auth","token":"<AUTH_TOKEN>"}

客户端 → 服务端指令

op	说明	关键字段
ping	心跳	无
test_connection	连通性测试	id（可选）
synthesize	文本合成（流式返回音频）	text（必填，≤300 字）、voice_id（可选，空=零样本）、id（可选）
add_voice	上传音频注册音色	voice_id（必填）、mode、prompt_text、audio_b64（wav base64，必填）
generate_voice	按文字描述生成音色	voice_id（必填）、description（必填，≤500 字）、script、mode
design_voice	按描述生成多个候选音色	description（必填）、script、count（默认 3）、seed
clone_preview	创建克隆预览（不正式注册）	mode、prompt_text、audio_b64（必填）
preview_synthesize	用预览音色合成样音	preview_id（必填）、text（必填，≤300 字）
register_preview	将预览音色正式注册	preview_id（必填）、voice_id（必填）
preprocess_audio	参考音频降噪/净化	audio_b64（必填）、level（light/heavy）、name
list_voices	列出已注册音色	无
cancel	取消当前合成	id（可选）

• id 为客户端自定 UUID，服务端在响应中原样带回，用于关联请求与响应。
• mode 取值：reference（可控克隆，仅参考音频）、prompt（延续式克隆，需 prompt_text 逐字转写）、hifi（极致克隆，参考音频 + 转写，相似度最高）。prompt / hifi 模式必须提供 prompt_text。
• level 取值：light（轻量谱减法）、heavy（DeepFilterNet3 深度降噪）。

服务端 → 客户端消息

op	说明	关键字段
ready	连接建立后首发	sample_rate、model、auth_required、auth_enabled
auth_ok	鉴权通过	无
auth_failed	鉴权失败/超时	message
connection_ok	test_connection 响应	id、model、sample_rate、auth_enabled、auth_required
start	流式合成开始	id、sample_rate
（二进制帧）	音频数据	float32 LE 单声道 PCM，每个 chunk 一帧
end	流式合成结束	id、samples（总采样点数）
voice_added	音色注册/预览注册成功	id、voice_id
voice_list	list_voices 响应	id、voices（数组，含 voice_id/mode/prompt_text）
voice_candidates	design_voice 响应	id、candidates（数组，含 candidate_id/wav_b64/duration）
clone_previewed	预览创建成功	id、preview_id
preview_audio	预览样音	id、wav_b64、duration
audio_preprocessed	降噪处理结果	id、wav_b64、duration、name、level
cancelled	取消确认	id
error	错误	id（可选）、message
pong	ping 响应	无

调用示例

文本合成（零样本）：

{"op":"synthesize","id":"a1b2c3d4","text":"你好，欢迎使用 VoxCPM2。","voice_id":""}

注册音色（可控克隆）：

{"op":"add_voice","id":"e5f6g7h8","voice_id":"my_voice","mode":"reference","audio_b64":"<wav base64>"}

列出音色：

{"op":"list_voices","id":"i9j0k1l2"}

完整合成时序：

client -> synthesize
server -> start
server -> <二进制音频帧> × N
server -> end

鉴权信息（已脱敏）

• WebUI 默认登录账号：admin，默认密码：123456（建议首次登录后修改）
• 修改 WebUI 账号/密码（在实例内执行）： bash <项目目录>/set_webui_auth.sh <新用户名> <新密码>
• 鉴权 Token 已固化在镜像中，首次使用请在实例内查看： cat <项目目录>/.voxcpm_token

请勿在公开描述中填写真实 Token 或实例 IP。

开机自启动

• 自启动脚本：/start.d/voxcpm-server.sh
• 服务日志：/var/log/voxcpm-server.log
• 查看日志：tail -f /var/log/voxcpm-server.log

费用提示

• 平台按秒计费、关机不收费；依赖已固化进镜像，用完关机即可，避免重复安装产生的费用。
• 若 /models 为独立数据盘 / 公共模型库，新建实例时请挂载同名存储，模型不会丢失。

注意事项

• 敏感信息（IP、Token、WebUI 密码）请勿写入公开镜像描述或封面截图。