项目简介

Speech To Speech 是一个低延迟、完全模块化的语音智能体流水线，采用 VAD → STT → LLM → TTS 的级联架构，并通过兼容 OpenAI Realtime 的 WebSocket API 对外提供服务。每个组件均可替换；LLM 槽位遵循 OpenAI 兼容协议，既可指向托管服务商、HF Inference Providers，也可指向本地 vLLM 或 llama.cpp 服务器，组成完全本地、完全开源的技术栈。该流水线已在生产环境中作为数千台 Reachy Mini 机器人的对话后端稳定运行。

快速开始

pip install speech-to-speech
export OPENAI_API_KEY=...
speech-to-speech serve

上述命令在 ws://localhost:8765/v1/realtime 启动一个兼容 OpenAI Realtime 的服务器，本地 STT 使用 Parakeet TDT，LLM 使用 OpenAI 兼容 API，TTS 使用 Qwen3-TTS。

在另一终端进行对话：

speech-to-speech talk --url ws://127.0.0.1:8765/v1/realtime

一键启动服务器并连接麦克风/扬声器客户端：

speech-to-speech local

流水线工作原理

四个组件各自运行在独立线程中，通过队列相连：

1. 语音活动检测（VAD）：基于 Silero VAD v5，识别语音边界与对话轮次切换。
2. 语音转文字（STT）：转写用户发言，可选实时输出部分转写结果。
3. 大语言模型（LLM）：生成回复，流式输出文本与工具调用。
4. 文字转语音（TTS）：合成音频并流式回传给客户端。

每个阶段都提供多个可互换的后端，通过 CLI 参数选择，代码以 Transformers 与 Hugging Face Hub 模型为优先。

安装

需要 Python 3.10+。默认安装包含：

• STT：Parakeet TDT
• LLM：OpenAI 兼容 API
• TTS：Qwen3-TTS（非 macOS 使用 GGML 后端，Apple Silicon 使用 mlx-audio）
• 本地音频与 Realtime 服务器模式

Qwen3-TTS 的 CUDA 说明

Linux 上 Qwen3-TTS 的 GGML 后端来自 faster-qwen3-tts[ggml]，其默认的 qwentts-cpp-python 轮子针对 CUDA 12.8。若运行环境不匹配，可先从 Hugging Face 轮子仓库安装对应版本（CUDA 13.x、CUDA 12.4 或 CPU-only），再安装 speech-to-speech。如需使用旧的 CUDA graphs 实现，可指定 --qwen3_tts_backend torch。

可选组件

通过 pip extras 安装：

pip install "speech-to-speech[kokoro]"          # Kokoro-82M TTS
pip install "speech-to-speech[pocket]"          # Pocket TTS
pip install "speech-to-speech[chattts]"         # ChatTTS
pip install "speech-to-speech[faster-whisper]"  # Faster Whisper STT
pip install "speech-to-speech[whisper-mlx]"     # macOS 上的 Lightning Whisper MLX
pip install "speech-to-speech[paraformer]"      # 基于 FunASR 的 Paraformer STT
pip install "speech-to-speech[mlx-lm]"          # macOS 上的 mlx-vlm 视觉模型

注意：DeepFilterNet 需要 numpy<2，与 Pocket TTS（需要 numpy>=2）冲突，请仅在不同时使用二者的环境中手动安装。

源码安装

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

支持的组件

组件	后端	平台	安装方式
VAD	Silero VAD v5	全平台	内置
STT	Parakeet TDT（默认）	CUDA/CPU/Apple Silicon	内置
STT	Whisper（Transformers）	CUDA/CPU	内置
STT	Faster Whisper	CUDA/CPU	faster-whisper
STT	Lightning Whisper MLX	Apple Silicon	whisper-mlx
STT	MLX Audio Whisper	Apple Silicon	macOS 内置
STT	Paraformer	CUDA/CPU	paraformer
LLM	OpenAI 兼容 API	托管或自托管	内置
LLM	Transformers	CUDA/CPU	内置
LLM	mlx-lm	Apple Silicon	macOS 内置
TTS	Qwen3-TTS（默认）	Linux GGML/CUDA，macOS mlx-audio	内置
TTS	Kokoro-82M	CUDA/CPU/Apple Silicon	kokoro 或 macOS 内置
TTS	Pocket TTS	CPU/CUDA	pocket
TTS	ChatTTS	CUDA/CPU	chattts
TTS	MMS TTS	CUDA/CPU	内置

