huggingface/speech-to-speech
Build voice agents with open-source models
Speech‑to‑Speech (huggingface/speech-to-speech)
是什麼 – 一個開源、低延遲的管道，將語音輸入轉換為語音輸出，也就是一個 語音代理 堆疊。它串接四個階段——語音活動檢測（VAD）、語音轉文字（STT）、語言模型（LLM）和文字轉語音（TTS），並透過 OpenAI Realtime 協定（WebSocket / WebRTC）公開整個系統。每個階段都可以替換為不同的模型或服務提供者，因此你可以完全在本機運行，混合本機與託管元件，或讓 LLM 指向任何 OpenAI 相容服務（OpenAI、HF Inference Providers、vLLM、llama.cpp 等）。
核心理念
| 階段 | 預設後端 | 可替換為 |
|---|---|---|
| VAD | Silero VAD v5 | 任何能發出語音段檢測事件的 VAD（DeepFilterNet 為可選） |
| STT | Parakeet TDT（本機） | Whisper（transformers）、Faster‑Whisper、Lightning‑Whisper‑MLX、Paraformer、OpenAI /v1/audio/transcriptions 等 |
| LLM | OpenAI 相容 Responses API（預設模型 gpt‑5.6‑terra） |
直接 transformers 推理、Apple Silicon 上的 mlx‑lm、自架設的 vLLM/llama.cpp、任何 OpenAI 相容端點 |
| TTS | Qwen3‑TTS（Linux 上為 GGML，macOS 上為 mlx‑audio） | Kokoro‑82M、Pocket TTS、ChatTTS、OmniVoice、MMS‑TTS、OpenAI /v1/audio/speech 等 |
所有元件在獨立執行緒中運行並透過佇列通訊，保持管道的回應性，並便於插入新的後端。
快速開始（來自 README）
pip install speech-to-speech # Python 3.10+
export OPENAI_API_KEY=... # 用於預設 LLM 後端
speech-to-speech serve # 啟動一個相容 Realtime 的伺服器
# 在另一個終端
speech-to-speech talk --url ws://127.0.0.1:8765/v1/realtime
serve→ 運行 VAD‑STT‑LLM‑TTS 管道，並監聽ws://localhost:8765/v1/realtime。talk→ 一個內建的麥克風-喇叭客戶端，與該伺服器通訊。local→ 在同一行程中運行伺服器與客戶端（適合測試）。
你也可以透過 llama.cpp 將 LLM 指向自架設的 Gemma 4 模型：
llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full
speech-to-speech serve \
--model_name "ggml-org/gemma-4-E4B-it-GGUF" \
--responses_api_base_url "http://127.0.0.1:8080/v1" \
--responses_api_api_key ""
主要特性（如 README 所述）
- OpenAI Realtime 相容性 – 實作了 Realtime 事件集的核心子集，因此現有的 OpenAI Agents SDK 代碼可開箱即用。
- 完全模組化 – 每個階段可透過 CLI 標記（
--stt、--llm_backend、--tts）選擇。 - 以本機為優先預設 – STT 使用 Parakeet TDT，TTS 使用 Qwen3‑TTS，LLM 使用 OpenAI 相容 API，所有元件均可透過單一
pip install安裝。 - 跨平台 – 支援 Linux、macOS 和 Windows（透過平台特定的輪子）。macOS 使用
mlx‑audio進行 TTS；Linux 可使用 GGML 或 CUDA 加速的 Qwen3‑TTS。 - 可選擴充 – 擴充功能（
[kokoro]、[pocket]、[omnivoice]等）允許你引入替代的 TTS 或 STT 模型，而不會使基礎安裝臃腫。 - Docker 支援 –
docker compose up可啟動一個運行 Gemma 4 和 Realtime 伺服器的容器組合。 - LLM 代理 – 啟用
--enable_llm_proxy後，同一行程還會將配置的 LLM 作為普通 OpenAI 相容的/v1/chat/completions或/v1/responses端點公開，用於輔助任務。 - 工具呼叫支援 – 打包的客戶端可載入實作工具呼叫的 Python 模組，實現更豐富的互動（例如透過 Serper 進行網路搜尋）。
典型用例
- 機器人語音助手 – 用作數千台 Reachy Mini 機器人的對話後端。
- 桌面或嵌入式語音代理 – 完全在筆電或裝置硬體（Apple Silicon、CUDA GPU 或僅 CPU）上本機運行。
- 多模態代理原型設計 – 將語音管道與視覺模型（
mlx‑lm支援）或自訂工具模組結合使用。 - 低延遲語音互動研究 – 模組化設計允許你替換實驗性 STT/TTS 模型並測量端到端延遲。
限制 / 注意事項（來自 README）
- Realtime 實作僅涵蓋 核心 事件集；它 不是 OpenAI Realtime API 的完整替代品。
- 某些可選元件存在衝突（例如 DeepFilterNet 需要
numpy<2，而 Pocket TTS 需要numpy>=2）。你必須在互斥環境中安裝它們。 - CUDA 加速的 Qwen3‑TTS 輪子針對 CUDA 12.8 和較新的 glibc；舊的執行時需要從提供的 Hugging Face 輪子庫中取得匹配的輪子。
- 預設 LLM（
gpt‑5.6‑terra）透過 OpenAI Responses API 存取；除非替換為自架設模型，否則需要有效的 API 金鑰。 - 直接音訊輸入模式（將原始 VAD 音訊傳送給支援音訊的 LLM）僅在
chat-completions後端下運作，且需要明確支援音訊的模型。
安裝快照
pip install speech-to-speech # 核心
pip install "speech-to-speech[kokoro]" # 可選的 Kokoro-82M TTS
pip install "speech-to-speech[pocket]" # 可選的 Pocket TTS
# …依需求添加其他擴充
開發用：
git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
uv sync # 建立可編輯安裝
快速參考表（來自 README）
| 組件 | 後端（透過 CLI 選擇） | 平台備註 |
|---|---|---|
| VAD | Silero VAD v5（內建） | 到處可用 |
| STT | Parakeet TDT、Whisper、Faster-Whisper、Lightning-Whisper-MLX、Paraformer、OpenAI /v1/audio/transcriptions |
CUDA/CPU/Apple-Silicon 變體 |
| LLM | OpenAI 相容 Responses API、Chat-Completions API、transformers、mlx-lm |
可指向遠端提供者或本機 vLLM/llama.cpp |
| TTS | Qwen3-TTS（預設）、Kokoro-82M、Pocket TTS、ChatTTS、OmniVoice、MMS-TTS、OpenAI /v1/audio/speech |
Linux 上為 GGML/CUDA，macOS 上為 mlx-audio |
接下來該做什麼？
- 閱讀 Realtime Engine README 了解確切的事件矩陣以及如何與 OpenAI Agents SDK 集成。
- 探索 LLM 後端 部分，決定你是想要託管 API 還是完全本機模型。
- 如果想使用預設容器運行本地 LLM 伺服器和語音到語音管道，嘗試 Docker compose 設定。
- 如果需要語音代理呼叫外部服務（搜尋、資料庫查詢等），請查閱 工具呼叫文件。
總結 – speech-to-speech 是一個生產級、開源的語音代理框架，允許你構建端到端的語音助手，其 AI 元件可互換，全部透過 OpenAI 相容的 Realtime 介面實現。
相關
- 專案
- 專案
- 專案
- 專案
- 專案