开源模型

speech-to-speech：用开源模型搭建低延迟实时语音智能体，读懂安装部署、架构原理、插话打断与性能调优

2026 年 8 月 25 日

Hugging Face 开源的 speech-to-speech 是 Apache-2.0 协议、Python 3.10+ 的低延迟级联语音智能体框架，支持 VAD→STT→LLM→TTS 四级流水线，具备插话即停、停顿续说、多模型热替换、WebRTC/WS 双协议及工具调用能力。文章详解其六线程处理链、四种运行模式、三套高效配置（全本地/Apple Silicon/中文优先）、核心打断与短停顿机制，并指出上线前需注意的元数据 Alpha 状态、网络与安全边界。

语音智能体都能画成 VAD→STT→LLM→TTS，难的是插话即停、停顿后续说，以及把本地/云端模型、WebSocket、WebRTC 和工具调用装进同一套可替换架构。

Hugging Face 的 speech-to-speech 是 Apache-2.0、Python 3.10+ 的低延迟级联框架。

项目四级级联架构

speech-to-speech 四级级联架构示意图 — speech-to-speech 四级级联架构

一、功能简介

核心是六线程处理链：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/本地音频：

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：

pip 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：

git clone https://github.com/huggingface/speech-to-speech.git
cd speech-to-speech
uv sync
uv run speech-to-speech

开发验证使用：

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，便于复用、扩缩和升级。

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 播放缓冲，旧尾音追不上新响应。

打断与代际取消时序

speech-to-speech：用开源模型搭建低延迟实时语音智能体，读懂安装部署、架构原理、插话打断与性能调优配图 3

短停顿不是句号。 VAD 为每轮分配 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。

最有价值的不是默认模型，而是把并发、插话、流式输出、工具回路和运行时配置做成可读、可换的工程结构——比“串起四个模型”更接近上线起点。

JOTO 企业落地观察

该框架将 VAD/STT/LLM/TTS 显式解耦为可替换模块，为企业构建语音智能体提供了清晰的「模型治理层」接口，降低因单点模型迭代导致的系统重构成本。
其基于代际（generation）的打断机制与 SpeculativeTurnTracker 设计，表明实时语音交互中「状态一致性」必须由框架层保障，而非依赖 LLM 自身响应逻辑——这对企业设计高可靠客服/会议助手类系统具有直接工程参考价值。
CLI 支持 raw-websocket 和 socket 两种裸协议模式，意味着企业可在已有通信中间件（如 Kafka、gRPC 网关）之上复用语音处理能力，避免将 AI 能力强耦合于特定前端协议栈。
所有模型加载、配置更新、工具注册均通过运行时 RuntimeConfig 注入，未硬编码路径或参数，符合企业对「灰度发布」「A/B 测试」「多租户模型隔离」等生产运维场景的基础要求。