CosyVoice环境配置指南30分钟跑通导入错误一次修好【免费下载链接】CosyVoiceMulti-lingual large voice generation model, providing inference, training and deployment full-stack ability.项目地址: https://gitcode.com/gh_mirrors/cos/CosyVoice这篇 CosyVoice 环境配置指南目标是 30 分钟让多语言语音模型跑通第一条音频并给出一份 Python 模块导入错误对照卡。照着走每步都有可观察的结果。版本组合一张表看对先锁定版本再装依赖。CosyVoice 的依赖在 requirements.txt 里全部钉死其中首行已指向 CUDA 12.1 的 PyTorch 专用源。按这张表核对装完环境就能直接对照验证组件版本备注Python3.10官方推荐解释器torch / torchaudio2.3.1cu121从 cu121 专用源安装transformers4.51.3钉在 requirements.txt 第 38 行protobuf4.25高版本会引发导入报错gradio5.4.0WebUI 前端依赖modelscope1.20.0拉取预训练模型tensorrt-cu1210.13.3.9仅 TensorRT 加速部署需要三步跑通第一条语音三步走完你会在项目根目录同时拥有代码和模型文件。第一步克隆仓库并拉全子模块子模块不拉全后面 import 必挂。递归克隆后确认third_party/Matcha-TTS/目录存在git clone --recursive https://gitcode.com/gh_mirrors/cos/CosyVoice cd CosyVoice网络中断导致子模块失败时重跑git submodule update --init --recursive直到成功。第二步建环境装依赖用 conda 隔离环境装依赖一条命令。国内网络可以换阿里云 PyPI 镜像加速Linux 另装 soxconda create -n cosyvoice python3.10 -y conda activate cosyvoice pip install -r requirements.txt sudo apt-get install sox libsox-dev # CentOS 用 yum install sox sox-devel装完执行python -c import torch; print(torch.__version__)看到2.3.1cu121即可进入下一步。第三步下载预训练模型模型统一放进根目录的pretrained_models/这是 cosyvoice/cli/cosyvoice.py 里model_dir的默认约定。用 modelscope 拉取几行就够from modelscope import snapshot_download snapshot_download(iic/CosyVoice2-0.5B, local_dirpretrained_models/CosyVoice2-0.5B)走 git 下载则需要先装 git-lfs否则仓库里只有占位文件。高频导入报错对照卡三类报错覆盖了 CosyVoice 环境配置问题的大头。症状对上号直接执行修复命令不用从头排查。症状No module named cosyvoice原因Python 找不到项目根目录cosyvoice包不在搜索路径里。修复把仓库根目录写进 PYTHONPATH当前 shell 立即生效export PYTHONPATH$PWD:$PYTHONPATH python -c import cosyvoice; print(cosyvoice.__file__)打印出文件路径即定位成功。要长期保留把这行追加进~/.bashrc。症状google.protobuf 导入异常原因环境里的 protobuf 版本高于 4.25内部 API 对不上。修复锁定版本强制重装再跑一句 import 验证pip install protobuf4.25 --force-reinstall python -c import google.protobuf; print(google.protobuf.__version__)输出4.25即修复完成。症状No module named matcha_tts原因third_party/Matcha-TTS子模块缺失或它的目录不在搜索路径里。修复先补子模块再把路径挂进环境变量example.py 里用的就是同款sys.path.append写法git submodule update --init --recursive export PYTHONPATH$PWD/third_party/Matcha-TTS:$PYTHONPATH按场景选部署方式三种入口对应三种使用强度本地试音、对外服务、极限吞吐。WebUI本地界面最快出结果--model_dir指向你刚下载的模型目录python webui.py --port 50000 --model_dir pretrained_models/CosyVoice2-0.5BFastAPI 服务适合多客户端接入server.py 的--model_dir相对当前目录解析建议传绝对路径避免引用错位cd runtime/python/fastapi python server.py --port 50000 --model_dir /abs/path/CosyVoice2-0.5BTensorRT 加速性能上限最高但对 TensorRT 版本敏感。直接用官方 Docker 组合见 runtime/triton_trtllm/ 下的 README 与 compose 文件cd runtime/triton_trtllm docker compose -f docker-compose.cosyvoice2.unet.yml up -d关键差异一句话WebUI 只需模型路径FastAPI 注意路径基准TensorRT 必须容器化隔离环境。收尾验证与快速自检验证只需三行输出可用音色列表就说明环境通了from cosyvoice.cli.cosyvoice import CosyVoice2 cv CosyVoice2(pretrained_models/CosyVoice2-0.5B) print(cv.list_available_spks())再用一条命令核对关键版本与第 1 节的表逐行对照pip freeze | grep -Ei ^torch|^transformers|^protobuf|^modelscope卡住时先查 FAQ.mdmatcha 导入、git-lfs 缺件这些坑都有现成条目没有答案再去项目 issues 提问。顺手扫一眼社区入口找不到答案也能直接问人【免费下载链接】CosyVoiceMulti-lingual large voice generation model, providing inference, training and deployment full-stack ability.项目地址: https://gitcode.com/gh_mirrors/cos/CosyVoice创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考