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

语音智能体都能画成 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/…

— 以上为试看内容(约 40%),开通会员后阅读全文 —