# VoxCPM2 TTS 服务配置说明

硬件参考：x86 16核/32GB + NVIDIA GeForce RTX 4090 + 256GB磁盘

# 0. 快速部署（一键启动）

适合绝大多数场景，直接复制执行即可

# 1.拉取镜像
docker pull cdhx78.seeyon.com:5356/library/voxcpm2-tts:1.0.0
# 2.镜像重命名
docker tag cdhx78.seeyon.com:5356/library/voxcpm2-tts:1.0.0 voxcpm2-tts:nanovllm

# 离线导入镜像（如无内网仓库，使用tar包，二选一）
# docker load -i voxcpm2-tts-1.0.0.tar

# 3.启动服务（使用宿主机GPU 0，端口9913）
docker run -d \
  --gpus '"device=0"' \
  -p 9913:9913 \
  -e CUDA_VISIBLE_DEVICES=0 \
  -e NANOVLLM_DEVICES=0 \
  --name voxcpm2-tts \
  voxcpm2-tts:nanovllm

访问地址：http://服务器IP:9913

# 1. 宿主机环境要求（Docker部署）

容器内部已自带CUDA、cuDNN、Python、Pytorch，宿主机无需安装。

检查项	要求	校验命令
NVIDIA驱动	≥ 550（支持CUDA 12.4）	`nvidia-smi --query-gpu=driver_version --format=csv,noheader`
NVIDIA Container Toolkit	已安装	`dpkg -l \| grep nvidia-container-toolkit`

基础镜像：nvidia/cuda:12.4.0-runtime-ubuntu22.04

# 2. 配置方式说明

所有参数均通过环境变量，以 docker run -e 变量名=值 的方式传入容器。

# 重要语法规则

-e 参数等号两侧不能带空格
- ✅ 正确：-e WS_TTS_TEXT_MAX_BYTES=4096
- ❌ 错误：-e WS_TTS_TEXT_MAX_BYTES = 4096
只需要传入你希望修改的配置项，其余自动使用默认值；
默认值来源标记说明：
- (镜像)：Dockerfile内预置，不传也生效
- (代码)：容器代码config.py内置默认，镜像未预置

# 3. 环境变量完整参考表

# 3.1 GPU / 设备

变量名	默认值	来源	说明
CUDA_VISIBLE_DEVICES	0	镜像	容器内可见GPU编号，需要和`--gpus`参数对应；宿主机显卡映射进容器后重新编号为0,1...
NANOVLLM_DEVICES	0	镜像	nanovllm推理使用设备序号，一般和CUDA_VISIBLE_DEVICES保持一致

# 3.2 日志配置

变量名	默认值	来源	说明
TTS_LOG_DIR	/app/logs	镜像	日志存放目录
TTS_LOG_RETENTION_DAYS	7	镜像	日志保留天数，到期自动清理旧日志文件
TTS_LOG_TIMEZONE	Asia/Shanghai	镜像	日志打印时区
TTS_LOG_BODY_MAX_CHARS	50000	代码	单条请求日志内请求体最大打印字符数

# 3.3 HTTP文本分段

变量名	默认值	来源	说明
TTS_AUTO_SPLIT_TEXT	1	镜像	是否开启长文本自动分段；1=开启，0=关闭
TTS_TEXT_SEGMENT_MAX_CHARS	128	镜像	HTTP接口长文本每一段最大字符数

# 3.4 WebSocket 文本分段与流控

变量名	默认值	来源	说明
WS_TTS_SEGMENT_MAX_CHARS	60	代码	WebSocket单段文本最大字符数，影响合成延迟、粒度
WS_TTS_TEXT_MAX_BYTES	2048	代码	WebSocket单帧text.data字节上限，超出返回错误码10007
WS_TTS_TOTAL_TEXT_MAX_BYTES	16384	代码	单WebSocket会话累计文本字节上限，超出返回错误码10007
WS_TTS_BUFFER_MAX_BYTES	4096	代码	未切分文本缓冲字节上限（极少触发）
WS_TTS_QUEUE_MAX_SEGMENTS	48	代码	待合成音频队列段数上限，超出返回错误码10008
WS_TTS_FIRST_TEXT_TIMEOUT_SECONDS	15	代码	连接建立后，等待第一条文本帧超时秒数
WS_TTS_NEXT_TEXT_TIMEOUT_SECONDS	30	代码	两条文本帧之间最大等待超时秒数

