解除静音

快来 Unmute.sh 体验吧！

Unmute 是一个系统，它通过将文本型大语言模型（LLM）与 Kyutai 的语音合成（TTS）和语音识别（STT）模型相结合，使 LLM 具备“听”和“说”的能力。语音识别会将用户的语音转录为文本，LLM 生成回复文本，然后语音合成就会将这些文本朗读出来。语音识别和语音合成都针对低延迟进行了优化，该系统可以与任何你喜欢的文本型 LLM 配合使用。

如果你想单独使用 Kyutai 的 STT 或 TTS，可以查看 kyutai-labs/delayed-streams-modeling。关于这些模型的预印本可以在 这里 获取。

从高层次来看，其工作流程如下：

graph LR
    UB[用户浏览器]
    UB --> B(后端)
    UB --> F(前端)
    B --> STT(语音识别)
    B --> LLM(LLM)
    B --> TTS(语音合成)

• 用户打开由 前端 提供服务的 Unmute 网站。
• 点击“连接”后，用户会建立一个 WebSocket 连接至 后端，实时传输音频及其他元数据。
  • 后端通过 WebSocket 连接到 语音识别 服务器，将用户的音频发送过去，并实时接收转录结果。
  • 当语音识别检测到用户停止说话并准备生成回复时，后端会连接到 LLM 服务器以获取响应。我们使用 OpenRouter 来部署 LLM，但你也可以使用 VLLM 自行托管。
  • 在生成回复的过程中，后端会将回复内容传递给 语音合成 服务器进行朗读，并将合成后的语音流返回给用户。

设置

[!NOTE]
如果遇到问题，请随时提交 Issue，我们会尽力帮助你解决问题。

要求：

• 硬件：支持 CUDA 的 GPU，显存至少 16 GB。架构必须是 x86_64，暂不支持 aarch64。
• 操作系统：Linux，或带有 WSL 的 Windows（安装说明）。不支持在原生 Windows 上运行（参见 #84），也不支持在 Mac 上运行（参见 #74）。

我们提供了多种方式来部署你自己的 unmute.sh：

名称	GPU 数量	机器数量	难度	文档是否完善	Kyutai 支持
Docker Compose	1+	1	非常简单	✅	✅
无 Docker	1–3	1–5	容易	✅	✅
Docker Swarm	1–~100	1–~100	中等难度	✅	❌

由于 Unmute 是一个复杂的系统，包含多个需要同时运行的服务，我们建议使用 Docker Compose 来运行 Unmute。它允许你通过一条命令启动或停止所有服务。由于这些服务都是 Docker 容器，你可以获得一个可重复的环境，而无需担心依赖关系。

虽然我们也支持使用 Docker Compose 和无 Docker 的部署方式，但 Docker Swarm 部署仅用于展示我们如何部署和扩展 unmute.sh。它的配置文件与 Compose 类似，但由于多节点应用的调试较为困难，我们无法提供 Swarm 部署的调试支持。

Hugging Face Hub 上的 LLM 访问权限

你可以使用任何你想要的 LLM。在生产环境中，我们使用通过 OpenRouter 提供服务的 GPT OSS 120B。而在默认的本地设置中（Docker Compose/无 Docker），Unmute 使用 Gemma 3 1B 作为 LLM。

该模型可免费使用，但你需要先接受相关条款：

1. 创建一个 Hugging Face 账号。
2. 接受 Mistral Small 3.2 24B 模型页面上的使用条款。
3. 创建访问令牌。 你可以使用细粒度令牌，只需授予“读取你可访问的所有公开 gated repo 内容”的权限即可。 请勿在公开部署时使用具有写入权限的令牌。 如果服务器遭到入侵，攻击者将获得对你在 Hugging Face 上所有模型、数据集等的写入权限。
4. 将令牌添加到你的 ~/.bashrc 或等效文件中，格式为 export HUGGING_FACE_HUB_TOKEN=hf_...你的令牌..."。

启动 Unmute

请确保已安装 Docker Compose。此外，还需要安装 NVIDIA Container Toolkit，以便 Docker 能够访问你的 GPU。要验证 NVIDIA Container Toolkit 是否正确安装，请运行以下命令：

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

如果你使用的是 google/gemma-3-1b-it，这是 docker-compose.yml 中的默认配置，那么 16 GB 的显存就足够了。如果遇到内存不足的问题，可以打开 docker-compose.yml，查找带有 NOTE: 标记的注释，看看哪些地方可能需要调整。

