语音智能体都能画成 VAD→STT→LLM→TTS，难的是插话即停、停顿后续说，以及把本地/云端模型、WebSocket、WebRTC 和工具调用装进同一套可替换架构。
Hugging Face 的 speech-to-speech 是 Apache-2.0、Python 3.10+ 的低延迟级联框架。
项目四级级联架构
一、功能简介
核心是六线程处理链：VAD → STT → TranscriptionNotifier → LLM → LMOutputProcessor → TTS，类型化队列连接各阶段，模型槽位可替换。
VAD： Silero VAD v5；支持动态阈值、语音/静音时长、补边、短段合并、可选 DeepFilterNet、增量放音和“软结束重开”。默认阈值 0.6，最短语音/续说/静音为 384/192/64ms。
STT： 默认 Parakeet TDT（25 种欧洲语言；非 macOS 用 nano-parakeet，Mac 用 MLX），另有 Transformers/MLX Whisper；可选 Faster-Whisper、Lightning Whisper MLX、FunASR Paraformer。支持增量转写、固定语言或逐句检测；Paraformer 默认偏中文。
LLM： 可在本地使用 Transformers/MLX-LM，也可把 responses-api、chat-completions 指向 OpenAI、HF Providers、OpenRouter、vLLM 或 llama.cpp。支持流式/非流式、图像/VLM、会话窗口与后台压缩、语言提示、文本/音频模态、工具调用、逐响应 instructions/tool_choice 和 token 统计。
TTS： 默认 Qwen3-TTS：Linux/Windows 用 faster-qwen3-tts 的 GGML/torch，Mac 用 mlx-audio 的 bf16/4/6/8bit；支持预设音色、克隆和 VoiceDesign。另有 Kokoro、Pocket（8 个预设及自定义声线）、ChatTTS、MMS；Melo、Parler、Moonshine 已归档并退出 CLI。
四种模式：realtime 提供 OpenAI Realtime；local 直连麦克风/扬声器；raw-websocket 收发 16kHz int16 单声道 PCM；socket 以双 TCP 端口分离收放。TCP 不含完整打断、字幕和工具事件。
Realtime：/v1/realtime 走 WebSocket；webrtc extra 增加 /v1/realtime/calls。覆盖音频追加/提交、会话更新、上下文注入、生成/取消，以及语音起止、增量/最终字幕、音频、文本、工具、完成事件。--num_pipelines 建并发池；/v1/usage、/v1/pool 看用量及 idle/active/draining/stuck。
浏览器 Demo： 含声波 Orb、WS/WebRTC、设备/音色/指令、问候、历史字幕、插话清音、HF OAuth、Space 限时与负载均衡；工具有服务端代理搜索和摄像头快照，密钥不进浏览器。
二、最快跑起来、源码安装
默认安装含 Parakeet、OpenAI 兼容 LLM、Qwen3-TTS 与 Realtime/本地音频：
●●●bash pip install speech-to-speech
export OPENAI_API_KEY=...
speech-to-speech
首次运行下载模型。非 macOS 的 Qwen3 GGML wheel 默认面向 CUDA 12.8；12.4、13.x 或 CPU 机器须先装 README 指定的匹配 wheel。可选后端用 extra：
●●●bashpip install "speech-to-speech[webrtc,kokoro,faster-whisper]"
Pocket、ChatTTS、MMS、Paraformer、whisper-mlx、mlx-lm 也有 extra。DeepFilterNet 要求 numpy，Pocket 要求 numpy>=2，勿共用环境。
源码安装推荐 uv；uv sync 会 editable 安装并生成 CLI：
●●●bash git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
uv sync
uv run speech-to-speech
开发验证使用：
●●●bash uv run pytest
uv run ruff check
GPU 服务器可在 NVIDIA Container Toolkit 上运行 docker compose up，同时启动 CUDA llama.cpp/Gemma 4 与 socket 管线，开放 8080、12345、12346。
三、三套高效配置
1. 全本地： 让 llama.cpp 独立承载 LLM，语音循环只做 VAD/STT/TTS，便于复用、扩缩和升级。
●●●bash llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full
speech-to-speech --responses_api_base_url http://127.0.0.1:8080/v1 \
--responses_api_api_key "" --responses_api_stream
2. Apple Silicon： 加 --local_mac_optimal_settings，自动选 MPS、Parakeet、MLX-LM、Qwen3 6bit 并切 local。MLX 有全局锁；多管线会关闭增量转写以免争锁，最终转写不受影响。
3. 中文优先： STT 换 MLX Whisper/Whisper 或 Paraformer，设 zh；TTS 用 Qwen3 auto。自动语种可加 --enable_lang_prompt。
部署与运行模式
调延迟先看三处：VAD min_silence_ms 决定交棒，LLM stream_batch_sentences 决定文本批次，TTS chunk 决定首音频。过小会切句或增加调度。长对话开 compact_history；字幕用 --enable_live_transcription。Qwen3 统一输出 16kHz、512 样本块。
四、源码里最值得学的三种机制
打断不是清空队列。 响应捕获 CancelScope.generation；插话或 response.cancel 使代际自增，LLM/TTS 每个流片检查过期。发送循环丢旧文本/音频、保留结束哨兵，并清 WebRTC 播放缓冲，旧尾音追不上新响应。
打断与代际取消时序
短停顿不是句号。 AD 为每轮分配 turn_id + revision；重开后 revision 递增，SpeculativeTurnTracker 在 STT/LLM/TTS 丢弃旧版，已提交轮次不可重开。100ms 噪声底线、短段拼接和 384/192ms 双门槛平衡“快交棒”与“不抢答”。
配置是运行时数据。session.update 仅深合并显式字段，VAD/LLM/TTS 处理时读取 RuntimeConfig，逐响应参数优先。远程工具走结构化 tools；本地模型把 JSON Schema 转函数签名并以 AST 校验。工具结果写回后不会自动生成，需按场景补 response.create。
每个并发槽独享队列、Chat、CancelScope 和处理器。断开后 SESSION_END 必须穿过全链才复用；超时槽被隔离并标为 stuck，阻止迟到输出泄漏给下一位。
五、上线前须知道的边界
• 元数据仍为 Alpha；语言、速度、显存、音质取决于模型组合。
• WebRTC 跨公网常需 STUN/TURN；麦克风要求 HTTPS/localhost；负载均衡 Demo 仅 WS。
• LLM proxy 暴露 Responses/Chat 端点且不鉴权限流，只能置于可信网或网关后。
• raw WS/TCP 是裸 PCM；生产端要自行处理采样率、背压、重连和播放缓冲。
• 归档模型依赖已移出默认安装，不能视为受支持 CLI。
最有价值的不是默认模型，而是把并发、插话、流式输出、工具回路和运行时配置做成可读、可换的工程结构——比“串起四个模型”更接近上线起点。
#speech-to-speech #语音智能体 #开源AI #本地部署 #实时语音
—— 如此才是
把复杂的技术，讲成你真正能用上的生产力
