unmute

环境要求

• 支持 CUDA 的 GPU，显存至少 16 GB
• CPU 架构必须为 x86_64（官方无 aarch64 计划）
• 操作系统：Linux，或 Windows + WSL；不支持原生 Windows 与 macOS
• 远程访问需能使用 SSH 端口转发

安装与启动步骤

1. 1检查硬件环境

   先确认显卡为 CUDA GPU 且显存≥16GB，架构 x86_64；系统用 Linux 或 Windows+WSL，Mac 与原生 Windows 均不支持。

2. 2克隆仓库

   把 unmute 源码拉到本地，仓库内同时包含 Docker Compose 与无 Docker 两套部署说明，按需选择。

   git clone https://github.com/kyutai-labs/unmute
   cd unmute

   复制

3. 3选择部署方式

   官方推荐 Docker Compose：单机一条命令启停全部服务、环境可复现；也可用 Dockerless 手动逐个启动服务。

4. 4安装 pre-commit 钩子

   无 Docker 方式需先装好 pre-commit 可执行文件，建议用 pip 全局安装而非虚拟环境，再在仓库里安装钩子。

   pip install pre-commit
   pre-commit install --hook-type pre-commit

   复制

5. 5启动后端服务

   用 uv 运行 FastAPI 后端主程序，开发模式自带自动重载；上线时把 dev 换成 run 走生产模式。

   uv run fastapi dev unmute/main_websocket.py

   复制

6. 6打开前端连接

   前端默认监听 3000 端口、后端 8000；Docker Compose 方案默认走 80 端口，浏览器打开后点 connect 建立 websocket。

7. 7远程访问做端口转发

   本机执行 SSH 隧道；Compose 只需转发 80，Dockerless 要分别转发后端 8000 和前端 3000。

   ssh -N -L 3333:localhost:80 unmute-box
   ssh -N -L 8000:localhost:8000 -L 3000:localhost:3000 unmute-box

   复制

8. 8运行负载测试

   用自带脚本模拟多路并发对话，测量延迟与吞吐；server-url 指向后端 websocket 地址即可。

   uv run unmute/loadtest/loadtest_client.py --server-url ws://localhost:8000 --n-workers 16

   复制

关键配置

如何确认成功

浏览器打开 localhost:3000（或端口转发后的 localhost:3333），点 connect 能建立 websocket 并正常语音对话；loadtest 脚本能持续输出延迟与吞吐数据。

常见问题

注意事项

• Docker Swarm 部署只用于展示官方如何部署和扩展 unmute.sh，多节点调试困难，官方不提供支持。
• 非 HTTPS 场景下必须做端口转发，因为浏览器只允许 localhost 使用麦克风。
• 官方建议用 uv 管理 Python 依赖，文档中的命令默认基于 uv。
• 服务数量较多，优先用 Docker Compose 以获得可复现环境并避免依赖问题。