企业官网建设流程全解析

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 专用源。按这张表核对，装完环境就能直接对照验证：

三步跑通第一条语音

三步走完，你会在项目根目录同时拥有代码和模型文件。

第一步：克隆仓库并拉全子模块

子模块不拉全，后面 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 另装 sox：

conda create -n cosyvoice python=3.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.1+cu121即可进入下一步。

第三步：下载预训练模型

模型统一放进根目录的pretrained_models/，这是 cosyvoice/cli/cosyvoice.py 里model_dir的默认约定。用 modelscope 拉取，几行就够：

from modelscope import snapshot_download snapshot_download('iic/CosyVoice2-0.5B', local_dir='pretrained_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 protobuf==4.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.5B

• FastAPI 服务：适合多客户端接入，server.py 的--model_dir相对当前目录解析，建议传绝对路径避免引用错位：

cd runtime/python/fastapi && python server.py --port 50000 --model_dir /abs/path/CosyVoice2-0.5B

• TensorRT 加速：性能上限最高，但对 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.md，matcha 导入、git-lfs 缺件这些坑都有现成条目；没有答案再去项目 issues 提问。顺手扫一眼社区入口，找不到答案也能直接问人：

【免费下载链接】CosyVoiceMulti-lingual large voice generation model, providing inference, training and deployment full-stack ability.项目地址: https://gitcode.com/gh_mirrors/cos/CosyVoice