15分钟上手CosyVoice：从安装到语音生成的全流程指南

你还在为找不到好用的多语言语音合成工具而烦恼吗？想快速将文本转换为自然流畅的语音，支持中文、英文、日语等多种语言，甚至还能模仿特定的声音？本文将带你一步步掌握CosyVoice的使用方法，从环境搭建到实际生成语音，让你在15分钟内轻松上手这款强大的开源语音生成模型。读完本文，你将能够：

• 成功安装CosyVoice及其依赖环境
• 下载并配置预训练模型
• 使用Python代码生成个性化语音
• 运行Web界面进行可视化操作
• 了解高级部署和加速方法

项目简介

CosyVoice是一个多语言语音生成模型（Multi-lingual large voice generation model），提供了从推理、训练到部署的全栈能力。目前最新版本为CosyVoice 3.0，相比之前的版本，在语音质量、生成速度和多语言支持方面都有了显著提升。

CosyVoice支持多种语音生成模式，包括零样本语音克隆（Zero-shot Voice Cloning）、跨语言合成、情感控制等。其主要特点包括：

• 多语言支持：中文、英文、日语、韩语以及多种中文方言（粤语、四川话、上海话等）
• 低延迟 streaming 推理：首包合成延迟低至150ms
• 高精度语音合成：相比1.0版本，发音错误率降低30%至50%
• 强大的稳定性：确保零样本和跨语言语音合成的音色一致性

官方文档：README.md

环境准备与安装

克隆仓库

首先，我们需要克隆CosyVoice的代码仓库。打开终端，执行以下命令：

git clone --recursive https://gitcode.com/gh_mirrors/cos/CosyVoice.git
cd CosyVoice
git submodule update --init --recursive

创建虚拟环境

推荐使用conda创建独立的虚拟环境，以避免依赖冲突。如果你还没有安装conda，请先参考Miniconda安装指南。

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

如果遇到sox兼容性问题，可以执行以下命令安装依赖：

# Ubuntu
sudo apt-get install sox libsox-dev
# CentOS
sudo yum install sox sox-devel

模型下载与配置

下载预训练模型

CosyVoice提供了多个预训练模型，包括CosyVoice2-0.5B、CosyVoice-300M等。我们强烈推荐使用CosyVoice2-0.5B以获得更好的性能。可以通过以下两种方式下载模型：

方法一：使用modelscope SDK下载

from modelscope import snapshot_download
snapshot_download('iic/CosyVoice2-0.5B', local_dir='pretrained_models/CosyVoice2-0.5B')
snapshot_download('iic/CosyVoice-300M', local_dir='pretrained_models/CosyVoice-300M')
snapshot_download('iic/CosyVoice-300M-SFT', local_dir='pretrained_models/CosyVoice-300M-SFT')
snapshot_download('iic/CosyVoice-300M-Instruct', local_dir='pretrained_models/CosyVoice-300M-Instruct')
snapshot_download('iic/CosyVoice-ttsfrd', local_dir='pretrained_models/CosyVoice-ttsfrd')

方法二：使用git clone下载（需安装git lfs）

mkdir -p pretrained_models
git clone https://www.modelscope.cn/iic/CosyVoice2-0.5B.git pretrained_models/CosyVoice2-0.5B
git clone https://www.modelscope.cn/iic/CosyVoice-300M.git pretrained_models/CosyVoice-300M
git clone https://www.modelscope.cn/iic/CosyVoice-300M-SFT.git pretrained_models/CosyVoice-300M-SFT
git clone https://www.modelscope.cn/iic/CosyVoice-300M-Instruct.git pretrained_models/CosyVoice-300M-Instruct
git clone https://www.modelscope.cn/iic/CosyVoice-ttsfrd.git pretrained_models/CosyVoice-ttsfrd

安装ttsfrd（可选）

ttsfrd是一个文本规范化工具，可以提高文本到语音转换的准确性。如果需要安装，可以执行以下命令：

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

如果不安装ttsfrd，系统会默认使用WeTextProcessing进行文本处理。

基本使用方法

CosyVoice2基本用法

以下是使用CosyVoice2-0.5B模型进行语音生成的基本示例代码：

import sys
sys.path.append('third_party/Matcha-TTS')
from cosyvoice.cli.cosyvoice import CosyVoice2
from cosyvoice.utils.file_utils import load_wav
import torchaudio

# 加载模型
cosyvoice = CosyVoice2('pretrained_models/CosyVoice2-0.5B', load_jit=False, load_trt=False, load_vllm=False, fp16=False)

