3步掌握开源语音转换工具：从零到实战

【免费下载链接】speech-to-speechBuild local voice agents with open-source models项目地址: https://gitcode.com/gh_mirrors/sp/speech-to-speech

Speech To Speech 是一个开源语音转语音项目，能够构建本地语音助手系统。这个低延迟、完全模块化的语音代理流水线采用 VAD → STT → LLM → TTS 架构，通过兼容 OpenAI Realtime 的 WebSocket API 暴露服务。每个组件都可替换，LLM 槽位支持 OpenAI 兼容协议，可连接托管提供商、HF Inference Providers，或在你自己的硬件上运行 vLLM 或 llama.cpp 服务器，实现完全本地化、完全开放的技术栈。

核心功能概览 🚀

Speech To Speech 的核心价值在于其模块化设计和低延迟特性。项目采用四阶段流水线架构，每个阶段都有多个可互换的后端实现：

1. 语音活动检测 (VAD)：使用 Silero VAD v5 检测语音边界和对话轮次
2. 语音转文本 (STT)：转录用户语音，支持实时部分转录
3. 语言模型 (LLM)：生成响应，流式传输文本和工具调用
4. 文本转语音 (TTS)：合成音频并流式传输回客户端

支持的后端组件

快速上手指南 📋

环境要求与安装

项目需要 Python 3.10+ 环境。安装非常简单：

pip install speech-to-speech

默认安装包含标准实时路径：

• Parakeet TDT 用于 STT
• OpenAI 兼容 API 用于语言模型
• Qwen3-TTS 用于语音输出（非 macOS 平台默认使用 GGML 后端，Apple Silicon 使用 mlx-audio）

基础使用示例

设置 OpenAI API 密钥并启动服务：

export OPENAI_API_KEY=your_api_key_here speech-to-speech

这将启动一个 OpenAI Realtime 兼容服务器，监听ws://localhost:8765/v1/realtime。从源码目录，你可以在另一个终端中测试：

python scripts/listen_and_play_realtime.py --host 127.0.0.1 --port 8765

运行模式选择

Speech To Speech 支持多种运行模式，适应不同场景：

Docker 部署

安装 NVIDIA Container Toolkit 后，使用 Docker Compose 一键部署：

docker compose up

Compose 文件将启动 llama.cpp 服务器（使用 Gemma 4），启动 TCP socket 服务器，并暴露端口8080、12345和12346。

高级配置详解 ⚙️

如何快速配置语音识别模型？

Speech To Speech 提供了灵活的模型配置选项。以下是几个实用配置示例：

使用本地 llama.cpp 服务器：

# 终端1：启动 llama.cpp 服务器 llama-server -hf ggml-org/gemma-4-E4B-it-GGUF -np 2 -c 65536 -fa on --swa-full # 终端2：使用本地 LLM 服务器 speech-to-speech \ --mode realtime \ --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

macOS 优化配置：

speech-to-speech --local_mac_optimal_settings

此设置自动配置：

• 添加--device mps为所有模型使用 MPS
• 设置 Parakeet TDT 用于 STT
• 设置 MLX LM 作为 LLM 后端
• 设置 Qwen3-TTS 用于 TTS，默认使用 mlx-audio 和 6bit MLX 变体
• 设置--mode local

多语言支持配置

语言支持取决于你选择的 STT 和 TTS 后端：

单语言配置示例（中文）：

speech-to-speech \ --stt whisper-mlx \ --stt_model_name large-v3 \ --language zh \ --llm_backend mlx-lm \ --model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

自动语言检测：

speech-to-speech \ --stt parakeet-tdt \ --language auto \ --llm_backend mlx-lm \ --model_name "mlx-community/Qwen3-4B-Instruct-2507-bf16"

可选后端安装

额外后端通过 pip extras 安装：

pip install "speech-to-speech[kokoro]" # 非 macOS 上的 Kokoro-82M TTS pip install "speech-to-speech[pocket]" # Pocket TTS pip install "speech-to-speech[chattts]" # ChatTTS pip install "speech-to-speech[facebook-mms]" # MMS TTS pip install "speech-to-speech[faster-whisper]" # Faster Whisper STT pip install "speech-to-speech[whisper-mlx]" # macOS 上的 Lightning Whisper MLX STT pip install "speech-to-speech[paraformer]" # 通过 FunASR 的 Paraformer STT pip install "speech-to-speech[mlx-lm]" # macOS 上的 mlx-vlm 视觉模型支持

