ChatTTS 在 Mac 本地部署的完整指南：从环境配置到性能优化

ChatTTS 在 Mac 本地部署的完整指南：从环境配置到性能优化

背景与痛点

做语音合成（TTS）项目时，云端 API 虽然方便，但延迟、并发限制和费用常常让人抓狂。把模型搬到本地，Mac 用户最先遇到的往往不是“跑不起来”，而是“跑起来却跑不顺”：

1. 依赖地狱：PyTorch 与 macOS 自带 Accelerate 版本不匹配，装完 CUDA 版才发现 M 系列芯片根本用不上。
2. 性能瓶颈：默认 FP32 精度在 M1 Max 上生成 10 秒音频要 18 s，CPU 温度直接飙到 90 ℃。
3. 部署复杂：ChatTTS 官方仓库只给了一条“python generate.py”，没提模型放哪、权重怎么下、protobuf 版本冲突怎么办。

本文把过去两周踩过的坑一次性打包，给出一条“能跑、能调、能上线”的本地路线，供同样用 Mac 的开发者直接抄作业。

技术选型

先给出结论：M1/M2 系列芯片优先走arm64原生 Python + PyTorch-Nightly + Metal Performance Shaders（MPS）路线；Intel Mac 继续用x86_64+ CPU 或 AMD ROCm（若外接 eGPU）。下面把三种方案拉出来对比：

对日常开发来说，MPS 路线性价比最高，下文所有步骤默认基于 Apple Silicon 芯片，系统版本 ≥ 12.3（Metal 3 最低要求）。

核心实现

1. 环境准备

   1. 用 Homebrew 装 pyenv，保证 Python 3.10 的 arm64 版本：
      brew install pyenv && pyenv install 3.10.12
   2. 新建项目目录并写入.python-version：
      echo 3.10.12 > .python-version
   3. 创建 venv，避免污染系统包：
      python -m venv vtf && source vtf/bin/activate

2. 依赖安装

   1. 先装 nightly 版 PyTorch（MPS 后端）：
      pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cpu
   2. 再装 ChatTTS 官方依赖，但把 transformers 版本锁在 ≤ 4.30，否则GPT2LMHeadModel接口变动：
      pip install -r requirements.txt transformers==4.30.2
   3. 额外补两个坑包：
      pip install protobuf==3.20.3 numba==0.57.1
      说明：protobuf 4.x 与 onnxruntime 冲突；numba 0.56 在 arm64 会提示_llvm找不到。

3. 权重下载与缓存
   ChatTTS 默认从 Hugging Face 拉2Noise/ChatTTS主分支，首次需要 3.2 GB。国内网络建议用镜像：
   export HF_ENDPOINT=https://hf-mirror.com
   随后写一段最小脚本触发缓存，避免在正式服务里动态下载导致超时：

   from ChatTTS import ChatTTS chat = ChatTTS.Chat() chat.load(compile=False) # 先不编译，仅下载

   下载完成后，权重会落到~/.cache/huggingface/hub/models--2Noise--ChatTTS/snapshots/<commit>/，后续离线可用。

4. 模型加载与编译
   官方示例默认compile=True会调用torch.compile，在 MPS 上目前（2.3 nightly）仍有 graph break，导致第一次推理 90 s。建议关闭编译，改用torch.inference_mode()足够：

   chat.load(compile=False) # 关闭 torch.compile chat.model.eval()

代码示例

下面给出可直接跑的infer.py，包含批量文本、语速调节、输出保存：

#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ Mac MPS 版 ChatTTS 批量推理示例 运行： python infer.py "你好，这是第一条测试语音。" "第二条，语速略快。" --speed 5 """ import argparse import torch import ChatTTS from pathlib import Path import soundfile as sf def main(texts, speed=3, output_dir="wavs"): output_dir = Path(output_dir) output_dir.mkdir(exist_ok=True) # 1. 初始化并强制走 MPS device = torch.device("mps") if torch.backends.mps.is_available() else torch.device("cpu") chat = ChatTTS.Chat() chat.load(compile=False, device=device) # 2. 构造参数 params = { "prompt": f"[speed_{speed}]", "temperature": 0.3, "top_P": 0.5, "top_K": 20, } # 3. 推理 with torch.inference_mode(): wavs = chat.infer(texts, params_refine_text=params, params_infer_code=params) # 4. 保存 for idx, wav in enumerate(wavs): sf.write(output_dir / f"{idx}.wav", wav[0], 24000) print(f"saved {output_dir}/{idx}.wav") if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("texts", nargs="+", help="待合成文本列表") parser.add_argument("--speed", type=int, default=3, help="语速 0-9，越大越快") parser.add_argument("--output_dir", default="wavs") args = parser.parse_args() main(args.texts, args.speed, args.output_dir)

关键注释已写在代码里，注意temperature越小越平稳，适合朗读场景；聊天场景可拉到 0.5–0.7。

性能优化

1. 精度与 batch
   MPS 后端对 FP16 支持完整，直接在chat.infer里加dtype=torch.float16即可再省 30 % 内存。
   实测 batch=3 时 latency 最低；再大反而因 Unified Memory 换页掉速。

2. 提前建图
   第一次推理会触发 MPS 的 graph compile，耗时 20–30 s。可在服务启动时喂一条空白文本“预热”，用户端无感：

   _ = chat.infer([""])

3. 线程与队列
   官方代码的infer是同步阻塞。自己包一层asyncio意义不大，因为 MPS 内核本身排队。更实用的是用multiprocessing.Queue把推理进程独立，主进程只负责网络 IO，避免 Python GIL 拖慢并发。

4. 流式输出
   ChatTTS 目前只支持整句生成，但 24 kHz 采样率下 10 s 音频 ≈ 240 k 点，一次性返回 1.8 MB。可以按 0.5 s 滑动窗口切片，边生成边写 WAV，主观延迟降低 40 %。

避坑指南

1. 安装时提示clang: error: unknown argument '-fopenmp'
   说明 LLVM 与 libomp 版本不一致。brew install libomp后把export LDFLAGS="-L$(brew --prefix)/lib"写进~/.zshrc，重新pip install即可。

2. 运行报RuntimeError: MPS backend does not support cumsum op
   nightly 版已修复，出现该错误说明 PyTorch 版本低于 2.2。升级到最新 nightly 可解。

3. 生成音频出现电流杂音
   采样峰值超过 0 dB。ChatTTS 输出是 float32，直接写文件会保留溢出值。加一行硬裁剪：
   wav = np.clip(wav, -1.0, 1.0)
   再落盘即可。

4. 权重缓存路径带空格导致加载失败
   macOS 用户名带空格时，/Users/First Last/会被 URL 编码成%20，transformers 4.31 之后已修，若卡住可手动把缓存目录软链到无空格路径：
   ln -s ~/.cache/huggingface /opt/hf

结语

把 ChatTTS 搬到 Mac 本地，全程看下来就是“装环境十分钟，调参数两小时”。一旦跑通 MPS 路线，5 秒出 10 秒音频的体验足够让云端付费方案吃灰。建议先按本文流程跑通默认模型，再尝试微调音色、接入实时字幕或做成 menubar 小工具。如果你在部署中遇到更奇怪的报错，欢迎把日志贴出来一起折腾——本地 TTS 的玩法才刚开始。