AI工具

Voicebox Windows 本地部署：声音克隆、Qwen3-TTS、Whisper 与 MCP 接入

在 Windows 本地安装 Voicebox，配置声音克隆、Qwen3-TTS、Whisper 语音输入与 MCP，并排查 CUDA、模型下载和显存问题。

Voicebox 是一个本地优先的开源 AI 语音工作台，把声音克隆、文字转语音、Whisper 语音识别、全局听写、REST API 和 MCP Server 放进同一个桌面应用。

它支持 Windows CUDA、macOS MLX、Linux、AMD ROCm、Intel Arc 和 Docker。Windows 用户可以直接安装 MSI，不必先搭建 Python 项目。模型、参考音频和生成结果默认保留在本机，适合不希望把声音样本上传到第三方服务的场景。

Quick Answer

Windows 上最省事的方式是从 Voicebox Releases 下载 MSI，首次运行后只安装一个适合显存的 TTS 引擎，先完成普通文字转语音，再添加参考音频做声音克隆。需要让 Claude Code、Cursor 或其他 Agent 发声时，再到 Voicebox 的 MCP 设置中启用服务并按界面生成的地址配置客户端。

不要一开始同时下载全部模型。Qwen3-TTS、Chatterbox、TADA 和 Whisper 会分别占用磁盘与显存，模型过多会让首次排障变得困难。

Voicebox 能做什么

当前项目把输入和输出两条语音链路合并到一起：

  • 用几秒参考音频创建声音配置；
  • 通过 Qwen3-TTS、Chatterbox、Kokoro 等引擎生成语音；
  • 使用 Whisper 把麦克风或音频文件转成文字；
  • 使用全局快捷键在其他应用中听写；
  • 通过 REST API 或 MCP 让 AI Agent 调用语音；
  • 在 Stories 编辑器中组合多角色对话、播客或旁白；
  • 对生成结果添加混响、变调、压缩等效果。

项目 README 当前列出 7 个 TTS 引擎和 23 种语言，但各引擎支持的语言、显存需求和表现不同，不能把“应用支持 23 种语言”理解为每个模型都支持全部语言。

Windows 安装步骤

1. 检查显卡和驱动

NVIDIA 用户先运行：

1

nvidia-smi

如果命令不存在或无法显示驱动信息，先修复显卡驱动。Voicebox 安装成功不代表 CUDA 推理一定可用。

没有 NVIDIA 显卡也可以尝试 CPU 或项目支持的其他后端，但生成速度和可用模型会受到影响。

2. 下载 MSI

从官方 Release 页面下载最新 Windows 安装包：

1

https://github.com/jamiepine/voicebox/releases/latest

安装后从开始菜单启动。Windows SmartScreen 如果提示未知发布者，应先核对下载地址、Release 文件名和项目仓库，不要从第三方网盘寻找所谓绿色版。

3. 只下载一个模型测试

首次测试可以按硬件选择：

场景 建议起点
CPU 或显存很小 Kokoro 或 LuxTTS
需要中文、多语言和声音克隆 Qwen3-TTS 0.6B
更重视表达控制 Qwen3-TTS 1.7B 或 Qwen CustomVoice
需要更多语言覆盖 Chatterbox Multilingual

具体可用模型以应用当前的模型管理页面为准。模型下载完成后，先输入一小段文字生成默认声音，确认后端正常，再创建声音配置。

创建声音克隆配置

参考音频直接影响结果。建议：

  1. 使用单人、无背景音乐、无混响的录音；
  2. 保持自然语速和稳定音量；
  3. 剪掉长时间静音与明显噪声；
  4. 只使用自己拥有授权的声音；
  5. 先用短句测试，不要直接生成长文章。

在 Voice Profile 中上传或录制参考音频，选择支持 zero-shot cloning 的引擎，然后输入测试文本。不同引擎对参考音频长度和转录准确度的要求不同，如果一个引擎效果差，可以换引擎比较，不要只反复提高音量。

使用 Whisper 听写和转写

Voicebox 的语音输入使用 Whisper，可以选择 Base、Small、Medium、Large 或 Turbo 等尺寸。通常：

  • 小模型下载快、占用低，适合日常听写；
  • 大模型更重，适合口音、噪声或复杂内容；
  • Turbo 适合希望提高速度又保持较好质量的任务。