# 3.5 VoxCPM 推理参数（谨慎调整）

变量名	默认值	来源	说明
VOXCPM_CFG_VALUE	2.0	代码	CFG引导强度
VOXCPM_INFERENCE_TIMESTEPS	10	代码	推理步数，步数越大音质越高、速度越慢
VOXCPM_OUTPUT_SAMPLE_RATE	16000	代码	输出音频采样率；0或大于等于原生采样率则跳过重采样
VOXCPM_MAX_GENERATE_LENGTH	2000	代码	单段音频最大生成token长度
VOXCPM_TEMPERATURE	1.0	代码	采样温度，控制语音随机性

# 3.6 nanovllm 引擎参数

变量名	默认值	来源	说明
NANOVLLM_MAX_NUM_BATCHED_TOKENS	8192	代码	单批最大token数量
NANOVLLM_MAX_NUM_SEQS	48	代码	最大并发序列数，控制并发上限
NANOVLLM_MAX_MODEL_LEN	4096	代码	模型最大上下文长度
NANOVLLM_GPU_MEMORY_UTILIZATION	0.95	代码	GPU显存占用上限比例
NANOVLLM_ENFORCE_EAGER	0	代码	是否禁用CUDA Graph；1=禁用，0=启用

# 4. Docker Run 启动示例

# 示例1：基础启动（宿主机 GPU 4、5）

docker run -d \
  --gpus '"device=4,5"' \
  -p 9913:9913 \
  -e CUDA_VISIBLE_DEVICES=0,1 \
  -e NANOVLLM_DEVICES=0,1 \
  --name voxcpm2-tts \
  voxcpm2-tts:nanovllm

# 示例2：修改WebSocket单帧文本上限

docker run -d \
  --gpus '"device=4,5"' \
  -p 9913:9913 \
  -e CUDA_VISIBLE_DEVICES=0,1 \
  -e NANOVLLM_DEVICES=0,1 \
  -e WS_TTS_TEXT_MAX_BYTES=4096 \
  --name voxcpm2-tts \
  voxcpm2-tts:nanovllm

# 示例3：同时调整多项WebSocket流控参数

docker run -d \
  --gpus '"device=4,5"' \
  -p 9913:9913 \
  -e CUDA_VISIBLE_DEVICES=0,1 \
  -e NANOVLLM_DEVICES=0,1 \
  -e WS_TTS_TEXT_MAX_BYTES=4096 \
  -e WS_TTS_TOTAL_TEXT_MAX_BYTES=65536 \
  -e WS_TTS_QUEUE_MAX_SEGMENTS=64 \
  --name voxcpm2-tts \
  voxcpm2-tts:nanovllm

# 示例4：修改宿主机映射端口（宿主机19913 → 容器9913）

docker run -d \
  --gpus '"device=5"' \
  -p 19913:9913 \
  -e CUDA_VISIBLE_DEVICES=0 \
  -e NANOVLLM_DEVICES=0 \
  --name voxcpm2-tts \
  voxcpm2-tts:nanovllm

访问地址：http://服务器IP:19913

# 5. 错误写法与避坑提醒

# ❌ 错误示例

# 错误1：等号两边带空格
WS_TTS_TEXT_MAX_BYTES = 4096 docker run -d --gpus '"device=4,5"' ...

问题解析：

环境变量 = 两侧带空格 → shell语法报错；
在docker run命令前面设置变量，只会给宿主机docker进程设置变量，不会自动透传到容器内部，容器读取不到配置。

# ✅ 正确做法

将配置项作为 -e KEY=VALUE 参数追加到 docker run 命令参数列表中，参考上面启动示例。

编撰人：jiangtw

← OCR Docker部署手册API版 ASR docker部署文档 →

# VoxCPM2 TTS 服务 配置说明