huggingface/speech-to-speech
Build local voice agents with open-source models
這是什麼
huggingface/speech-to-speech 是一套用開源模型組成的低延遲語音代理管線，目標是把「聽見人聲、理解內容、生成回答、再唸出來」串成可替換、可自架的完整後端。README 把它拆成四段：VAD → STT → LLM → TTS；Silero VAD 負責偵測說話邊界，STT 轉錄使用者語音，LLM 串流產生文字與工具呼叫，TTS 再把回覆轉成音訊。比較關鍵的是，它不是只提供一個 demo，而是對外暴露 OpenAI Realtime-compatible WebSocket API，任何相容 Realtime API 的 client 都能把端點從 hosted OpenAI 換到這個本機或自架 server。LLM 欄位也走 OpenAI-compatible 協定，可接 OpenAI、HF Inference Providers、OpenRouter，也可指向 vLLM 或 llama.cpp。
為什麼上榜
這個專案今日拿到 628 stars_period、總星數 8758，熱點很明確：語音代理正在從「雲端 API 展示」走向「可控、可替換、可落地的本地堆疊」。README 特別強調每個元件都能透過 CLI flags 替換，且同一套 server 可用標準 Realtime client 連線，降低了從既有 OpenAI Realtime 應用遷移的成本。另一個亮點是它已被用作數千台 Reachy Mini 機器人的對話後端；這不是效能保證，但說明它的設計不是純玩具。爭點則在部署複雜度：STT、LLM、TTS 都牽涉不同硬體、CUDA 或 Apple Silicon 後端，README 也花不少篇幅處理 Qwen3-TTS wheel 與 optional backends。
適合誰，可以拿來做什麼
它最適合正在做語音助理、機器人、互動裝置、客服或本地 AI 工具的開發者，尤其是希望保留 OpenAI Realtime client 介面、但想把部分或全部模型換成自架方案的人。若你只想快速做文字聊天機器人，這套會太重；但如果你在意語音端到端流程、live transcription、turn-taking、audio streaming、工具呼叫事件，README 顯示它已把這些常見工程問題整理成可啟動的 server。上手門檻中等偏高：Python 3.10+ 與 pip 安裝本身簡單，但要達到理想延遲，仍需要理解本機音訊、GPU/CPU、LLM provider 或自架 server 的取捨。
上手
README 提供了明確 quickstart。預設會啟動 ws://localhost:8765/v1/realtime，使用 Parakeet TDT 做本地 STT、OpenAI-compatible LLM，以及 Qwen3-TTS 做本地語音輸出。
pip install speech-to-speech
export OPENAI_API_KEY=...
speech-to-speech
若從原始碼 checkout，可在第二個 terminal 用範例 client 測試：
python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765
想把 LLM 放在自己機器上，README 示範用 llama.cpp 跑 Gemma 4，再把 speech-to-speech 的 OpenAI-compatible LLM backend 指向 http://127.0.0.1:8080/v1。Linux 使用 Qwen3-TTS 時要留意 README 的 CUDA 12.8 / 13.x / 12.4 / CPU-only wheel 說明。
README 重點摘要
- 架構採 VAD、STT、LLM、TTS 四段 cascade，各自跑在 thread 中並用 queues 串接，重點是可替換而不是綁死單一模型。
- 預設安裝涵蓋 realtime 路徑：Parakeet TDT、OpenAI-compatible LLM、Qwen3-TTS、本地音訊與 realtime server；macOS / non-macOS 依 platform markers 處理依賴。
- 支援多種 STT / TTS 後端，例如 Whisper、Faster Whisper、Lightning Whisper MLX、Paraformer、Kokoro、Pocket TTS、ChatTTS、MMS TTS。
- Run modes 包含 realtime、local、websocket、socket；realtime 是標準 WebSocket API，socket / websocket 則偏向自訂或遠端模型串流情境。
- README 明確提醒 LLM 是最吃算力與延遲的環節，可用 transformers、mlx-lm、vLLM、llama.cpp 或 provider APIs，需依硬體與延遲預算選擇。