加载中...

AIGC标识 CosyVoice3 本机部署入门指南

CosyVoice3 本机部署入门指南（macOS / Apple Silicon 纯 CPU）

面向第一次接触本项目的人，从零到能在浏览器里合成语音。全程无需 GPU。
验证环境：macOS（Apple M4 Pro，arm64，24GB 内存）· Python 3.10 · 纯 CPU 推理
目标模型：Fun-CosyVoice3-0.5B-2512 · Web 界面：http://127.0.0.1:50000

0. 这是什么 / 你将得到什么

CosyVoice 是通义实验室（FunAudioLLM）开源的语音合成（TTS）框架，CosyVoice3 是其第三代模型，主打零样本音色克隆：给一段几秒的参考音频，就能用同样的音色朗读任意文本。

本指南结束后，你会有：

  • 一个隔离的 Python 虚拟环境，依赖装齐；
  • 下载好的 CosyVoice3 模型；
  • 一个跑在 50000 端口的 Web 界面（webui），浏览器打开就能合成；
  • 4 个预置音色（开箱即用，无需每次上传音频）。

关于纯 CPU：本机没有 NVIDIA 显卡，代码会自动检测并回退到 CPU，无需改任何东西。代价是慢——合成 1 秒音频大约需要 1.8 秒（RTF≈1.8），这是正常现象。

1. 前置要求

项目 要求 说明
操作系统 macOS（Apple Silicon 最佳） Intel Mac 亦可，速度略慢
Python 3.10.x 建议用 pyenv 管理，避免污染系统 Python
磁盘 ≥ 15 GB 空闲 模型约 9.1G + 依赖若干
网络 能访问 ModelScope / PyPI 镜像 下载模型和依赖时需要
Git 已安装 用于拉取子模块

为什么锁定 Python 3.10？项目依赖（如 torch==2.3.1、openai-whisper==20231117）在 3.10 下经过验证，更高或更低版本可能出现兼容问题。

2. 获取代码与子模块

CosyVoice 依赖一个 Git 子模块 Matcha-TTS（提供声码器等组件），必须初始化，否则运行时会报找不到模块。

git clone --recursive https://github.com/FunAudioLLM/CosyVoice.git
cd CosyVoice
# 拉取子模块（Matcha-TTS）
git submodule update --init --recursive

项目里几乎所有脚本开头都有一句 sys.path.append('third_party/Matcha-TTS')，就是为了把这个子模块加入 Python 搜索路径。命令行运行时也要设置 PYTHONPATH（见第 6 节）。

3. 创建虚拟环境

用 pyenv 的 Python 3.10 建一个独立的 .venv，后续所有命令都用 .venv/bin/python 执行，不碰全局环境。

cd CosyVoice

# 用 pyenv 的 3.10 创建虚拟环境（路径按你本机 pyenv 版本名调整）
python3 -m venv .venv

# 升级基础工具（用阿里云镜像加速）
.venv/bin/pip install --upgrade pip wheel \
  -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com

4. 安装依赖（含一个必踩的坑）

依赖清单在 requirements.txt。注意里面有 cu121、onnxruntime-gpu、tensorrt、deepspeed 等条目——它们都带 sys_platform == 'linux' 限定，在 macOS 上会被 pip 自动跳过，不用手删。macOS 会走 onnxruntime==1.18.0（CPU 版）那一行。

唯一的坑是 openai-whisper==20231117，必须单独装：

# 4.1 先装除 whisper 外的全部依赖
grep -v "openai-whisper" requirements.txt > /tmp/req_no_whisper.txt
.venv/bin/pip install -r /tmp/req_no_whisper.txt \
  -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com

# 4.2 再用 --no-build-isolation 单独装 whisper
.venv/bin/pip install "openai-whisper==20231117" --no-build-isolation \
  -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com

为什么要这么做？
openai-whisper==20231117 的 setup.py 在构建时要 import pkg_resources。而 pip 默认开启“构建隔离”，会在临时环境里装一个新版 setuptools——新版已经移除了 pkg_resources，于是构建报错 No module named 'pkg_resources'，并且会中断整个安装。加 --no-build-isolation 让它复用 venv 里自带 pkg_resources 的 setuptools，即可绕过。这也是为什么要拆成两步：避免 whisper 一个包的失败拖垮全部依赖安装。

5. 下载模型