通过 --stt、--llm_backend、--tts 选择具体实现。CLI 只为已选后端构造配置；非活跃后端的参数虽被接受但会被忽略并打印警告。

核心命令

命令	行为	适用场景
serve	启动基于 WebSocket/WebRTC 的 Realtime 服务器	构建应用或设备端
talk --url <url>	启动内置麦克风/扬声器客户端	连接已有 Realtime 服务器
local	组合 serve 与 talk 于同一进程	一键本地运行

serve 默认绑定 127.0.0.1；如需对外暴露请显式指定 --host 0.0.0.0。local 始终绑定回环地址。打包客户端可通过 --tool-module <module> 启用本地 Python 工具。

Realtime API

Realtime 模式支持 OpenAI Realtime 协议（WebSocket 与 WebRTC），提供实时转写与低延迟轮次切换。WebSocket 客户端连接 /v1/realtime：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8765/v1",
    websocket_base_url="ws://localhost:8765/v1",
    api_key="not-needed",
)

with client.realtime.connect(model="local") as conn:
    conn.send({
        "type": "session.update",
        "session": {
            "type": "realtime",
            "instructions": "You are a helpful assistant.",
            "audio": {"input": {"turn_detection": {
                "type": "server_vad",
                "interrupt_response": True,
            }}},
        },
    })
    for event in conn:
        print(event.type)

服务器实现了核心 Realtime 事件集：入站支持 input_audio_buffer.append、session.update、conversation.item.create、response.create、response.cancel；出站包含语音起止、流式转写、音频增量、工具调用与 response.done。

LLM 代理

启用 --enable_llm_proxy 后，Realtime 服务器将配置的远程 LLM 同时暴露为标准 OpenAI 兼容端点，便于客户端在语音对话之外并发执行摘要、标题、后台智能体等任务，永不被新发言打断：

• --llm_backend chat-completions 时暴露 POST /v1/chat/completions
• --llm_backend responses-api 时暴露 POST /v1/responses

服务器不自带鉴权与限流，请仅在受信网络启用，或部署在具备访问控制的网关之后。请求无状态（每次发送完整消息列表），model 字段始终被覆写为服务器配置的 --model_name。

LLM 后端

LLM 是流水线中计算最密集、延迟最高的组件。可选后端包括：

• 本地推理：CUDA/CPU 上的 transformers；Apple Silicon 上的 mlx-lm。
• 自托管服务器：responses-api 与 chat-completions 可指向本地 vLLM 或 llama.cpp 服务器。
• 服务商 API：同一后端兼容 OpenAI、HF Inference Providers、OpenRouter 等。

两种 API 后端共享 --responses_api_* 连接参数：

• --llm_backend responses-api（默认）指向 /v1/responses
• --llm_backend chat-completions 指向 /v1/chat/completions

直接音频输入（跳过 STT）

使用 --stt none --llm_backend chat-completions 可将每个完成的 VAD 音频段直接发送给支持音频输入的模型。responses-api 后端不支持该模式。需显式设置 --model_name 为支持音频的模型（如 gpt-audio-1.5）。可用 --responses_api_audio_content_type 在 input_audio（嵌入 WAV base64）与 audio_url（base64 data URL）之间切换。

Responses API 后端示例

```bash

OpenAI

speech-to-speech local --stt parakeet-tdt --llm_backend responses-api \ --tts qwen3 --qwen3_tts_m