CosyVoice 报错排查指南：如何解决'没有可用的预训练音色'问题
1. 问题背景：第一次跑通语音合成，就被“没有可用的预训练音色”拦住
很多新手跟着官方 README 把 CosyVoice 装好，兴冲冲地跑一句：
from cosyvoice import CosyVoice model = CosyVoice("pretrained")结果终端啪地弹出一行红字：
RuntimeError: No available pretrained voice found!程序直接退出，连“Hello World”都没来得及说出口。
这个报错出现的典型场景：
- 刚克隆完仓库，模型权重还没下载或放错位置
- 下载了权重，但路径里多了一级文件夹，扫描不到
*.pt - 在 Windows 上解压后忘记关“只读”，导致 Python 打不开文件
- 用 Docker 跑，把模型目录挂载成了空卷
一句话：CosyVoice 在启动时会去“固定位置”扫描音色模型，找不到就抛异常，后续所有接口都无法调用。
2. 原因分析：CosyVoice 到底在“找”什么？
CosyVoice 的模型加载器（ModelHub类）启动流程大致如下：
- 读取环境变量
COSYVOICE_MODEL_ROOT，若为空则回退到~/.cache/cosyvoice - 在上述目录里递归查找满足
**/<voice_name>/model.pt的文件结构 - 把找到的
model.pt包装成Voice对象，注册到内存池 - 如果池子为空，就抛
No available pretrained voice found!
所以报错只有两种可能：
A. 磁盘上确实没有模型文件；B. 有，但路径/权限/格式不对，扫描跳过了。
3. 解决方案：一步一步把模型“请”回家
3.1 环境变量设置
Linux / macOS：
# 1. 找个宽裕的磁盘，新建目录 mkdir -p /data/cosyvoice # 2. 写进当前 shell export COSYVOICE_MODEL_ROOT=/data/cosyvoice # 3. 顺手写进 ~/.bashrc，下次开机还在 echo 'export COSYVOICE_MODEL_ROOT=/data/cosyvoice' >> ~/.bashrcWindows PowerShell：
# 永久生效 setx COSYVOICE_MODEL_ROOT "D:\cosyvoice"3.2 下载并解压官方权重
官方仓库 Releases 里提供了voices-v1.zip，假设我们下载后得到：
voices-v1/ ├── anna/ │ └── model.pt ├── bob/ │ └── model.pt └── ...把anna、bob这些文件夹直接移动到$COSYVOICE_MODEL_ROOT下，最终目录树应类似：
/data/cosyvoice ├── anna/ ├── bob/ └── ...注意：不要多套一层voices-v1文件夹，否则扫描器会错过。
3.3 权限验证（Linux 常见）
# 确保当前用户能读 chmod -R u+rw $COSYVOICE_MODEL_ROOT # 如果计划用 systemd 或 cron 跑，最好再开 o+rw4. 代码示例：最简正确打开方式
import os from pathlib import Path from cosyvoice import CosyVoice # 保险起见：在代码里再次确认路径 model_root = Path(os.getenv("COSYVOICE_MODEL_ROOT", Path.home() / ".cache" / "cosyvoice")) print("扫描目录:", model_root) # 初始化，内部会自动扫描 try: engine = CosyVoice("pretrained") # 或 CosyVoice("anna") 指定音色 except RuntimeError as e: print("仍报错 →", e) print("请检查目录结构或权限") raise # 合成一句试试 wav = engine.tts("你好，世界！", voice="anna") with open("demo.wav", "wb") as f: f.write(wav) print("demo.wav 已生成，快去听效果！")5. 避坑指南：90% 的“找不到”都是这 3 个错
| 错误 | 现象 | 修复 |
|---|---|---|
| 1. 多套一级文件夹 | 目录下只有voices-v1/anna/model.pt | 把anna移动到$COSYVOICE_MODEL_ROOT根 |
| 2. 文件被锁（Win 只读） | Python 报PermissionError | 右键→属性→取消“只读”→应用 |
3. 忘记装torchaudio | 报错libtorch_*.so: cannot open | pip install torchaudio -f https://download.pytorch.org/whl |
6. 进阶建议：如何把自己的声音做成“预训练音色”
- 准备 20~30 分钟干净干声，采样率 22050 Hz，单通道
- 用官方
scripts/train_voice.py走微调：
python scripts/train_voice.py \ --base_model $COSYVOICE_MODEL_ROOT/anna \ --data_dir /data/my_voice/wavs \ --output_dir $COSYVOICE_MODEL_ROOT/me- 训练完会生成
me/model.pt，重启程序就能CosyVoice("me") - 把
me文件夹打包分享给同事，对方放到同目录即可复现你的音色
7. 验证清单：跑完代码，逐条打钩
- [ ] 环境变量
COSYVOICE_MODEL_ROOT已设置并指向正确目录 - [ ] 目录下能看到
<voice>/model.pt两级结构，无多余文件夹 - [ ] 当前用户对
*.pt有读权限（Linuxls -l查看） - [ ] Python 端
print(engine.list_voices())能打印出音色列表 - [ ] 运行一次
tts()成功生成 wav，播放器可正常播放
全部打钩后，“没有可用的预训练音色”就不会再出现啦。
个人小结
第一次踩这个坑时，我以为是代码 bug，结果只是解压时多了一层文件夹。把模型当“插件”理解后，后面再换音色、做微调都顺了很多。希望这份流水账能帮你一次性把语音合成跑通，少加班，早下班。
