Chrysalid1. 项目概述
fish-speech-1.5是一款开源的语音合成模型，它能够根据5-10秒的样本语音片段和对应文本，生成与样本音色高度相似的语音输出。相比其他语音合成方案，它的优势在于对硬件要求不高，可以在普通消费级显卡上运行，且完全免费开源。我在实际部署过程中发现，虽然官方文档看似简单，但存在多个隐藏的"坑"，特别是版本兼容性和环境配置方面的问题。本文将详细记录我从零开始成功部署fish-speech-1.5的全过程，包括那些官方文档没有提及的关键细节。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备
2.1 硬件与驱动检查
在开始部署前，首先需要确保你的硬件环境满足基本要求。fish-speech-1.5主要依赖NVIDIA GPU进行加速运算，因此需要检查显卡驱动和CUDA版本：
bash复制nvidia-smi # 查看显卡驱动版本和CUDA版本
nvcc --version # 查看实际安装的CUDA Toolkit版本
注意：这两个命令显示的CUDA版本可能不同，这是正常现象。nvidia-smi显示的是驱动支持的最高CUDA版本，而nvcc显示的是实际安装的CUDA Toolkit版本。
如果你的驱动较旧，建议更新到最新版本。我在RTX 3060上测试时使用的是驱动版本535.161.07，对应CUDA 12.2，但实际使用的是CUDA 12.1的工具包，运行完全正常。这说明NVIDIA驱动具有良好的向下兼容性。
2.2 Python环境配置
Python版本选择是部署过程中最大的"坑"之一。经过多次尝试，我强烈建议使用Python 3.12.10版本。原因如下：
- Python 3.13及以上版本会导致部分依赖包无法正常安装
- Python 3.11及以下版本虽然可以运行，但性能不如3.12稳定
- 3.12.10是经过社区验证最稳定的版本
建议使用venv创建隔离的Python环境：
bash复制python3.12 -m venv fish-speech-env
source fish-speech-env/bin/activate # Linux/macOS
fish-speech-env\Scripts\activate # Windows
3. 代码与模型获取
3.1 获取fish-speech-1.5代码
必须确保获取的是1.5版本的代码，最新版的主分支可能不兼容。有两种可靠的方式：
-
直接下载release版本：
bash复制wget https://github.com/fishaudio/fish-speech/archive/refs/tags/v1.5.0.tar.gz tar -xzvf v1.5.0.tar.gz cd fish-speech-1.5.0 -
通过git克隆并切换tag：
bash复制git clone https://github.com/fishaudio/fish-speech.git cd fish-speech git checkout v1.5.0
重要提示：绝对不要使用官方提供的install_env.bat安装脚本，它会安装不兼容的依赖版本，导致后续运行失败。
3.2 下载预训练模型
模型文件较大（约2GB），建议从ModelScope下载，速度较快且不需要特殊网络环境：
bash复制modelscope download --model fishaudio/fish-speech-1.5 --local_dir ./checkpoints/fish-speech-1.5.0
下载完成后，检查目录结构应该是：
code复制checkpoints/
└── fish-speech-1.5.0/
├── config.yaml
├── model.safetensors
└── ...
4. 依赖安装与配置
4.1 PyTorch安装
PyTorch版本必须严格匹配，否则会出现各种奇怪的错误。以下是经过验证可用的安装命令：
bash复制pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu121
注意：这里的cu121表示CUDA 12.1版本。如果你的CUDA版本不同，需要相应调整。例如CUDA 11.8应使用cu118。
4.2 其他依赖安装
安装项目所需的其他依赖：
bash复制pip install -r requirements.txt
如果遇到任何依赖冲突，可以尝试以下解决方案：
-
先卸载冲突的包：
bash复制
pip uninstall [冲突的包名] -
指定版本重新安装：
bash复制
pip install [包名]==[特定版本]
5. 运行与测试
5.1 准备输入文件
创建一个input目录，放入你的音频样本和文本文件：
code复制input/
├── sample.wav # 5-10秒的语音样本
└── text.txt # 要合成的文本内容
音频文件格式建议使用16kHz采样率的WAV格式。如果不是，可以使用ffmpeg转换：
bash复制ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav
5.2 运行推理
使用以下命令启动语音合成：
bash复制python inference.py --input input/text.txt --reference input/sample.wav --output output/result.wav
参数说明：
--input: 包含要合成文本的文件路径--reference: 参考音频文件路径--output: 生成的音频文件保存路径
5.3 常见问题排查
-
CUDA内存不足：
- 降低batch size：在inference.py中找到batch_size参数，减小其值
- 使用更短的参考音频（5秒足够）
- 关闭其他占用GPU的程序
-
生成的语音质量不佳：
- 确保参考音频清晰无噪音
- 尝试不同的文本（某些特殊字符可能影响效果）
- 检查模型是否完整下载
-
运行时报错找不到模块：
- 确认Python环境已激活
- 检查是否安装了所有依赖
- 尝试
pip install -e .将项目安装到环境中
6. 高级配置与优化
6.1 性能调优
如果你的GPU性能较强，可以尝试以下优化：
-
增加batch size以提高吞吐量
-
启用半精度计算（FP16）：
python复制torch.set_float32_matmul_precision('medium') -
使用更高效的数据加载方式：
- 将音频文件预处理为numpy数组缓存
- 使用多线程数据加载
6.2 自定义音色
通过微调模型可以获得更个性化的音色：
- 准备至少10分钟的高质量语音数据
- 分割为5-10秒的片段并标注对应文本
- 使用train.py脚本进行微调：
bash复制
python train.py --config configs/finetune.yaml --data_dir your_data_dir
注意：微调需要较强的GPU和较长训练时间，建议至少16GB显存。
7. 实际应用建议
-
批量处理：
可以修改inference.py支持批量处理，提高效率：python复制# 修改为处理多个文件 texts = ["text1.txt", "text2.txt"] refs = ["ref1.wav", "ref2.wav"] for text, ref in zip(texts, refs): run_inference(text, ref) -
API服务：
使用FastAPI封装为HTTP服务：python复制from fastapi import FastAPI, File, UploadFile app = FastAPI() @app.post("/synthesize") async def synthesize(text: str, audio: UploadFile = File(...)): # 保存上传文件 # 调用推理函数 # 返回生成的音频 -
音色融合：
尝试混合多个参考音频的特征，创造新的音色：python复制# 在inference.py中修改特征提取部分 ref1_features = extract_features(ref1) ref2_features = extract_features(ref2) mixed_features = 0.7*ref1_features + 0.3*ref2_features
8. 维护与更新
-
定期检查更新：
- 关注项目GitHub的release页面
- 加入社区讨论组获取最新信息
-
备份重要数据：
- 定期备份微调后的模型
- 保存优秀的音色样本
-
环境迁移：
使用requirements.txt导出环境：bash复制pip freeze > requirements.txt # 在新机器上 pip install -r requirements.txt
经过以上步骤，你应该已经成功部署了fish-speech-1.5语音合成系统。这套方案在我的实际使用中表现稳定，生成质量令人满意。最大的经验教训就是严格遵循版本要求，任何微小的版本偏差都可能导致难以排查的问题。建议在部署前完整阅读本文，避免重复踩坑。