Spark‑TTS 部署避坑全攻略（Ubuntu 24.04 + Conda + RTX 40 系）

适用对象：零基础也想本地跑出第一句 TTS 的同学。

运行环境：Ubuntu 24.04 × CUDA 12.x × RTX 4090（同理可迁移到 30/20 系或纯 CPU）。

---

1 硬件 & 软件环境

类别	版本	备注
OS	Ubuntu 24.04	其它发行版通用
GPU Driver	570.xx	保证 nvidia‑smi 正常
CUDA Toolkit	12.4 / 12.8	与驱动对应即可
Conda	24.3	推荐 Miniconda/Mamba
Python	3.12 (Conda)	requirements 与官方兼容

检查脚本

nvidia-smi     # GPU 与驱动
python - <<'PY'
import torch, platform, sys
print(torch.__version__, torch.version.cuda, torch.cuda.is_available())
PY

---

2 项目克隆与依赖安装

# 1️⃣ 克隆仓库
mkdir -p ~/tts && cd ~/tts
git clone https://github.com/SparkAudio/Spark-TTS.git
cd Spark-TTS

# 2️⃣ 创建并激活 env
conda create -n sparktts python=3.12 -y
conda activate sparktts

# 3️⃣ 安装 PyTorch（CUDA 12.1 为例）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 4️⃣ 安装项目依赖
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

⚠️ 坑 1：pip install 过程卡在 Gradio 依赖

• 症状：安装速度极慢或卡死。
• 解决 ：切换国内源、加 --timeout 600；必要时分两次安装（PyTorch 与其他包分开）。

---

3 下载 0.5 B 预训练模型

pip install -U huggingface_hub tqdm

# 若在中国大陆网络 ↓
export HF_ENDPOINT=https://hf-mirror.com

python - <<'PY'
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id="SparkAudio/Spark-TTS-0.5B",
    local_dir="pretrained_models/Spark-TTS-0.5B",
    resume_download=True,
    local_dir_use_symlinks=False
)
print("✅ 模型下载完成")
PY

⚠️ 坑 2：HuggingFace 下载报 SSL / Connection reset

• 症状：下载时断连或 0 KB/s。
• 解决：

1. 1. 使用镜像域名 HF_ENDPOINT=https://hf-mirror.com；
   2. 或离线拷贝别人已下载的 pretrained_models 文件夹。

---

4 命令行快速推理

export PYTHONPATH=$(pwd):$PYTHONPATH   # 每次启动前执行，或写入 ~/.bashrc

python -m cli.inference \
  --text "你好，Spark‑TTS 部署成功！" \
  --gender female --pitch moderate --speed high \
  --model_dir pretrained_models/Spark-TTS-0.5B \
  --device 0 \
  --save_dir outputs

生成的 outputs/YYYYmmddHHMMSS.wav 能播放即成功。

⚠️ 坑 3：TypeError: Invalid file: None

• 原因 ：未同时提供 --gender / --prompt_speech_path 任意一组参数。
• 修复：

• • Voice Creation ：指定 --gender --pitch --speed。
  • Voice Cloning ：提供 --prompt_speech_path snd.wav（16 kHz WAV）+ 可选 --prompt_text。

---

5 启动 Gradio Web UI

python webui.py \
  --model_dir pretrained_models/Spark-TTS-0.5B \
  --device 0 \
  --server_name 0.0.0.0 --server_port 7860

本机浏览器 http://127.0.0.1:7860；远程使用服务器 IP 访问。

⚠️ 坑 4：TypeError: argument of type 'bool' is not iterable

• 根因：Gradio ≤ 5.18 与 pydantic ≥ 2.11 不兼容。
• 两种修复方案：

1. 1. 降 pydantic

pip uninstall -y pydantic && pip install "pydantic==2.10.6"

1. 2. 升 Gradio（≥ 5.24 已修复）

pip install -U "gradio>=5.24.0"

---

6 显存占用与优化

选项	作用	显存消耗
--device -1	纯 CPU 推理	0 GiB（超慢）
默认 fp32	全精度	~3.5 GiB
torch.cuda.set_per_process_memory_fraction(0.3,0)	限制显存百分比	自控

RTX 4090 + fp32 单句推理 ≈ 2 s；fp16 改源码或 ONNX 导出可进一步减至 1 s 级。

---

7 常见报错速查表

报错片段	触发场景	解决方案
Missing tensor: mel_transformer.*	正常提示，可忽略	------
CUDA out of memory	Vram 不够	关闭占用进程 / 限显存 / CPU 推理
ValueError: When localhost is not accessible	远程服务器无本机回环	加 --server_name 0.0.0.0 或 --share

---

8 完整命令清单

# 克隆 & 环境
conda create -n sparktts python=3.12 -y && conda activate sparktts
git clone https://github.com/SparkAudio/Spark-TTS.git && cd Spark-TTS
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

# 下载模型
export HF_ENDPOINT=https://hf-mirror.com   # 可选
python - <<'PY'
from huggingface_hub import snapshot_download;snapshot_download(repo_id='SparkAudio/Spark-TTS-0.5B',local_dir='pretrained_models/Spark-TTS-0.5B',resume_download=True,local_dir_use_symlinks=False)
PY

# 降 pydantic（或升 gradio）
pip install 'pydantic==2.10.6'

# 推理
export PYTHONPATH=$(pwd):$PYTHONPATH
python -m cli.inference --text "Hello" --gender female --pitch moderate --speed high --model_dir pretrained_models/Spark-TTS-0.5B --device 0 --save_dir outputs

# Web UI
python webui.py --model_dir pretrained_models/Spark-TTS-0.5B --device 0 --server_name 0.0.0.0 --server_port 7860

---

9 结语

到此，一个 本地离线、显存友好、支持语音克隆的 Spark‑TTS 环境就全部搞定。把踩坑笔记分享到朋友圈 / 公众号，让更多小伙伴少走弯路吧！

---

作者 ：最后更新：2025‑04‑25