从 ModelScope 拉取 Fun-CosyVoice3-0.5B-2512（约 9.1G），存到 pretrained_models/Fun-CosyVoice3-0.5B/：

cd CosyVoice
.venv/bin/python -c "from modelscope import snapshot_download; \
  snapshot_download('FunAudioLLM/Fun-CosyVoice3-0.5B-2512', \
  local_dir='pretrained_models/Fun-CosyVoice3-0.5B')"

下载完后，pretrained_models/Fun-CosyVoice3-0.5B/ 目录里应有模型权重、配置等文件。

首次推理还会联网一次：第一次跑合成时，会从 ModelScope 拉取 wetext 文本正则化资源（很小，几十 KB），之后缓存在 ~/.cache/modelscope/。所以第一次合成前请保持联网。

6. 启动 Web 界面（webui）

cd CosyVoice

# 关键：把 Matcha-TTS 子模块加入 Python 路径
export PYTHONPATH="third_party/Matcha-TTS:$PYTHONPATH"

# 启动 webui，指定端口和模型目录
.venv/bin/python webui.py --port 50000 --model_dir pretrained_models/Fun-CosyVoice3-0.5B
  • CPU 加载模型较慢，首次启动约需 1 分钟；
  • 日志出现监听端口信息后，浏览器打开 http://127.0.0.1:50000；
  • 想换端口改 --port 即可（webui 默认是 8000，本指南统一用 50000）。

停止服务：

# 结束占用 50000 端口的进程
lsof -tiTCP:50000 -sTCP:LISTEN | xargs kill

7. webui 各模式说明（重要）

CosyVoice3 是 CosyVoice2 的子类，webui 上列出 5 种模式，但对 v3 真正可用的只有 3 种：

模式 可用性 说明
预训练音色 ❌ v3 无内置 SFT 说话人（sft 模式需 embedding 字段）
预置音色（zero_shot spk） ✅ 最推荐 下拉选已注册音色，开箱即用，无需上传
3s 极速复刻（zero_shot） ✅ 上传参考音频 + 参考文本，克隆任意音色
跨语种复刻（cross_lingual） ✅ 上传参考音频，跨语种 / 细粒度控制
自然语言控制（instruct） ❌ v3 用 instruct2，webui 调的是旧接口

选到不可用的模式并生成时，界面会弹警告（不会让服务崩溃，见第 10 节问题 5），换对模式重试即可。

8. 三种可用模式怎么用

8.1 预置音色（最省事，推荐先玩这个）

项目自带 4 个 CosyVoice3 官方 demo 参考音，已通过 zero_shot 方式固化为命名说话人，不用每次上传音频。

一次性注册（首次执行一次即可，音色信息会写进模型目录）：

cd CosyVoice
export PYTHONPATH="third_party/Matcha-TTS:$PYTHONPATH"
.venv/bin/python register_spks.py