最佳实践与性能优化 🎯

实时 API 集成

Speech To Speech 的实时模式通过 WebSocket 使用 OpenAI Realtime 协议传输音频，支持实时转录和低延迟对话轮次。服务器暴露/v1/realtime端点，任何 OpenAI Realtime 兼容客户端都可以连接：

图：将 OpenAI Realtime 客户端端点从托管的 OpenAI 切换到自托管的 speech-to-speech 服务器

服务器实现了核心 Realtime 事件集：入站包括input_audio_buffer.append、session.update、conversation.item.create、response.create和response.cancel；出站包括语音开始/停止、流式转录、音频增量、工具调用和response.done。

LLM 后端选择策略

LLM 是流水线中计算最密集、延迟最高的组件。大型模型的单次前向传播可能主导端到端响应时间，因此根据硬件和延迟预算选择合适的后端至关重要：

本地推理：

• transformers在 CUDA/CPU 上
• mlx-lm在 Apple Silicon 上

自托管服务器：

• responses-api和chat-completions可指向本地 vLLM 或 llama.cpp 服务器

提供商 API：

• 相同后端适用于 OpenAI、HF Inference Providers、OpenRouter 和其他 OpenAI 兼容提供商

性能调优建议

1. 设备选择：使用--device参数为所有组件设置统一设备，或为每个组件单独指定设备
2. VAD 参数调优：调整--thresh、--min_speech_ms、--min_silence_ms以优化语音检测
3. 模型量化：对于 Apple Silicon，使用 MLX 量化变体（bf16、4bit、6bit、8bit）平衡性能和质量
4. 流水线池大小：通过--num_pipelines调整实时流水线池大小，优化并发处理

常见问题解决

Qwen3-TTS CUDA 兼容性问题：在 Linux 上，Qwen3-TTS GGML 后端来自faster-qwen3-tts[ggml]。如果机器没有 PyPI wheel 期望的 CUDA 12 运行时，请在安装speech-to-speech之前从 Hugging Face wheelhouse 安装匹配的 wheel：

# CUDA 13.x pip install "qwentts-cpp-python==0.3.1+cu130" \ -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu130 # CUDA 12.4 pip install "qwentts-cpp-python==0.3.1+cu124" \ -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu124 # 仅 CPU 回退 pip install "qwentts-cpp-python==0.3.1+cpu" \ -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cpu pip install speech-to-speech

DeepFilterNet 兼容性注意：DeepFilterNet 用于 VAD 中的可选音频增强，需要numpy<2，并且与需要numpy>=2的 Pocket TTS 冲突。仅在不使用 Pocket TTS 的环境中手动安装。

项目架构与扩展

Speech To Speech 采用模块化设计，便于扩展和定制。主要目录结构：

src/speech_to_speech/ ├── LLM/ # 语言模型相关实现 ├── STT/ # 语音转文本处理器 ├── TTS/ # 文本转语音处理器 ├── VAD/ # 语音活动检测 ├── api/ # API 接口实现 ├── arguments_classes/ # 命令行参数类 ├── connections/ # 连接管理 ├── pipeline/ # 流水线核心逻辑 └── utils/ # 工具函数

每个组件都有对应的参数类，位于src/speech_to_speech/arguments_classes/目录下，允许通过命令行参数进行细粒度控制。

开发与贡献

对于本地开发：

git clone https://gitcode.com/gh_mirrors/sp/speech-to-speech.git cd speech-to-speech uv sync pytest ruff check

项目欢迎问题和 PR。对于较大的更改，建议先开一个 issue 讨论方法。Speech To Speech 已在数千个 Reachy Mini 机器人中作为对话后端投入生产使用，证明了其稳定性和实用性。

通过灵活的配置选项和模块化设计，Speech To Speech 为构建本地语音助手提供了强大而灵活的基础设施，无论是用于研究、开发还是生产部署，都能满足不同场景的需求。

【免费下载链接】speech-to-speechBuild local voice agents with open-source models项目地址: https://gitcode.com/gh_mirrors/sp/speech-to-speech