Chatterbox-TTS-Server

环境要求

• Python 3.10（3.11+ 缺 torchvision/ONNX 预编译 wheel，可能安装失败）
• 首次安装需联网，磁盘需预留数 GB 空间（PyTorch 与 GPU 库）
• NVIDIA 显卡需装最新驱动；Blackwell（RTX 50 系）需 CUDA 12.8 分支
• AMD 显卡需在 Linux 上安装最新 ROCm 驱动；无独显可选 CPU 方案

安装与启动步骤

1. 1克隆仓库

   把源码下载到本地并进入项目目录，后续所有命令都在此目录执行。

   git clone https://github.com/devnen/Chatterbox-TTS-Server.git
   cd Chatterbox-TTS-Server

   复制

2. 2一键启动 Linux

   脚本自动建虚拟环境、检测硬件、装依赖并启动服务，适合大多数用户。

   chmod +x start.sh
   ./start.sh

   复制

3. 3一键启动 Windows

   双击 start.bat，或在命令提示符中运行；便携模式会自动用内置 Python 3.10。

   start.bat

   复制

4. 4手动建虚拟环境

   Linux/macOS 下创建并激活 venv，提示符出现 (venv) 才算成功。

   python3 -m venv venv
   source venv/bin/activate

   复制

5. 5Windows 建虚拟环境

   在 PowerShell 中创建并激活 venv，避免与其它项目依赖冲突。

   python -m venv venv
   .\venv\Scripts\activate

   复制

6. 6装 NVIDIA 依赖

   CUDA 12.8 分支含 sm_120 支持；第二条必须带 --no-deps，防止 torch 被降级。

   pip install -r requirements-nvidia-cu128.txt
   pip install --no-deps git+https://github.com/devnen/chatterbox-v2.git@master

   复制

7. 7装 AMD 依赖

   ROCm 需先装 PyTorch 栈再装其余依赖，最后同样用 --no-deps 装 chatterbox。

   pip install -r requirements-rocm-init.txt
   pip install -r requirements-rocm.txt
   pip install --no-deps git+https://github.com/devnen/chatterbox-v2.git@master

   复制

8. 8验证安装

   检查 PyTorch 版本与 GPU 是否可见；NVIDIA 用户应能在架构列表中看到 sm_120。

   python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}'); print(f'GPU: {torch.cuda.get_device_name(0)}'); print(f'Architectures: {torch.cuda.get_arch_list()}')

   复制

关键配置

如何确认成功

torch 检查命令能打印出 GPU 名称与 sm_120；启动后浏览器打开 Web UI 可正常加载页面。

常见问题

注意事项

• 新手优先用一键启动脚本，它会自动完成虚拟环境、硬件检测与依赖安装。
• 手动安装时务必先激活虚拟环境，命令提示符应显示 (venv) 再执行 pip 安装。
• 重装或排错可运行 python start.py --reinstall，加 --verbose 查看详细日志。
• CPU-only 安装对应的 requirements 文件名在本节选中未给出，请查阅仓库安装章节 Option 1。