Voicebox 完整安装教程从下载到首次语音生成【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voiceboxVoicebox 安装最常见的卡点其实不在安装包而在首次运行macOS 提示已损坏、后端状态红灯、模型迟迟下不完。本文按启动前、启动中、生成时三个阶段把 Voicebox 部署与首次运行的完整链路一次讲完每个卡点都给出可直接执行的命令跟着走即可跑通。一、装前体检配置与门槛最低门槛macOS 11 / Windows 10 / Linux8GB 内存、5GB 空闲磁盘即可安装推荐 16GB 内存并配一张 CUDA 显卡或 Apple Silicon纯 CPU 模式也能跑只是慢 5–10 倍。四条安装路线按环境二选一路线适用人群耗时量级macOS DMGApple Silicon / Intel Mac解压拖入 Applications1–2 分钟Windows MSI/SetupWindows 10向导安装2–5 分钟源码构建Tauri Python 后端Linux 用户5–10 分钟需预装 Rust、just、BunDocker 容器无头服务器 / 共享 GPU 机器首次构建数分钟之后秒级启动本地安装的用户注意给模型留磁盘Kokoro 级小模型约 350 MBTADA 3B 这类大模型可达 ~8 GB建议预留 10GB 空闲空间。Docker 适合服务器场景docker compose up构建并启动后浏览器打开127.0.0.1:17600当前 docker-compose.yml 把容器内 17493 映射到宿主机 17600避免与本地桌面版冲突完整配置说明见 docs/content/docs/overview/docker.mdx。二、按阶段排障启动前系统拦截与源码构建卡点 1桌面端打不开。症状双击Voicebox.app弹应用已损坏无法打开或 Windows 弹 SmartScreen 蓝屏已保护你的电脑。定位应用未做开发者证书签名系统对未签名应用的拦截属于正常行为不是真的损坏。修复macOS 打开终端执行xattr -cr /Applications/Voicebox.app再重新打开即可10 秒生效无需重装。Windows 在拦截界面点更多信息再点仍要运行同样 10 秒不用改任何系统设置。卡点 2Linux 没有安装包。症状发布页找不到 Linux 预编译包或自行拿到的 AppImage 报权限被拒绝。定位官方推荐走源码构建依赖安装与打包各一条命令。修复先装好 Rust 工具链、bun和justcargo install just然后git clone https://gitcode.com/GitHub_Trending/voicebox1/voicebox cd voicebox just setup # 建 Python 3.12 venv装全部依赖自动按 GPU 选 PyTorch 版本 just build # 构建桌面端产物在tauri/src-tauri/target/release/bundle/just --list可查看全部命令定义见 justfile。若坚持用 AppImage先chmod x voicebox-*.AppImage再运行。启动中后端红灯端口 17493、权限、日志症状左下角状态灯红灯提示 Failed to connect to server。定位内置 Python 后端没起来或起不来按端口 → 权限 → 日志三步查。修复# 1. 检查端口 17493 是否被占用 lsof -i :17493 kill -9 PID # 确认是无主进程后再杀 # 2. 给服务二进制补执行权限macOS/Linux chmod x ~/Library/Application\ Support/sh.voicebox.app/backend/voicebox-server # 3. 跟日志看真实报错 tail -f ~/Library/Application\ Support/sh.voicebox.app/logs/server.logWindows 上端口查询换成powershell -Command Get-NetTCPConnection -LocalPort 17493 -State Listen日志在%APPDATA%\sh.voicebox.app\logs\server.log。若日志里出现flash-attn is not installed直接忽略——它是可选加速库PyTorch 会自动回退到 SDPA 注意力速度几乎无损。更多症状与解法收录在 troubleshooting.mdx。生成时模型下载卡住、GPU 加速未生效卡点 1模型迟迟下不动。症状点生成后进度条停在 Downloading... / Loading model...。定位首次生成会自动下载所选引擎的模型网络侧受 HuggingFace Hub 访问限制是主因。修复进度可在 Settings → Models 查看小带宽环境先选Kokoro~350 MB或LuxTTS~300 MB起步下载卡死时用代理或手动把模型拉到缓存目录pip install huggingface_hub huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base缓存目录可用环境变量VOICEBOX_MODELS_DIR自定义Docker 部署若重启就重新下载检查 compose 里的huggingface-cache卷是否保留。卡点 2GPU 加速没生效或显存不足。症状生成报CUDA out of memory或有 GPU 但速度与纯 CPU 无异。定位依次查显存占用生成需 6GB、后端类型、显卡选择。修复先关闭游戏、视频编辑等吃显存的应用再重启 Voicebox或 Settings → Generation 切换 CPU 模式慢 5–10 倍但改用系统内存小模型下依然可用。Apple Silicon 用户确认 Settings → Server Status 显示Backend: MLX比 PyTorch 快 4–5 倍若显示 PYTORCH重装依赖pip install -r backend/requirements-mlx.txt多卡机器在 Settings → Generation → GPU Device 手动选对显卡Windows 用户确认 GPU 面板里装好了 CUDA 后端。三、跑通验证最小闭环三步确认全链路可用状态灯启动 Voicebox左下角指示器由红转绿说明 17493 端口的后端已就绪建档案进入 Voices 页点 Create Voice上传或录制 10–30 秒清晰音频WAV/MP3/M4A填名称与语言后保存。样本质量直接决定克隆效果挑无背景噪声的片段同一说话人多条样本更稳生成一句到 Generate 页选刚建的档案输入一句话点 Generate能听到声音即安装完成 。第一次会叠加模型下载与引擎初始化等几分钟属正常后续生成命中缓存速度会明显加快。四、速查对照表卡点关键动作预计耗时macOS已损坏xattr -cr /Applications/Voicebox.app10 秒Windows SmartScreen更多信息 → 仍要运行10 秒Linux 无安装包just setup just build或docker compose up5–10 分钟后端红灯查端口 17493 → 二进制权限 →server.log2 分钟模型下载卡住换小模型 / 代理 /huggingface-cli手动下载视网速显存不足 / 速度慢关吃显存应用 / 切 CPU 模式 / 核对 MLX 后端2 分钟绿灯亮起且能生成音频Voicebox 的安装、部署与首次运行这条链路就算全部打通后续只需关注档案质量与模型选择完整后端依赖清单见 backend/requirements.txt。 语音档案、生成历史与音频默认全部保存在本地macOS 在~/Library/Application Support/sh.voicebox.app/、Windows 在%APPDATA%\sh.voicebox.app\、Linux 在~/.config/sh.voicebox.app/备份时认准这一个目录。【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考