我这周基本都泡在 Windows 机器上跟 CosyVoice 较劲。起因是实验室换了一批 Windows 笔记本要在这批机器上跑阿里通义实验室开源的 CosyVoice 做语音合成实验。Clone 仓库、装依赖、下模型常规步骤看着都不复杂真正把我卡住的是它的文本前端依赖 ttsfrd——这个库只发布 Linux 版本的 Python wheel 包Windows 下直接pip install就是死路一条。折腾一圈之后我把解决方案锁定在 WSL2 上最终把 ttsfrd 依赖顺利装好文本前端的拼音解析、韵律预测全部正常跑通。这篇文章就把我完整的操作路径和踩坑记录沉淀下来。如果你是刚拿到 Windows 机器、又需要在 WSL 里跑 CosyVoice 的同学可以按着下面的步骤直接抄作业。我会把每个关键步骤为什么这样做、会遇到什么坑、怎么排查都讲清楚避免你再走一遍我花两天才绕出来的弯路。1. 先搞清楚为什么非要在 WSL 里装 ttsfrd很多第一次接触 CosyVoice 的人会想当然既然项目是 Python 写的那 Windows 下搞个 Python 环境不就行了实际上 CosyVoice 有部分原生依赖并没有发布 Windows 版本其中最有代表性的就是 ttsfrd。1.1 ttsfrd 到底是个什么东西如果你接触过 TTS 系统应该听过“文本前端”这个词。文本前端负责把输入的普通文本转换成模型真正能读懂的符号序列流程大致是中文文本 - 分词 - 注音 - 韵律预测 - 音素序列。CosyVoice 在训练和推理时文本前端质量直接影响到最终合成的自然度而 ttsfrd 就是阿里内部沉淀下来的一个文本前端处理库里面封装了分词、字音转换、韵律边界预测等能力。问题就出在发布形式上。ttsfrd 通常以ttsfrd-0.3.7-cp310-cp310-linux_x86_64.whl这类包名发布注意中间写着linux_x86_64说明它只提供 Linux 平台编译好的二进制。Windows 下就算你强行安装也会在加载动态库的时候挂在OSError: cannot open shared object file这类错误上。所以想在 Windows 机器上完整跑起 CosyVoice必须有一层 Linux 运行时环境。这里顺带说一句ttsfrd 对 Python 版本也比较挑剔。我试过在 Python 3.8 和 Python 3.11 下踩到过不同的问题最后按照官方文档建议锁在 Python 3.10 才顺利通过。后面我也会建议你直接用 conda 建一个干净的 3.10 环境不要贪新用 3.12。1.2 为什么不用双系统也不用普通虚拟机既然需要 Linux 环境你可能会想直接装个双系统或者开个 VirtualBox、VMware 虚拟机行不行双系统的问题是切换成本太高。你开着 Windows 写文档、跑 Office突然要合成一段语音就得重启进 Linux合完想回来处理数据又得重启回 Windows。这种来回切换会严重打断工作流而且一旦在 Windows 侧访问 Linux 分区操作不当还容易弄坏文件系统。普通虚拟机VirtualBox、VMware倒是能同时跑 Windows 和 Linux但有两个致命问题。第一是文件共享和端口转发配置麻烦模型放在 Windows 盘还是 Linux 盘需要仔细规划第二是性能损耗明显CPU 密集型的文本处理任务还能忍真到了模型推理阶段GPU 穿透配置复杂很多新手在这一步直接劝退。WSL2 的做法完全不同。它本质上跑的是一个轻量级虚拟机但微软帮我们把内核管理、文件互访、端口转发都做成了默认配置。Windows 和 WSL 之间可以直接通过\\wsl$访问文件WSL 内部也能挂载 Windows 盘符开发体验非常接近原生 Linux。对于 CosyVoice ttsfrd 这种场景WSL2 是最省心的路子。2. 搭建 WSL2 环境版本选择和初始化配置如果你之前装过 WSL那想必对 WSL1 和 WSL2 的区别有所了解。WSL1 通过系统调用翻译层模拟 Linux 环境很多涉及到 native 编译和动态链接库的依赖会莫名奇妙地出问题WSL2 使用了真正的 Linux 内核对像 ttsfrd 这种二进制 wheel 包的兼容性要好得多。所以在开始之前请务必确认你用的是 WSL2。2.1 一条命令安装 WSL2在 Windows 10 2004 及以上版本或者 Windows 11 上安装 WSL2 已经非常无脑。用管理员身份打开 PowerShell然后执行wsl --install这条命令会自动完成三件事开启需要的 Windows 功能、下载并安装默认的 Ubuntu 发行版、配置 WSL2 为默认版本。安装完成后按照提示重启电脑系统会让你设置 Ubuntu 的用户名和密码。这个用户名不用跟 Windows 账号一致你可以随意设置但一定要记住后面很多操作都需要用到 sudo 权限。如果你的系统比较旧wsl --install可能不可用那就需要手动开启两个功能“适用于 Linux 的 Windows 子系统”和“虚拟机平台”然后去 Microsoft Store 安装 Ubuntu再执行wsl --set-version Ubuntu 2把发行版切换到 WSL2。开启虚拟化之前还要确认 BIOS 里已经打开了 CPU 的虚拟化功能Intel VT-x / AMD-V否则 WSL2 起不来。安装完成后打开 PowerShell 执行wsl -l -v如果你看到 Ubuntu 那行已经显示为 2那就说明 WSL2 已经是默认版本了。如果不放心还可以执行wsl --set-default-version 2强制后续安装的发行版都使用 WSL2。2.2 WSL 内的基础配置换源、更新、装工具进入 WSL 终端可以直接在 PowerShell 里执行wsl或者在 Windows Terminal 中选择 Ubuntu 标签页第一件事是更新系统软件源和包。sudo apt update sudo apt upgrade -y这里有一个很容易被忽略的点如果你在 WSL 里用官方默认源在国内网络环境下apt update可能很慢甚至超时。建议先把 apt 源换成清华或者阿里云的镜像源。Ubuntu 24.04 之后源配置采用了新的 deb822 格式文件路径在/etc/apt/sources.list.d/ubuntu.sources手动改成清华源示例sudo sed -i s|http://archive.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g /etc/apt/sources.list.d/ubuntu.sources sudo sed -i s|http://security.ubuntu.com/ubuntu|https://mirrors.tuna.tsinghua.edu.cn/ubuntu|g /etc/apt/sources.list.d/ubuntu.sources如果你用的是彻底移除默认源然后重新写的方案务必注意只保留一个源配置文件避免地址冲突。换完源之后再跑一次sudo apt update速度快很多。接下来安装基础编译工具和 git这部分是后续安装依赖的必需品sudo apt install -y build-essential git python3-pipbuild-essential里包含了 gcc、g、make 等编译工具很多 Python 依赖在安装时如果发现没有现成的 wheel会现场编译源码没有这组工具会直接报错。3. Python 虚拟环境准备conda 还是 venv进入 CosyVoice 目录之前先把 Python 环境想清楚。这一步决定你后面会不会被各种依赖冲突折磨到头皮发麻。3.1 为什么我建议你使用 conda你可能会问Ubuntu 自带 Python直接pip install不就行了问题是系统 Python 环境非常容易被污染而且你今天装一个项目 A 的依赖明天又要装项目 B 的依赖两个项目的 torch 版本冲突后你会陷入无休止的重新安装和反复卸载中。conda 的好处在于可以为每个项目创建独立的虚拟环境并且能够方便地指定 Python 版本。CosyVoice 官方文档推荐使用 Python 3.10用 conda 来做就特别顺畅。安装 Miniconda 是这样做的wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh安装过程中会问你安装路径我一般直接放在~/miniconda3。装完之后重新打开终端或者执行source ~/.bashrc让 conda 命令生效。建议顺手把 conda 的源也换成国内镜像否则后续创建环境时下载基础包还是会慢conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --set show_channel_urls yes创建 CosyVoice 专用环境conda create -n cosyvoice python3.10 -y conda activate cosyvoice在你看到命令行前面出现(cosyvoice)字样之前都不要继续下一步否则依赖很容易装到系统的 Python 环境里。3.2 pip 源配置提前省下半小时安装依赖前先把 pip 源切到国内镜像。这里我推荐清华源或者阿里源速度差别不大。执行pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ pip config set global.trusted-host mirrors.aliyun.compip config会帮你把配置写到当前用户目录下的~/.config/pip/pip.conf里不用手动维护。配置完源之后后面安装 torch、torchaudio、transformers 这些体积庞大的包时下载速度会明显快很多省下来的时间非常可观。4. CosyVoice 代码获取与 ttsfrd 依赖安装这一节是整个安装流程的重头戏也是踩坑最多的地方。我会把代码获取、普通依赖安装、ttsfrd 单独安装、环境变量配置四步拆开讲清楚。4.1 克隆仓库并安装常规依赖先在 WSL 里把你的项目目录建好我习惯放在~/workspacemkdir -p ~/workspace cd ~/workspace git clone https://github.com/FunAudioLLM/CosyVoice.git cd CosyVoice这里我有一个非常强烈的建议不要把代码放在/mnt/c/底下的 Windows 文件夹里克隆和运行。虽然 WSL2 可以访问 Windows 盘符下的文件但跨文件系统的 I/O 性能很差而且很多依赖在读取文件权限方面会产生各种奇怪问题。我一开始图方便直接 clone 到了 Windows 桌面结果装依赖时频繁报权限错误后来把代码挪回 WSL 内部文件系统问题全部消失。仓库克隆完成后激活你的 conda 环境安装常规依赖conda activate cosyvoice pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/requirements.txt 里包含了 PyTorch、torchaudio、transformers、modelscope 等主要依赖。这一步骤会下载很多大包建议确保网络通畅中途不要 CtrlC。如果你看到某个包安装失败先不要急着重试整个命令可以先单独安装失败的包排查报错原因后再继续。4.2 ttsfrd wheel 包下载、安装和环境变量常规依赖装完后import ttsfrd大概率还是报ModuleNotFoundError因为 ttsfrd 需要单独手动安装。先确认你的 Python 版本和系统架构执行python --version uname -m正常情况下你会看到Python 3.10.x和x86_64。然后从 CosyVoice 官方仓库提供的链接或者官方文档指定的位置下载对应版本的 whl 文件例如ttsfrd-0.3.7-cp310-cp310-linux_x86_64.whl。文件名里的cp310就是给 Python 3.10 用的如果你创建的是 Python 3.11 环境就要找cp311对应的包。拿到 whl 文件后安装pip install ttsfrd-0.3.7-cp310-cp310-linux_x86_64.whl安装完成后不要急着跑 Python还差一个关键环节配置TTSFRD_ROOT环境变量。ttsfrd 处理中文文本时还需要词表、字典等资源文件它运行时会通过这个环境变量去定位资源目录。我当时的做法是让 Python 自己告诉我们安装路径export TTSFRD_ROOT$(python -c import ttsfrd, os; print(os.path.dirname(ttsfrd.__file__)))然后把这一行追加进~/.bashrc防止每次打开终端都要重新设置echo export TTSFRD_ROOT$(python -c import ttsfrd, os; print(os.path.dirname(ttsfrd.__file__))) ~/.bashrc source ~/.bashrc这里要注意一点如果后续运行 CosyVoice 时遇到“找不到 resource 或 dict 目录”的提示通常意味着TTSFRD_ROOT指向的目录不对或者资源文件没有跟 whl 一起完整释放。不同版本的 ttsfrd 资源组织可能不同建议以官方仓库最新说明为准把环境变量改到包含dict或resource的上一层目录即可。4.3 验证 ttsfrd 是否真正可用安装完不能光看pip show ttsfrd还要实际跑一下导入和初始化。我用一个最简单的脚本验证python -c import ttsfrd; print(ttsfrd imported)如果能正常打印ttsfrd imported说明动态库也加载成功了。接下来尝试创建一个处理引擎实例import ttsfrd engine ttsfrd.TTSFRD() print(engine init ok)如果这一步也没有报错那么 ttsfrd 基本就绪。如果在这里报OSError或者RuntimeError首先检查刚才的TTSFRD_ROOT路径是否存在、是否有读权限其次确认 whl 文件是否下载了正确的系统架构版本。我曾经手滑下载了 arm64 的包结果一直挂在动态库加载上换成 x86_64 版本后立刻通过。5. 实际运行中常见的坑和排查思路依赖装完不代表万事大吉我在把 CosyVoice 真正跑起来的过程中还踩了几个 WSL 环境特有的坑这里集中写出来给你做参考。5.1 ttsfrd 相关的三类典型报错第一类是ModuleNotFoundError: No module named ttsfrd。这个一般是因为你换了 Python 环境或者 whl 被安装到了别的环境里。检查方法很简单执行which python看当前是不是cosyvoice环境下的解释器如果不是执行conda activate cosyvoice再重新安装。第二类是OSError: libttsfrd.so: cannot open shared object file。这通常是包下载错了架构比如在 x86_64 的 WSL 里装了 arm64 的 whl。可以执行uname -m查看实际架构再去下载匹配的包。第三类是RuntimeError: TTSFRD_ROOT is not set或者类似提示。这个就是环境变量没生效。别忘了执行source ~/.bashrc或者重启 WSL 终端然后再运行脚本。这三类问题占了 ttsfrd 故障的九成以上排查顺序建议是否激活环境 - 是否安装成功 - 架构是否匹配 - 环境变量是否正确。5.2 WSL 文件系统和资源限制的坑WSL2 默认会动态占用宿主机内存但如果你在.wslconfig里没做任何限制某些机器上可能会因为宿主机内存不足导致 WSL 崩溃或者 OOM。尤其是在跑 CosyVoice 加载大模型的时候内存占用很可观。建议在 Windows 用户目录下新建一个.wslconfig文件写入[wsl2] memory8GB processors4 swap4GB根据你的物理内存大小调整至少给 WSL 分配 8GB。改完配置后在 PowerShell 里执行wsl --shutdown重启 WSL 才会生效。另外如果你要在 WSL 里训练模型或者使用 GPU 推理需要注意 NVIDIA 驱动是装在 Windows 侧的WSL 内部不需要也没法直接安装显卡驱动。安装好 Windows 侧驱动后在 WSL 里执行nvidia-smi如果能显示显卡信息说明 GPU 可以被 WSL 使用。如果只是为了先跑通 ttsfrd 和文本前端CPU 模式就足够不必一上来就折腾 CUDA。5.3 模型下不动怎么办CosyVoice 的模型文件比较大如果你的网络状况不好从默认源下载模型可能非常慢甚至中途断掉。我建议优先使用 ModelScope 的 SDK 下载因为它的服务器在国内速度会好很多。pip install modelscope python -c from modelscope import snapshot_download; snapshot_download(iic/CosyVoice-300M, local_dir./pretrained_models/CosyVoice-300M)如果 ModelScope 也慢可以先在 Windows 浏览器里用下载工具把模型文件下载到 Windows 盘再通过\\wsl$路径或者cp /mnt/c/xxx拷贝进 WSL。这种“下载工具 手动拷贝”的方式最朴素但成功率最高。注意拷贝完确认文件大小完整不要漏文件。6. 跑通一条完整链路后的经验总结经过上面这些步骤你的 WSL 环境已经具备运行 CosyVoice 的条件。最后我补几个可以让后续使用更顺畅的小习惯。6.1 写一个启动脚本避免每次踩环境变量坑我后来把环境初始化写成了一个脚本start_cosyvoice.sh内容大致如下#!/bin/bash source ~/miniconda3/etc/profile.d/conda.sh conda activate cosyvoice export TTSFRD_ROOT$(python -c import ttsfrd, os; print(os.path.dirname(ttsfrd.__file__))) cd ~/workspace/CosyVoice echo CosyVoice environment ready.每次打开 WSL 终端直接执行bash start_cosyvoice.sh就不用担心忘记激活环境或者变量没设置的问题。这个习惯能帮你省掉大量重复操作尤其是当你经常在多个项目之间切换的时候。6.2 依赖升级要谨慎别手滑升了 ttsfrdttsfrd 不是一个高频更新的包不要在跑通环境之后随意pip install --upgrade ttsfrd。它跟 CosyVoice 的版本配合是有讲究的升级后一旦接口变化你就要回头排查是不是它引起的兼容问题。保持当前可用版本不动是省心的选择。另外一个容易被忽略的点在 WSL 里跑 CosyVoice 时尽量把 Windows 侧杀毒软件对\\wsl$路径的实时扫描关掉否则一些大文件读写会被拖慢严重时会造成 Python 进程假死。这个属于经验之谈具体关闭方式取决于你用的杀毒软件不做展开。就我个人实际体验而言把 CosyVoice 和 ttsfrd 放在 WSL2 里跑是我在 Windows 机器上能想到的最顺路径。虽然第一次配置花了接近两天时间但把流程理顺之后后续新建环境、切换项目都很快。如果你也卡在 ttsfrd 这个环节可以对照我上面的步骤逐步排查。这里再分享一个小技巧排查问题前先看一眼tty里当前的工作目录和环境变量是不是你预期的那个很多看起来很复杂的问题源头其实只是一个没生效的~/.bashrc。