# 零样本语音克隆
prompt_speech_16k = load_wav('./asset/zero_shot_prompt.wav', 16000)
for i, j in enumerate(cosyvoice.inference_zero_shot('收到好友从远方寄来的生日礼物，那份意外的惊喜与深深的祝福让我心中充满了甜蜜的快乐，笑容如花儿般绽放。', '希望你以后能够做的比我还好呦。', prompt_speech_16k, stream=False)):
    torchaudio.save('zero_shot_{}.wav'.format(i), j['tts_speech'], cosyvoice.sample_rate)

上述代码中，我们首先导入了必要的模块，然后加载了CosyVoice2模型。通过inference_zero_shot方法，我们可以使用一个参考音频（prompt_speech_16k）来克隆其音色，并生成指定文本的语音。生成的语音将保存为WAV文件。

细粒度控制

CosyVoice支持细粒度的语音控制，例如在文本中插入笑声、调整语速等。以下是一个示例：

# 细粒度控制示例
for i, j in enumerate(cosyvoice.inference_cross_lingual('在他讲述那个荒诞故事的过程中，他突然[laughter]停下来，因为他自己也被逗笑了[laughter]。', prompt_speech_16k, stream=False)):
    torchaudio.save('fine_grained_control_{}.wav'.format(i), j['tts_speech'], cosyvoice.sample_rate)

更多支持的控制标签可以查看cosyvoice/tokenizer/tokenizer.py文件中的相关定义。

指令式语音生成

通过指令式（Instruct）接口，我们可以更精确地控制语音的风格、情感等。例如，我们可以指定使用四川话来生成语音：

# 指令式语音生成
for i, j in enumerate(cosyvoice.inference_instruct2('收到好友从远方寄来的生日礼物，那份意外的惊喜与深深的祝福让我心中充满了甜蜜的快乐，笑容如花儿般绽放。', '用四川话说这句话', prompt_speech_16k, stream=False)):
    torchaudio.save('instruct_{}.wav'.format(i), j['tts_speech'], cosyvoice.sample_rate)

Web界面使用

为了更直观地体验CosyVoice的功能，我们可以运行Web界面。执行以下命令启动Web服务：

python3 webui.py --port 50000 --model_dir pretrained_models/CosyVoice-300M

然后在浏览器中访问http://localhost:50000，即可打开Web界面。在Web界面中，你可以：

• 输入文本并生成语音
• 上传参考音频进行语音克隆
• 调整语音的语速、音调等参数
• 试听并下载生成的语音

Web界面代码：webui.py

高级用法

VLLM加速

对于需要更高推理速度的场景，可以使用VLLM来加速CosyVoice的推理。首先需要安装VLLM：

conda create -n cosyvoice_vllm --clone cosyvoice
conda activate cosyvoice_vllm
pip install vllm==v0.9.0 transformers==4.51.3 -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com

然后可以使用VLLM示例代码进行推理：

python vllm_example.py

VLLM示例代码：vllm_example.py

部署为服务

CosyVoice可以部署为API服务，供其他应用程序调用。以下是使用FastAPI部署的示例：

cd runtime/python/fastapi
python3 server.py --port 50000 --model_dir pretrained_models/CosyVoice-300M

然后可以使用客户端代码调用API：

python3 client.py --port 50000 --mode zero_shot

FastAPI服务代码：runtime/python/fastapi/server.py 客户端代码：runtime/python/fastapi/client.py

Docker部署

还可以使用Docker容器化部署CosyVoice，方便在不同环境中移植：

cd runtime/python
docker build -t cosyvoice:v1.0 .
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"

Dockerfile：runtime/python/Dockerfile

TensorRT-LLM加速部署

对于需要极致性能的场景，可以使用NVIDIA TensorRT-LLM进行加速，相比原生实现可以获得4倍左右的性能提升：

cd runtime/triton_trtllm
docker compose up -d

更多细节可以参考Triton TRTLLM部署文档

总结与展望

本文介绍了CosyVoice的基本使用方法，从环境搭建到实际语音生成，再到高级部署和加速方案。通过这些步骤，你已经可以开始使用CosyVoice来生成高质量的多语言语音了。

CosyVoice作为一个开源项目，还在不断发展中。未来，我们可以期待更多功能的加入，例如更精细的情感控制、更多方言的支持、更低的推理延迟等。如果你在使用过程中遇到问题，或者有任何建议，可以通过项目的GitHub Issues进行反馈和交流。

希望本文能够帮助你快速上手CosyVoice，享受语音生成带来的便利和乐趣！如果你觉得本文对你有帮助，欢迎点赞、收藏，并关注项目的最新动态。

相关资源

• 官方文档：README.md
• 代码仓库：https://gitcode.com/gh_mirrors/cos/CosyVoice
• 预训练模型：通过modelscope下载（详见本文安装章节）
• 示例代码：examples/
• 工具脚本：tools/