在配备 GPU 的机器上，运行以下命令：

# 确保已设置包含令牌的环境变量：
echo $HUGGING_FACE_HUB_TOKEN  # 应该输出 hf_...一些内容...

docker compose up --build

使用多 GPU

在 Unmute.sh 上，我们将语音识别、语音合成以及 VLLM 服务器分别部署在不同的 GPU 上，这样可以显著降低延迟，相比单 GPU 配置效果更好。例如，当所有服务都在一台 L40S GPU 上运行时，TTS 延迟约为 750 毫秒；而在 Unmute.sh 上，这一延迟降至约 450 毫秒。

如果你有至少三块 GPU，可以在 stt、tts 和 llm 服务的配置中添加以下片段，以确保它们分别运行在不同的 GPU 上：

  stt: # `tts` 和 `llm` 同理
    # ...其他配置
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

不使用 Docker 运行

或者，你也可以选择不通过 Docker，而是手动启动各个服务来运行 Unmute。 由于需要处理多种依赖关系，这种方式的设置可能会更加复杂。

以下说明仅适用于 Linux 和 WSL 环境。

软件要求

• uv：使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装
• cargo：使用 curl https://sh.rustup.rs -sSf | sh 安装
• pnpm：使用 curl -fsSL https://get.pnpm.io/install.sh | sh - 安装
• cuda 12.1：可通过 conda 或直接从 Nvidia 官网安装。Rust 进程（tts 和 stt）需要此工具。

硬件要求

在不同的 tmux 会话或终端中依次启动每个服务：

./dockerless/start_frontend.sh
./dockerless/start_backend.sh
./dockerless/start_llm.sh        # 需要 6.1GB 显存
./dockerless/start_stt.sh        # 需要 2.5GB 显存
./dockerless/start_tts.sh        # 需要 5.3GB 显存

之后，网站应可在 http://localhost:3000 访问。

连接到运行 Unmute 的远程服务器

如果你在一台通过 SSH 访问的机器上运行 Unmute——假设这台机器名为 unmute-box——并且希望从本地计算机访问它， 你需要设置 端口转发。

[!注意] 如果你使用的是 HTTP 而不是 HTTPS，即使可以直接访问 http://unmute-box:3000，仍然需要进行端口转发。 这是因为出于安全考虑，浏览器通常不允许在非本地的 HTTP 连接上使用麦克风。 HTTPS 的相关说明请见下文。

对于 Docker Compose：默认情况下，我们的 Docker Compose 设置运行在端口 80 上。 要将远程服务器的 80 端口转发到本地的 3333 端口，请使用：

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

如果一切正常，该命令不会输出任何内容，只会持续运行。然后在浏览器中打开 localhost:3333。

对于 Dockerless：你需要分别转发后端（8000 端口）和前端（3000 端口）：

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

flowchart LR
    subgraph Local_Machine [本地机器]
        direction TB
        browser[浏览器]
        browser -. "用户在浏览器中打开 localhost:3000" .-> local_frontend[localhost:3000]
        browser -. "前端向 localhost:8000 发起 API 请求" .-> local_backend[localhost:8000]
    end
    subgraph Remote_Server [远程服务器]
        direction TB
        remote_backend[后端:8000]
        remote_frontend[前端:3000]
    end
    local_backend -- "SSH 隧道: 8000" --> remote_backend
    local_frontend -- "SSH 隧道: 3000" --> remote_frontend

HTTPS 支持

为简化起见，我们在 Docker Compose 和 Dockerless 的设置中未包含 HTTPS 支持。 如果你想让部署通过 HTTPS 工作，可以考虑使用 Docker Swarm (参见 SWARM.md)，或者询问你喜欢的 LLM 如何使 Docker Compose 或 Dockerless 设置支持 HTTPS。

使用 Docker Swarm 的生产部署

如果你想知道我们是如何部署和扩展 unmute.sh 的，请查看我们的文档中关于 Docker Swarm 部署的部分。

修改 Unmute

以下是一些关于如何对 Unmute 进行特定修改的高层次指导。

字幕与开发模式

按下 “S” 键可为用户和聊天机器人同时开启字幕。

此外，还有一个开发模式可以帮助调试，但默认是禁用的。打开 useKeyboardShortcuts.ts 文件，将 ALLOW_DEV_MODE 改为 true。 然后按下 “D” 键即可查看调试界面。你可以通过修改 unmute_handler.py 中的 self.debug_dict 来添加更多调试信息。

更改角色/声音