脚本做的事（见 register_spks.py）：读取 asset/spk_prompts/*.wav 与内置参考文本，给每段文本加上 You are a helpful assistant.<|endofprompt|> 前缀（CosyVoice3 要求 prompt 文本必须含 <|endofprompt|> 标记），再调 add_zero_shot_spk(...) 注册，最后 save_spkinfo() 写入 pretrained_models/Fun-CosyVoice3-0.5B/spk2info.pt。

执行成功会打印：

注册后音色: ['longcheng', 'longhua', 'longshu', 'longbella']

4 个音色：longcheng（中文女声）、longhua / longshu / longbella（英文声音，源自 common_voice 英文样本）。

在 webui 中用：

  1. 推理模式选 预置音色；
  2. 「选择预训练音色」下拉选一个（如 longcheng）；
  3. 「输入合成文本」填目标文本；
  4. 点「生成音频」。

此模式下，上传的 prompt 音频 / prompt 文本 / instruct 文本都会被忽略，选好下拉音色即可。

8.2 3s 极速复刻（克隆任意音色）

  1. 推理模式选 3s 极速复刻；
  2. 上传参考音频（可先用仓库自带的 asset/zero_shot_prompt.wav），采样率 ≥ 16kHz；
  3. 填 prompt 文本，内容须与音频一致，并建议加助手前缀，例如：
    You are a helpful assistant.<|endofprompt|>希望你以后能够做的比我还好呦。
  4. 「输入合成文本」填要合成的目标文本；
  5. 点「生成音频」。

8.3 跨语种复刻 / 细粒度控制

  1. 推理模式选 跨语种复刻；
  2. 上传参考音频；
  3. 合成文本里可用语种标记与控制符，例如 <|en|>...、[breath]、[laughter] 等（支持的控制符见 cosyvoice/tokenizer/tokenizer.py）。

9. 命令行快速验证（不经过 webui）

想确认模型和环境是否正常，可跑仓库根目录的最小脚本 quick_test_cv3.py：

cd CosyVoice
export PYTHONPATH="third_party/Matcha-TTS:$PYTHONPATH"
.venv/bin/python quick_test_cv3.py

它会用 inference_zero_shot 合成一句绕口令（“八百标兵奔北坡……”），成功后在当前目录生成 cv3_zero_shot_0.wav。

更完整的用法（zero_shot / cross_lingual 细粒度控制 / instruct2 / 日文等）见 example.py 里的 cosyvoice3_example() 函数。

10. 常见问题速查

1) No module named 'pkg_resources'（装 whisper 时）
构建隔离环境的新版 setuptools 移除了 pkg_resources。解决：按第 4 节用 --no-build-isolation 单独装 openai-whisper。

2) 没有 GPU / CUDA 怎么办
无需处理。代码自动检测，无 CUDA 时禁用 fp16 / load_jit / load_trt / load_vllm，回退 CPU，只是慢。

3) 找不到 cosyvoice 或 Matcha-TTS 模块
多半是没设 PYTHONPATH 或没初始化子模块。执行前务必：
export PYTHONPATH="third_party/Matcha-TTS:$PYTHONPATH"，并确认第 2 节的 git submodule update --init --recursive 跑过。

4) 端口被占用 / 想换端口
改 --port 参数；或用 lsof -tiTCP:<端口> -sTCP:LISTEN | xargs kill 结束旧进程。

5) 选「自然语言控制」后服务崩溃
根因：v3 的 inference_instruct 会抛 AssertionError: inference_instruct is only implemented for CosyVoice!。项目已给 webui.py 的 generate_audio 推理分支加了 try/except，现在单次失败只弹警告、输出静音，服务继续运行。避免踩坑的办法：用 instruct2 对应的模式（见 example.py），不要在 webui 选「自然语言控制」。

6) 推理很慢
纯 CPU 下 RTF≈1.8 属正常。想快只能上 GPU 环境。

11. 关键路径速查

项目 路径
项目根目录 <你的目录>/CosyVoice
虚拟环境 Python .venv/bin/python
模型目录 pretrained_models/Fun-CosyVoice3-0.5B/
音色 prompt 音频 asset/spk_prompts/*.wav
音色信息文件 pretrained_models/Fun-CosyVoice3-0.5B/spk2info.pt
webui 入口 webui.py
音色注册脚本 register_spks.py
最小验证脚本 quick_test_cv3.py
完整用法示例 example.py（cosyvoice3_example()）
依赖清单 requirements.txt

附：最快上手路径（TL;DR）

git clone --recursive https://github.com/FunAudioLLM/CosyVoice.git
cd CosyVoice
git submodule update --init --recursive                                    # 1. 子模块
python3 -m venv .venv                           # 2. 虚拟环境
.venv/bin/pip install --upgrade pip wheel -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com
grep -v "openai-whisper" requirements.txt > /tmp/req_no_whisper.txt        # 3. 依赖（两步）
.venv/bin/pip install -r /tmp/req_no_whisper.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com
.venv/bin/pip install "openai-whisper==20231117" --no-build-isolation -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com
.venv/bin/python -c "from modelscope import snapshot_download; snapshot_download('FunAudioLLM/Fun-CosyVoice3-0.5B-2512', local_dir='pretrained_models/Fun-CosyVoice3-0.5B')"  # 4. 模型
export PYTHONPATH="third_party/Matcha-TTS:$PYTHONPATH"                      # 5. 路径
.venv/bin/python register_spks.py                                          # 6. 注册音色（可选）
.venv/bin/python webui.py --port 50000 --model_dir pretrained_models/Fun-CosyVoice3-0.5B  # 7. 启动

浏览器打开 http://127.0.0.1:50000，选「预置音色」→ 下拉选 longcheng → 填文本 → 生成。

posted @ 2026-07-15 10:19  无穷小缘  阅读(13)  评论(0)    收藏  举报