ChatTTS语音合成报错排查指南：从Internal Server Error到稳定运行-育师

1. 背景：ChatTTS 部署架构与 500 报错的“黑盒”瞬间

ChatTTS 官方示例默认给出的是“单进程 + Flask”的玩具级服务，很多同学习惯用nohup python app.py &一把梭哈，结果前端一点“合成语音”就弹出 Internal Server Error。
500 并不神秘，它只是后端把异常吞掉后丢给网关的一句“我挂了”。在 ChatTTS 场景里，常见链路是：

Nginx(80) → Gunicorn(8000) → ChatTTS 服务进程 → GPU 推理库

任何一环抛异常，Nginx 都原样返 500。下面按“日志 → 接口 → 依赖 → 代码 → 生产”五段式拆给你看。

2. 错误诊断：把 500 拆成 5 步

2.1 日志三板斧

先看 Gunicorn 错误日志（默认gunicorn_error.log）
再看 ChatTTS 自己打印的 traceback（常常藏在--capture-output里）
最后翻系统日志/var/log/syslog，确认是否 OOM killer 把进程掐了

关键词速搜：
OOM,CUDA out of memory,model not found,missing config,json.decoder.JSONDecodeError

2.2 Postman 快速复现

把浏览器里触发的请求原样粘到 Postman，重点看：

Headers 里有没有Content-Type → application/json
Body 是不是裸文本，ChatTTS 接口要的是{ "text": "xxx", "voice": 0 }
返回头 512 字节，如果还是 500，把 Time 也勾上，看是不是 30 s 超时

2.3 依赖版本雷达

ChatTTS 对 torch 版本极度敏感，官方锁torch==2.0.1+cu118。
一条命令验真伪：

pip show torch | grep Version

如果看到 2.1.x 或 cpu 版，先降级再说。

3. 解决方案：一段“带重试 + 超时 + 异常落盘”的请求代码

以下脚本可直接丢到生产服务器做探活，返回 200 就把音频写入本地，否则打印异常栈，方便你二次开发。

# chattts_healthcheck.py import requests, json, time, traceback, sys URL = "http://127.0.0.1:8000/v1/tts" # 按实际端口改 TEXT = " ChatTTS 报错排查指南 " RETRY = 3 TIMEOUT = 25 # 秒，必须 < Nginx proxy_read_timeout def call_tts(text: str, voice: int = 1111): payload = {"text": text, "voice": voice, "format": "wav"} for i in range(1, RETRY + 1): try: r = requests.post(URL, json=payload, headers={"Content-Type": "application/json"}, timeout=TIMEOUT) if r.status_code == 200: fname = f"tts_{int(time.time())}.wav" with open(fname, "wb") as f: f.write(r.content) print(f"[OK] 音频已保存 → {fname}") return else: print(f"[WARN] 第{i}次请求返回 {r.status_code}，文本：{text[:30]}") print(r.text[:300]) except Exception as e: print(f"[ERROR] 第{i}次异常：{{type(e).__name__}】") traceback.print_exc() time.sleep(1) sys.exit(1) if __name__ == "__main__": call_tts(TEXT)

跑通后，把URL换成公网域名就能当监控脚本用。

4. 生产环境：并发、缓存、重试，一个都不能少

4.1 并发限制

ChatTTS 默认 workers=1，推理全在 GPU0，并发一上来就排队。
Gunicorn 建议：

gunicorn -w 4 -k gthread --threads 2 app:app

同时把CUDA_VISIBLE_DEVICES=0,1打开，模型内部做 round-robin，可把吞吐翻 2 倍。

4.2 音频缓存

合成文本重复率高的场景（客服电话、通知），用 Redis 缓存 MD5(text+voice) → wav 二进制，可砍掉 60% GPU 占用。
缓存 TTL 设 24h，凌晨低峰跑定时脚本清掉冷数据。

4.3 错误重试 & 熔断

502/504 走指数退避：1s → 2s → 4s
连续 5 次 500 直接熔断 30s，返回 503 给前端，别让 GPU 一直爆
把失败文本写入 Kafka，供离线批处理补偿

4.4 性能压测

用 Locust 写 30 行脚本即可：

from locust import HttpUser, task class TTSUser(HttpUser): @task def tts(self): self.client.post("/v1/tts", json={"text": "压测文本", "voice": 0}, timeout=25)

起 200 并发，阶梯加到 500，观察 GPU-Util 与显存。显存飙到 90% 就差不多是上限。

5. 避坑指南：Top5 配置错误一次说清

端口占用冲突
症状：gunicorn 起不来，日志报Address already in use
验证：lsof -i:8000杀掉僵尸进程即可
Nginx 文件体超限
症状：长文本 500，日志出现client intended to send too large body
修复：client_max_body_size 10M;
缺失模型权重
症状：第一次点合成，后台报FileNotFoundError: *.pth
验证：ls -h models/看权重是否被 .gitignore 漏传
混用系统 Python
症状：torch 装上了 cpu 版，GPU 显存纹丝不动
验证：python -c "import torch;print(torch.cuda.is_available())"必须 True
忘记关 debug
症状：并发时 Flask 自动重载，导致 workers 互相抢模型句柄
修复：启动参数FLASK_ENV=production gunicorn ...