角色的声音和提示语定义在 voices.yaml 文件中。 配置文件的格式应该比较直观。某些系统提示语包含动态生成的内容。 例如，“知识竞赛”中的 5 道题目是从一个固定列表中随机提前选出的。 类似这样的系统提示语定义在 unmute/llm/system_prompt.py 文件中。

请注意，该文件仅在后端启动时加载并被缓存，因此如果你更改了 voices.yaml 中的内容， 就需要重新启动后端。

你可以在我们的 语音仓库 中查看可用的语音。 要使用其中一种语音，只需将 voices.yaml 中的 path_on_server 字段更改为所需语音的相对路径， 例如 voice-donations/Haku.wav。

从 2025 年 6 月至 2026 年 2 月，我们还开展了 Unmute 语音捐赠项目， 志愿者们提供了自己的声音，用于 Kyutai TTS 1.6B（Unmute 使用）及其他开源 TTS 模型。 这些语音同样可以在 语音仓库 中找到。

使用外部 LLM 服务器

Unmute 后端可以与任何兼容 OpenAI 的 LLM 服务器一起使用。默认情况下，docker-compose.yml 配置 VLLM，以实现完全自包含的本地部署。 你可以修改此文件，切换到其他外部 LLM，比如 OpenAI 服务器、本地 Ollama 部署等。

以 Ollama 为例，将 unmute-backend 镜像的环境变量部分中的

  backend:
    image: unmute-backend:latest
    [..]
    environment:
      [..]
       - KYUTAI_LLM_URL=http://llm:8000

替换为：

  backend:
    image: unmute-backend:latest
    [..]
    environment:
      [..]
      - KYUTAI_LLM_URL=http://host.docker.internal:11434
      - KYUTAI_LLM_MODEL=gemma3
      - KYUTAI_LLM_API_KEY=ollama
    extra_hosts:
      - "host.docker.internal:host-gateway"

这样就指向了你的本地服务器。或者，如果你想使用兼容 OpenAI 的服务器，比如 OpenRouter，可以这样配置：

  backend:
    image: unmute-backend:latest
    [..]
    environment:
      [..]
      - KYUTAI_LLM_URL=https://openrouter.ai/api
      - KYUTAI_LLM_MODEL=google/gemma-3-12b-it # 或其他型号
      - KYUTAI_LLM_API_KEY=sk-.. # 你的 OpenRouter 密钥

随后可以移除 vllm 相关的部分，因为不再需要：

  llm:
    image: vllm/vllm-openai:v0.11.0
    [..]

切换前端

后端和前端通过 WebSocket 按照基于 OpenAI 实时 API（简称 ORA）的协议进行通信。在可能的情况下，我们尽量与 ORA 格式保持一致，但也有一些额外的消息需要添加，而另一些消息则简化了参数。我们会明确指出与 ORA 格式的差异，请参阅 unmute/openai_realtime_api_events.py。

有关 WebSocket 通信协议、消息类型以及音频处理流程的详细信息，请参阅 浏览器与后端通信文档。

理想情况下，编写一个能够同时与 Unmute 后端或 OpenAI 实时 API 通信的单一前端应该很简单，但目前我们尚未完全兼容。欢迎贡献代码！

前端是一个 Next.js 应用，定义在 frontend/ 目录中。如果您想将其与其他前端实现进行比较，我们还提供了一个 Python 客户端，位于 unmute/loadtest/loadtest_client.py，该脚本用于基准测试 Unmute 的延迟和吞吐量。

工具调用

这是一个常见的需求，因此我们非常欢迎有人为 Unmute 添加对工具调用的支持！

将工具调用集成到 Unmute 中最简单的方式，是让这一功能对 Unmute 本身完全透明——只需将其作为 LLM 服务器的一部分即可。关于如何实现这一点，请参阅 此评论。您需要使用 FastAPI 编写一个简单的服务器来封装 vLLM，并接入工具调用的响应。

开发 Unmute

安装 pre-commit 钩子

首先安装 pre-commit 工具本身——建议您使用 pip install pre-commit 将其全局安装，而不是在虚拟环境或 uv 中安装，因为您需要始终能够访问 pre-commit 可执行文件。然后运行以下命令：

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

我们推荐使用 uv 来管理 Python 依赖。以下命令假设您正在使用 uv。

运行后端（开发模式，自动重载）

uv run fastapi dev unmute/main_websocket.py

运行后端（生产模式）

uv run fastapi run unmute/main_websocket.py