全局听写需要系统麦克风权限。出现“能录音但无法粘贴”时，要分别检查麦克风权限、Voicebox 快捷键冲突，以及目标应用是否允许自动输入。

接入 MCP Agent

Voicebox 内置 MCP Server，可以让支持 MCP 的客户端调用 voicebox.speak。推荐流程是：

  1. 在 Voicebox 中完成一次手动语音生成；
  2. 打开 Settings → MCP；
  3. 启用 MCP，并复制界面提供的连接信息；
  4. 在 Claude Code、Cursor、Cline 或其他 MCP 客户端中添加该服务；
  5. 让 Agent 只说一句短文本，确认连接和声音配置；
  6. 再为不同 Agent 绑定不同 Voice Profile。

项目同时提供 HTTP 与 stdio 传输方式。不要凭旧教程手写端口和二进制路径，应优先使用当前版本设置页面生成的配置。

Agent 发声适合完成通知、审批问题和短状态提示。不要让它朗读完整日志，否则会占用生成队列，也很难从声音中定位技术错误。

Docker 运行

项目 README 给出的 Docker 入口是：

1

docker compose up

Docker 更适合 Linux 服务器或希望隔离依赖的用户。Windows 上如果需要 GPU，还要确认 Docker Desktop、WSL2、NVIDIA 驱动和容器 GPU 支持均正常。桌面听写和全局快捷键更适合原生 MSI 版本。

官方 docker-compose.yml 默认是 CPU 构建，并不是自动使用 NVIDIA GPU。它把服务限制在本机回环地址：

1

127.0.0.1:17600 -> container:17493

因此 Docker 版健康检查应访问主机的 17600，而不是桌面版常用的 17493：

1

Invoke-RestMethod http://127.0.0.1:17600/health

Compose 文件还定义了三类持久化数据：

数据 默认位置 作用
生成音频 ./output 方便从宿主机直接读取结果
voicebox-data Docker named volume 保存 Profile、数据库和应用数据
huggingface-cache Docker named volume 避免重建后重新下载模型

停止容器时不要随手加 -v：

1

docker compose down

docker compose down -v 会同时删除 named volumes，可能让模型缓存和应用数据一起消失。

理解首次生成为什么很慢

官方排障文档说明，第一次生成可能需要 2–5 分钟，因为应用要下载并初始化模型。不同引擎的模型规模差距很大：Kokoro 大约 350 MB，而 TADA 3B 可达到约 8 GB。

首次测试时按以下顺序观察：

  1. Settings → Models 是否显示下载进度；
  2. 网络是否能访问 Hugging Face；
  3. 模型下载完成后，GPU 或 CPU 是否开始工作；
  4. 第二次生成是否明显变快。

如果第一次慢、第二次正常，这不是故障。只有下载进度长期不变、日志出现错误或每次启动都重新下载，才需要检查网络和缓存目录。

低带宽或只想确认安装是否成功时，官方建议先用 Kokoro 或 LuxTTS，二者下载量约 300–350 MB，再决定是否安装更大的克隆模型。

查看服务状态和日志

桌面应用后端默认使用 17493。左下角出现红色状态或提示 Failed to connect to server 时，先检查端口：

1

Get-NetTCPConnection -LocalPort 17493 -State Listen

如果返回了其他进程，记录 PID：

1

Get-Process -Id (Get-NetTCPConnection -LocalPort 17493 -State Listen).OwningProcess

确认该进程可以停止后，再正常关闭它。不要看到端口占用就直接杀死未知系统进程。

Windows 服务日志位于：

1

type %APPDATA%\sh.voicebox.app\logs\server.log

PowerShell 中可以实时查看尾部：

1

Get-Content "$env:APPDATA\sh.voicebox.app\logs\server.log" -Tail 100 -Wait

日志至少可以区分四类问题：服务未启动、模型下载失败、CUDA/显存错误，以及音频或数据库错误。

flash-attn is not installed 要不要修

Windows 日志可能反复出现：

1

Warning: flash-attn is not installed. Will only run the manual PyTorch version.

官方文档明确说明这通常可以忽略。Windows 没有稳定的官方 flash-attn 支持，Voicebox 会使用 PyTorch 自带的 SDPA，语音仍能正常生成。不要把这条 Warning 当成服务启动失败，也不建议为了消除日志而随意安装不匹配的社区 wheel。

只有在 Linux、CUDA 与 PyTorch 版本完全匹配，并且确认性能确实受限时，才考虑：

