## 项目概述

speech-to-speech 是 Hugging Face 推出的开源语音智能体构建框架，旨在通过开源模型快速搭建本地语音助手。它提供了一个低延迟、模块化的语音处理流水线：语音活动检测（VAD）→ 语音转文本（STT）→ 大语言模型（LLM）→ 文本转语音（TTS），并通过 OpenAI Realtime 兼容的 WebSocket API 对外提供服务。该项目已在生产环境中作为数千台 Reachy Mini 机器人的对话后端运行。

## 核心功能

- **模块化流水线**：VAD、STT、LLM、TTS 四个组件均可独立替换，支持多种后端实现。
- **OpenAI Realtime 兼容**：提供与 OpenAI Realtime 协议兼容的 WebSocket 和 WebRTC 接口，方便集成现有客户端。
- **多后端支持**：STT 支持 Parakeet TDT、Whisper、Faster Whisper、Paraformer 等；TTS 支持 Qwen3-TTS、Kokoro、Pocket TTS、ChatTTS 等；LLM 支持 OpenAI 兼容 API、Transformers、mlx-lm 等。
- **完全本地运行**：支持通过 llama.cpp、vLLM 等自托管 LLM 服务器实现全本地部署，无需联网。
- **多语言支持**：根据所选 STT/TTS 后端，支持多种语言，包括自动语言检测和切换。
- **低延迟交互**：支持实时转录、打断（barge-in）、Smart Turn 端点检测等特性，优化对话体验。
- **LLM 代理**：可选的 LLM 代理功能，允许客户端在语音对话的同时执行后台任务。

## 适用与不适用场景

**适用场景：**

- 构建语音助手、语音交互应用或智能设备。
- 需要低延迟、可定制的语音对话流水线。
- 希望使用开源模型实现本地化、隐私保护的语音处理。
- 需要与 OpenAI Realtime 客户端兼容的语音服务。

**不适用场景：**

- 需要图形界面或完整语音应用框架的场景（本项目仅提供核心流水线和 CLI）。
- 对语音识别或合成质量有极高要求，且不愿自行调优模型和参数。
- 需要多轮复杂对话管理或长期记忆功能（需自行扩展）。

## 技术架构与依赖

- **语言**：Python 3.10+。
- **架构**：四阶段流水线（VAD→STT→LLM→TTS），每个组件运行在独立线程，通过队列连接。
- **主要依赖**：
  - VAD：Silero VAD v5。
  - STT：Parakeet TDT（默认）、Whisper、Faster Whisper、Paraformer 等。
  - LLM：OpenAI 兼容 API、Transformers、mlx-lm。
  - TTS：Qwen3-TTS（默认）、Kokoro、Pocket TTS、ChatTTS 等。
- **可选依赖**：通过 pip extras 安装，如 `[kokoro]`、`[pocket]`、`[faster-whisper]` 等。
- **平台支持**：Linux、macOS（Apple Silicon）、Windows（部分功能）。

## 安装与快速开始

**安装：**

```bash
pip install speech-to-speech
```

**快速开始：**

```bash
export OPENAI_API_KEY=...
speech-to-speech serve
```

启动后，服务器监听 `ws://localhost:8765/v1/realtime`。在另一个终端运行客户端：

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

或使用一条命令同时启动服务器和客户端：

```bash
speech-to-speech local
```

**从源码安装：**

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

## 典型使用方法

**使用 OpenAI 兼容 LLM 后端：**

```bash
speech-to-speech serve \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --tts qwen3 \
    --model_name "gpt-4o-mini" \
    --responses_api_api_key "$OPENAI_API_KEY" \
    --responses_api_stream \
    --enable_live_transcription
```

**完全本地部署（使用 llama.cpp）：**

```bash
# 终端1：启动 llama.cpp 服务器
llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full

# 终端2：启动 speech-to-speech
speech-to-speech serve \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --tts qwen3 \
    --model_name "ggml-org/gemma-4-E4B-it-GGUF" \
    --responses_api_base_url "http://127.0.0.1:8080/v1" \
    --responses_api_api_key "" \
    --responses_api_stream \
    --enable_live_transcription
```

**多语言支持：**

```bash
# 自动语言检测
speech-to-speech serve --language auto --llm_backend mlx-lm --model_name "mlx-community/Qwen3-4B-Instruct-2507-bf16"

# 指定中文
speech-to-speech serve --language zh --stt whisper-mlx --stt_model_name large-v3 --llm_backend mlx-lm --model_name mlx-community/Qwen3-4B-Instruct-2507-bf16
```

## 配置与部署要点

- **服务器绑定**：默认绑定 `127.0.0.1`，如需网络访问，使用 `--host 0.0.0.0`。
- **LLM 代理安全**：启用 `--enable_llm_proxy` 时，服务器不进行认证和限流，仅应在可信网络中使用，或部署在网关之后。
- **CUDA 版本**：Qwen3-TTS 的 GGML 后端默认针对 CUDA 12.8，若环境不匹配，需手动安装对应 wheel。
- **离线运行**：先在线运行一次以缓存模型，然后设置 `HF_HUB_OFFLINE=1` 即可离线运行。
- **Docker 部署**：提供 `docker compose up` 一键启动，包含 llama.cpp 和 Realtime 服务器。
- **参数调优**：VAD 阈值、Smart Turn 延迟等参数可通过 CLI 调整，以适应不同场景。

## 限制、风险与许可证

- **许可证**：Apache-2.0。
- **限制**：
  - 依赖外部模型和库，部分组件可能需要特定硬件（如 CUDA）。
  - 默认配置使用 OpenAI API，需要 API 密钥。
  - 多语言支持取决于所选 STT/TTS 后端。
- **风险**：
  - LLM 代理无内置认证，需自行保护。
  - 模型可能产生不准确或不当内容，需自行评估。
  - 依赖的第三方库可能存在安全漏洞，需及时更新。

## 官方链接

- GitHub 仓库：https://github.com/huggingface/speech-to-speech
- PyPI 包：https://pypi.org/project/speech-to-speech/
- 最新发布：https://github.com/huggingface/speech-to-speech/releases/tag/v0.2.12

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README（https://github.com/huggingface/speech-to-speech）
- 分析时间：2026-08-05（基于最新发布信息）