运行负载测试

loadtest_client.py 是一个脚本，它会连接到 Unmute 并模拟与之的对话，以测量延迟和吞吐量。

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

Unmute 快速上手指南

Unmute 是一个开源系统，通过集成 Kyutai 的语音转文本（STT）和文本转语音（TTS）模型，让纯文本大语言模型（LLM）具备“听”和“说”的能力。它支持低延迟实时对话，并兼容任意文本 LLM。

环境准备

系统要求

• 操作系统：Linux 或 Windows (需使用 WSL2)。不支持原生 Windows 或 macOS。
• 硬件架构：x86_64 (暂不支持 aarch64)。
• GPU 要求：支持 CUDA 的 NVIDIA 显卡，显存至少 16 GB。
  • 若使用默认模型 Gemma 3 1B，16GB 显存即可。
  • 若需多 GPU 部署以降低延迟，建议拥有 3 张及以上 GPU。

前置依赖

推荐使用 Docker Compose 方式部署，需安装以下工具：

1. Docker Compose
2. NVIDIA Container Toolkit (用于让 Docker 访问 GPU)

验证 NVIDIA Toolkit 是否安装成功：

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

若命令成功输出 GPU 信息，则环境就绪。

Hugging Face 访问配置

Unmute 默认使用 Hugging Face 上的模型（如 google/gemma-3-1b-it）。

1. 注册 Hugging Face 账号。
2. 在模型页面接受使用条款（例如 Mistral Small 3.2 或 Gemma 系列）。
3. 创建 Access Token：
   • 权限仅需勾选：Read access to contents of all public gated repos you can access。
   • 警告：切勿使用具有写入权限的 Token，以防服务器被攻破后泄露数据。
4. 将 Token 添加到环境变量（以 .bashrc 为例）：

export HUGGING_FACE_HUB_TOKEN=hf_...your_token_here...
source ~/.bashrc

国内加速提示：若下载模型缓慢，可配置 Hugging Face 镜像源：

export HF_ENDPOINT=https://hf-mirror.com

安装步骤

方法一：使用 Docker Compose（推荐）

这是最简单且可复现的部署方式，一键启动所有服务。

1. 克隆项目代码（假设已获取源码）。
2. 确认环境变量已设置：

echo $HUGGING_FACE_HUB_TOKEN
# 应输出 hf_ 开头的字符串

3. 启动服务：

docker compose up --build

启动完成后，服务通常运行在 http://localhost:80。

方法二：无 Docker 部署（仅限高级用户）

若不使用 Docker，需手动安装依赖并在不同终端启动各服务。 软件依赖：uv, cargo, pnpm, cuda 12.1。

依次在独立的 tmux 会话或终端中运行：

./dockerless/start_frontend.sh
./dockerless/start_backend.sh
./dockerless/start_llm.sh        # 需 6.1GB 显存
./dockerless/start_stt.sh        # 需 2.5GB 显存
./dockerless/start_tts.sh        # 需 5.3GB 显存

启动后访问 http://localhost:3000。

基本使用

本地访问

启动成功后，在浏览器打开：

• Docker Compose 模式：http://localhost (或 http://localhost:80)
• 无 Docker 模式：http://localhost:3000

点击页面上的 "Connect" 按钮，建立 WebSocket 连接。允许浏览器使用麦克风权限，即可开始语音对话。

远程访问（SSH 端口转发）

若 Unmute 运行在远程服务器（例如通过 SSH 连接的 unmute-box），由于浏览器安全策略限制，HTTP 协议下非 localhost 无法调用麦克风，必须配置端口转发。

Docker Compose 模式（默认端口 80）： 在本地机器执行：

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

然后在本地浏览器访问 http://localhost:3333。

无 Docker 模式： 需分别转发前端（3000）和后端（8000）：

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

然后在本地浏览器访问 http://localhost:3000。

进阶功能

• 开启字幕：在对话界面按键盘 S 键，可显示用户和机器人的实时字幕。
• 开发者模式：修改前端代码 useKeyboardShortcuts.ts 中的 ALLOW_DEV_MODE 为 true，重启后按 D 键查看调试信息。
• 更换声音/角色：编辑 voices.yaml 文件，修改 path_on_server 指向 Kyutai 声音仓库 中的其他音色文件，修改后需重启后端服务。
• 接入外部 LLM：修改 docker-compose.yml 中的 KYUTAI_LLM_URL 环境变量，即可对接 OpenAI、Ollama 或其他兼容接口。