1

pip install flash-attn --no-build-isolation

编译可能持续二十分钟以上，失败也不影响继续使用默认后端。

显存与 CPU 模式怎么选

官方排障文档把 6GB 以上显存作为 GPU 生成的实用门槛提示。不同引擎仍会有差异，因此应以实际模型和文本长度为准。

出现 CUDA out of memory 时按以下顺序处理：

  1. 关闭游戏、视频编辑器和占用 WebGL 的浏览器标签；
  2. 在 Voicebox 中卸载当前不用的模型；
  3. 重启应用，清理已经占用但未释放的显存；
  4. 换较小模型；
  5. 拆分长文本；
  6. 最后再切换到 Settings → Generation → Use CPU instead of GPU。

CPU 模式会使用系统内存，官方预计可能比 GPU 慢 5–10 倍。它适合验证功能或低频生成，不适合把显存问题隐藏起来后继续批量任务。

声音质量应该怎样对比

不要只生成一句话就判断模型。准备一组固定测试文本：

1
2
3
4
5

1. 普通陈述句：测试音色稳定性和自然停顿。
2. 数字与英文缩写：测试中英文混读。
3. 长句和逗号：测试呼吸与分句。
4. 专有名词：测试发音和文本规范化。
5. 情绪标签：只用于明确支持标签的引擎。

每个 Voice Profile 使用同一组文本、同一输出格式和相近参数。官方建议参考音频使用 10–30 秒清晰录音，并可以添加同一说话人的多段样本。音色相似但语气僵硬时，检查参考样本本身是否过于单调，而不是只增加样本长度。

模型缓存和数据备份

应用提供模型目录迁移和 Profile 导入导出。准备升级、清理磁盘或重装前，优先从应用中导出重要 Profile，并记录模型目录。

官方文档给出了直接删除数据库的恢复方法，但这会丢失 Voice Profiles 和生成历史，不能作为普通排障的第一步。遇到 SQLite lock 时先关闭所有 Voicebox 实例并备份数据，再根据日志处理锁文件。

模型版本异常时，也不要直接删除整个 Hugging Face 缓存。先在 Settings → Models 中删除具体模型；手工清理应限定到明确的模型目录，并确保应用已经关闭。

远程访问不要直接暴露端口

Voicebox 后端提供健康检查：

1

curl http://<server-ip>:17493/health

这只能验证服务是否可达，不代表适合直接暴露到公网。远程使用时至少需要：

  • 防火墙只允许可信来源；
  • 通过 VPN、SSH 隧道或带认证的反向代理访问；
  • 不公开模型管理、Profile 和生成接口；
  • 检查 MCP 客户端是否会把工具地址写入同步配置；
  • 定期查看访问日志。

如果只是同一台电脑上的 Agent 调用，应继续绑定 127.0.0.1，不需要开放局域网端口。

常见问题排查

模型下载卡住

先确认磁盘空间和网络，再检查 Hugging Face Hub 是否可访问。Voicebox 模型页面支持取消、清理和迁移时，应优先使用内置功能，不要直接删除整个数据目录。

需要手工验证时，可以安装 Hugging Face CLI 并单独尝试模型下载：

1
2

pip install huggingface_hub
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base

CLI 也无法下载时，问题通常在网络、代理、磁盘或 Hugging Face 访问，而不是 Voicebox 界面。

CUDA 可用但生成时显存不足

关闭其他占用 GPU 的程序，卸载当前不用的模型，换用较小引擎或 0.6B 版本，并缩短一次生成的文本。长文本虽然可以自动分块，仍会增加任务时间和缓存占用。

中文发音不自然

确认当前引擎明确支持中文，参考音频语言与生成文本尽量一致。英文专用模型即使能读出汉字，也不代表中文质量合格。

MCP 已配置但 Agent 没有声音

先在 Voicebox 内手动生成语音，再检查 MCP 客户端是否发现 voicebox.speak、Voice Profile 名称是否存在，以及 Voicebox 是否仍在运行。把“工具未连接”和“语音生成失败”分开排查。

隐私与声音授权

本地运行降低了上传声音样本的风险，但不自动解决授权问题。不要克隆他人的声音用于冒充、欺诈或未经同意的公开内容。公开发布生成音频时，最好明确标注合成来源，并妥善保护参考音频和导出的 Voice Profile。

参考资料