这份详细的部署教程将指引您安装和使用 CosyVoice——一个由 FunAudioLLM 开发的多语言大型语音生成模型。它支持零样本语音克隆、流式推理和指令控制，适用于多种语音合成场景。

CosyVoice 的核心优势在于其多语言、高质量和可控性。它支持9种主流语言和18种以上中文方言/口音，并允许通过文本指令控制情感、语速和音量，非常适合需要高表现力语音输出的应用。

整个部署流程包括环境准备、模型下载和基本使用。您可以根据需求选择基础推理、vLLM加速或服务化部署。

📥 环境准备与安装

1. 克隆仓库

1
2
3
4
git clone --recursive https://github.com/FunAudioLLM/CosyVoice.git
cd CosyVoice
# 如果子模块克隆失败，重复执行以下命令直到成功
git submodule update --init --recursive

2. 创建 Conda 环境

项目推荐使用 Conda 管理 Python 环境，要求 Python 3.10。

1
2
3
conda create -n cosyvoice -y python=3.10
conda activate cosyvoice
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com

3. 安装系统依赖 (可选，用于解决音频兼容性问题)

1
2
3
4
# Ubuntu
sudo apt-get install sox libsox-dev
# CentOS
sudo yum install sox sox-devel

🤖 模型下载

您需要下载预训练模型。推荐使用 Fun-CosyVoice3-0.5B 以获得最佳性能。

使用 ModelScope 下载 (国内推荐)：

1
2
3
4
5
from modelscope import snapshot_download
# 下载 Fun-CosyVoice3-0.5B 模型 (推荐)
snapshot_download('FunAudioLLM/Fun-CosyVoice3-0.5B-2512', local_dir='pretrained_models/Fun-CosyVoice3-0.5B')
# 其他模型
# snapshot_download('iic/CosyVoice2-0.5B', local_dir='pretrained_models/CosyVoice2-0.5B')

使用 Hugging Face 下载 (海外用户)：

1
2
from huggingface_hub import snapshot_download
snapshot_download('FunAudioLLM/Fun-CosyVoice3-0.5B-2512', local_dir='pretrained_models/Fun-CosyVoice3-0.5B')

可选：安装文本正则化工具 (ttsfrd)，可提升文本处理效果。

1
2
3
4
cd pretrained_models/CosyVoice-ttsfrd/
unzip resource.zip -d .
pip install ttsfrd_dependency-0.1-py3-none-any.whl
pip install ttsfrd-0.4.2-cp310-cp310-linux_x86_64.whl

🚀 基本使用

1. 运行示例脚本

下载模型后，可以直接运行项目提供的示例脚本，体验零样本语音克隆、指令控制等功能。

1
python example.py

您可以根据需要修改 example.py 中的文本和参考音频路径。

2. 启动 Web 演示界面

CosyVoice 提供了一个 Gradio Web 界面，方便快速体验。

1
2
3
4
# 使用 SFT 模型
python3 webui.py --port 50000 --model_dir pretrained_models/CosyVoice-300M-SFT
# 使用 Instruct 模型 (支持指令控制)
python3 webui.py --port 50000 --model_dir pretrained_models/CosyVoice-300M-Instruct

然后在浏览器中打开 http://localhost:50000。

⚡ 高级部署选项

使用 vLLM 加速推理

CosyVoice2/3 支持 vLLM 引擎以实现更高的推理效率。请注意 vLLM 有特定的版本要求。

1
2
3
4
5
6
7
# 克隆基础环境并安装 vLLM
conda create -n cosyvoice_vllm --clone cosyvoice
conda activate cosyvoice_vllm
# 对于 vLLM 0.11.0+ (推荐)
pip install vllm==v0.11.0 transformers==4.57.1 numpy==1.26.4 -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com
# 运行 vLLM 示例
python vllm_example.py

服务化部署 (Docker + FastAPI/gRPC)

项目提供了 Docker 镜像，方便将 CosyVoice 部署为 API 服务。

1
2
3
4
5
6
7
8
9
cd runtime/python
# 构建 Docker 镜像
docker build -t cosyvoice:v1.0 .

# 启动 FastAPI 服务 (端口 50000)
docker run -d --runtime=nvidia -p 50000:50000 cosyvoice:v1.0 /bin/bash -c "cd /opt/CosyVoice/CosyVoice/runtime/python/fastapi && python3 server.py --port 50000 --model_dir iic/CosyVoice-300M && sleep infinity"

# 使用客户端测试
cd fastapi && python3 client.py --port 50000 --mode <sft|zero_shot|cross_lingual|instruct>

注意：--runtime=nvidia 参数需要在系统已安装 NVIDIA Container Toolkit 时使用。

使用 TensorRT-LLM 部署

对于追求极致性能的场景，可以参考 runtime/triton_trtllm 目录下的说明，通过 TensorRT-LLM 获得约4倍的推理加速。

📚 了解更多

  • 更多高级用法：训练和推理脚本位于 examples/libritts 目录下。
  • 生态项目：CosyVoice 是 FunAudioLLM 系列的一部分，同系列还包括 FunASR (语音识别)、SenseVoice (情感识别) 等工具。
  • 问题反馈：您可以通过 GitHub Issues 或扫描项目 README 中的二维码加入官方钉钉群进行交流。