GitShelf — GitHub 项目目录

项目概述

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（部分功能）。

安装与快速开始

安装：

pip install speech-to-speech

快速开始：

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

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

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

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

speech-to-speech local

从源码安装：

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

典型使用方法

使用 OpenAI 兼容 LLM 后端：

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

# 终端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

多语言支持：

# 自动语言检测
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（基于最新发布信息）

项目概览