Speech To Speech：使用开源模型构建本地语音智能体

方法

架构

本仓库实现了一个语音到语音的级联管道，包含以下部分：

语音活动检测（VAD）
语音转文本（STT）
语言模型（LM）
文本转语音（TTS）

模块化

该管道提供了一种完全开放且模块化的方法，重点是利用 Hugging Face Hub 上 Transformers 库提供的模型。代码设计易于修改，我们已经支持特定设备和外部库的实现：

VAD

Silero VAD v5

STT

通过 Transformers 🤗 在 Hugging Face Hub 上的任何 Whisper 模型检查点，包括 whisper-large-v3 和 distil-large-v3
Lightning Whisper MLX
MLX Audio Whisper - 在 Apple Silicon 上快速推理 Whisper
Parakeet TDT - 在 Apple Silicon 上实现亚 100 毫秒延迟的实时流式 STT（通过 nano-parakeet 支持 CUDA/CPU，无需 NeMo）
Paraformer - FunASR

LLM

通过 Transformers 🤗 在 Hugging Face Hub 上的任何指令遵循模型
mlx-lm
OpenAI API

TTS

ChatTTS
Pocket TTS - Kyutai Labs 提供的支持语音克隆的流式 TTS
Kokoro-82M - 针对 Apple Silicon 优化的快速高质量 TTS
Qwen3-TTS

安装

从 PyPI 安装默认包：

pip install speech-to-speech

默认安装限定为标准实时语音智能体路径：

Parakeet TDT 用于 STT
兼容 OpenAI 的 API 用于语言模型
Qwen3-TTS 用于语音输出
本地音频和实时服务端模式

可选后端可通过附加依赖安装：

pip install "speech-to-speech[kokoro]"
pip install "speech-to-speech[pocket]"
pip install "speech-to-speech[faster-whisper]"
pip install "speech-to-speech[paraformer]"
pip install "speech-to-speech[mlx-lm]"
pip install "speech-to-speech[websocket]"

已弃用的模型实现（包括 MeloTTS）位于 archive/ 中，不再连接到 CLI。

从源码开发：

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

这将安装 speech_to_speech 包（可编辑模式）并使 speech-to-speech CLI 命令可用。该项目使用单个 pyproject.toml 配合平台标记，因此 macOS 和非 macOS 依赖项从一个文件自动解析。

⚠️ DeepFilterNet 注意： DeepFilterNet（用于 VAD 中可选的音频增强）需要 numpy<2，与需要 numpy>=2 的 Pocket TTS 冲突。请仅在不使用 Pocket TTS 的环境中手动安装 DeepFilterNet。

使用说明

默认 CLI 等同于实时 Parakeet + 兼容 OpenAI 的 LLM + Qwen3-TTS 设置。它使用环境中的 OPENAI_API_KEY，除非提供了 --responses_api_api_key：

speech-to-speech

管道可以通过四种方式运行：

实时方法：模型在本地或服务器上运行，并为其他应用暴露兼容 OpenAI Realtime 的 WebSocket API。
服务端/客户端方法：模型在服务器上运行，客户端使用 TCP 套接字流式传输音频输入/输出。
WebSocket方法：模型在服务器上运行，客户端使用 WebSocket 流式传输音频输入/输出。
本地方法：本地运行。

实时方法

默认实时设置使用 --llm_backend responses-api，适用于任何支持 OpenAI Responses API 协议的提供商。在启动前导出带有提供商密钥的 OPENAI_API_KEY，或使用 --responses_api_api_key 显式传递。对于非 OpenAI 提供商，还需设置 --responses_api_base_url。

export OPENAI_API_KEY=...

默认模式启动兼容 OpenAI Realtime 的服务器：

speech-to-speech

等同于：

speech-to-speech \
    --thresh 0.6 \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --tts qwen3 \
    --qwen3_tts_model_name Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
    --qwen3_tts_speaker Aiden \
    --qwen3_tts_language auto \
    --qwen3_tts_non_streaming_mode True \
    --qwen3_tts_mlx_quantization 6bit \
    --model_name gpt-5.4-mini \
    --chat_size 30 \
    --responses_api_stream \
    --enable_live_transcription \
    --mode realtime

服务端/客户端方法

在服务器上运行管道：

speech-to-speech --recv_host 0.0.0.0 --send_host 0.0.0.0

在本地运行客户端处理麦克风输入并接收生成的音频：
```
python scripts/listen_and_play.py --host <你服务器的 IP 地址>
```

WebSocket方法

以 WebSocket 模式运行管道：

speech-to-speech --mode websocket --ws_host 0.0.0.0 --ws_port 8765

从客户端应用连接到 ws://<服务器-ip>:8765 的 WebSocket 服务器。服务器处理双向音频流：
- 向服务器发送原始音频字节（16kHz，int16，单声道）
- 从服务器接收生成的音频字节

本地方法（Mac）

Mac 优化设置：

speech-to-speech --local_mac_optimal_settings

也可以指定特定的 LLM 模型：

speech-to-speech \
    --local_mac_optimal_settings \
    --model_name mlx-community/Qwen3-4B-Instruct-2507-bf16

此设置：

添加 --device mps 为所有模型使用 MPS
设置 Parakeet TDT 用于 STT（Apple Silicon 上的快速流式 ASR）
设置 MLX LM 作为 LLM 后端
设置 Qwen3-TTS 用于 TTS
--tts pocket 和 --tts kokoro 在 macOS 上也是有效的 TTS 选项
Apple Silicon 上的 Qwen3 使用 mlx-audio，默认使用 6bit MLX 变体，除非明确选择不同的量化或模型后缀

要在本地比较 MLX 变体，运行：

python scripts/benchmark_tts.py \
    --handlers qwen3 \
    --iterations 3 \
    --qwen3_mlx_quantizations bf16 4bit 6bit 8bit

实时模式

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

使用 OpenAI Realtime 客户端连接

from openai import OpenAI

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

with client.beta.realtime.connect(model="model_name") as conn:
    conn.session.update(
      session={
        "instructions": "你是一个乐于助人的助手。",
        "turn_detection": {"type": "server_vad", "interrupt_response": True},
      }
    )

    # 发送音频，接收事件等
    for event in conn:
        print(event.type)

支持的事件

客户端 -> 服务端

事件	描述
`input_audio_buffer.append`	流式传输 base64 PCM 音频。解码、重采样到 16 kHz，并为 VAD 分块。
`session.update`	深度合并会话配置（指令、工具、语音、轮次检测、音频格式）。
`conversation.item.create`	将 `input_text` 或 `function_call_output` 注入 LLM 上下文而不触发生成。
`response.create`	触发 LLM 生成。支持按响应覆盖 `instructions` 和 `tool_choice`。
`response.cancel`	取消进行中的响应并重新启用监听。

服务端 -> 客户端

事件	描述
`session.created`	连接时发送，包含当前会话配置。
`error`	协议错误（`session_limit_reached`、`unknown_or_invalid_event`、`invalid_session_type`、`conversation_already_has_active_response` 等）
`input_audio_buffer.speech_started`	VAD 检测到用户语音。
`input_audio_buffer.speech_stopped`	用户语音段结束。
`conversation.item.created`	确认从 `conversation.item.create` 注入的 `input_text`。
`conversation.item.input_audio_transcription.delta`	流式部分转录（启用实时转录时）。
`conversation.item.input_audio_transcription.completed`	用户轮次的最终转录（包含时长使用信息）。
`response.created`	在第一个出站音频块时发出（响应处于 `in_progress` 状态）。
`response.output_audio.delta`	TTS 生成的 base64 PCM 音频块。
`response.output_audio.done`	当前输出项的音频流完成。
`response.output_audio_transcript.done`	轮次的完整助手文本转录。
`response.function_call_arguments.done`	工具调用，包含 `call_id`、`name` 和 JSON `arguments`。
`response.done`	响应完成（`completed`、`cancelled`，取消原因为 `turn_detected` 或 `client_cancelled`）。

有关完整架构和设计细节，请参阅 Realtime Engine README。

LLM后端

LLM 是管道中计算最密集、延迟最高的组件。单次大模型前向传播很容易主导端到端响应时间，因此根据硬件和延迟预算选择合适的后端非常重要。为了给用户最大的灵活性，我们支持全范围的推理解决方案：

本地推理 — transformers（CUDA / CPU）和 mlx-lm（Apple Silicon）完全在本地运行模型，无外部依赖。
自托管服务器 — --llm_backend responses-api 可以指向本地 vLLM 或 llama.cpp 服务器，让您控制量化、批处理和硬件，同时保持流量在本地。
提供商 API — 相同的 responses-api 后端适用于 OpenAI、HuggingFace Inference Providers、OpenRouter 以及任何其他实现 OpenAI Responses API 的提供商。

使用 --llm_backend 选择后端（默认为 responses-api），并配合 --model_name。后端特定选项（--responses_api_base_url、--responses_api_api_key、--responses_api_stream 等）仅在 responses-api 后端时需要。

以下示例将 Parakeet TDT（本地 STT）和 Qwen3-TTS（本地 TTS）与不同的 LLM 后端配对。

兼容 OpenAI 的后端（`--llm_backend responses-api`）

--llm_backend responses-api 适用于任何实现 OpenAI Chat Completions API 的服务器 — 将 --responses_api_base_url 指向正确的端点并相应设置 --model_name：

后端	`--responses_api_base_url`	`--responses_api_api_key`
OpenAI	（省略，使用 OpenAI 默认值）	`$OPENAI_API_KEY`
HF Inference Providers	`https://router.huggingface.co/v1`	`$HF_TOKEN`
OpenRouter	`https://openrouter.ai/api/v1`	`$OPENROUTER_API_KEY`
vLLM（本地）	`http://localhost:8000/v1`	（省略或任意字符串）
llama.cpp（本地）	`http://localhost:8080/v1`	（省略或任意字符串）

# OpenAI
speech-to-speech \
    --mode local \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --tts qwen3 \
    --qwen3_tts_mlx_quantization 6bit \
    --model_name "gpt-4o-mini" \
    --responses_api_api_key "$OPENAI_API_KEY" \
    --responses_api_stream \
    --enable_live_transcription

# HF Inference Providers — 通过 Together 使用 Qwen3.5-9B
speech-to-speech \
    --mode local \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --tts qwen3 \
    --qwen3_tts_mlx_quantization 6bit \
    --model_name "Qwen/Qwen3.5-9B:together" \
    --responses_api_base_url "https://router.huggingface.co/v1" \
    --responses_api_api_key "$HF_TOKEN" \
    --responses_api_stream \
    --enable_live_transcription

# HF Inference Providers — 通过 Groq 使用 GPT-oss-20B
speech-to-speech \
    --stt parakeet-tdt \
    --llm_backend responses-api \
    --tts qwen3 \
    --qwen3_tts_mlx_quantization 6bit \
    --model_name "openai/gpt-oss-20b:groq" \
    --responses_api_base_url "https://router.huggingface.co/v1" \
    --responses_api_api_key "$HF_TOKEN" \
    --responses_api_stream \
    --enable_live_transcription

完全本地（Apple Silicon）

# MLX 后端（Apple Silicon）
speech-to-speech \
    --mode local \
    --stt parakeet-tdt \
    --llm_backend mlx-lm \
    --tts qwen3 \
    --qwen3_tts_mlx_quantization 6bit \
    --model_name "mlx-community/Qwen3-4B-Instruct-2507-bf16" \
    --enable_live_transcription

# Transformers 后端
speech-to-speech \
    --mode local \
    --stt parakeet-tdt \
    --llm_backend transformers \
    --tts qwen3 \
    --model_name "Qwen/Qwen3-4B-Instruct-2507" \
    --enable_live_transcription

Docker服务端

安装 NVIDIA Container Toolkit

https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

启动 Docker 容器

docker compose up

使用 Cuda 的推荐用法

利用 Torch Compile 配合 Whisper 和 Pocket TTS，实现简单的低延迟设置：

speech-to-speech \
    --stt parakeet-tdt \
    --llm_backend transformers \
    --tts qwen3 \
    --model_name "Qwen/Qwen3-4B-Instruct-2507" \
    --enable_live_transcription

多语言支持

该管道目前支持英语、法语、西班牙语、中文、日语和韩语。考虑两种使用场景：

单语言对话：使用 --language 标志强制执行语言设置，指定目标语言代码（默认为 ‘en’）。
语言切换：将 --language 设置为 ‘auto’。STT 检测每个语音提示的语言并传递给 LLM。可选择启用 --enable_lang_prompt，附加”请用……回复我的消息”指令，让 LLM 以检测到的语言回复。该标志默认为 False — 大型 LLM 通常能从上下文中自行识别语言，但显式指令可以帮助较小的模型保持在正确的语言中。

请注意，您必须使用与目标语言兼容的 STT 和 LLM 检查点。对于多语言 TTS，使用 ChatTTS 或其他支持目标语言的后端。

服务端版本：

自动语言检测：

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

或指定特定语言，例如中文：

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

本地 Mac 设置

自动语言检测（注意：--stt whisper-mlx 会覆盖优化设置中的默认 parakeet-tdt，因为 Whisper large-v3 具有更广泛的语言覆盖）：

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

或指定特定语言，例如中文：

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

使用 Pocket TTS

Kyutai Labs 的 Pocket TTS 提供支持语音克隆的流式 TTS。使用方法：

speech-to-speech \
    --tts pocket \
    --pocket_tts_voice jean \
    --pocket_tts_device cpu

可用的语音预设：alba、marius、javert、jean、fantine、cosette、eponine、azelma。您也可以使用自定义语音文件或 HuggingFace 路径。

命令行使用

注意： 所有 CLI 参数的参考信息可以直接在 arguments classes 中找到，或通过运行 speech-to-speech -h 查看。

模块级参数

参见 ModuleArguments 类。允许设置：

通用的 --device（如果希望每个部分在同一设备上运行）
--mode：realtime（默认）、local、socket 或 websocket
选择的 STT 实现（--stt）
选择的 LLM 后端（--llm_backend：transformers、mlx-lm 或 responses-api）
选择的 TTS 实现（--tts）
日志级别

VAD参数

参见 VADHandlerArguments 类。值得注意的是：

--thresh：触发语音活动检测的阈值。
--min_speech_ms：被视为语音的检测到语音活动的最小持续时间。
--min_silence_ms：用于分割语音的静音间隔最小长度，平衡句子切割和延迟降低。

STT、LLM 和 TTS 参数

model_name、torch_dtype 和 device 为每个 STT、LLM 和 TTS 实现暴露。STT 和 TTS 参数使用处理器前缀（例如 --stt_model_name、--llm_device）。LLM 模型选择和聊天设置通过无前缀标志在后端之间共享（例如 --model_name、--chat_size）；后端特定标志对 responses-api 后端使用 responses_api_ 前缀，对本地后端使用 llm_ 前缀。完整列表请参阅 arguments classes。

例如：

# 本地 transformers/mlx-lm 后端
--model_name google/gemma-2b-it

# 兼容 OpenAI 的后端
--llm_backend responses-api --model_name deepseek-chat --responses_api_base_url https://api.deepseek.com

生成参数

其他生成参数可以使用处理器前缀 + _gen_ 设置，例如 --stt_gen_max_new_tokens 128 或 --llm_gen_temperature 0.7。如果尚未暴露，这些参数可以添加到管道部分的参数类中。

引用

Silero VAD

@misc{Silero VAD,
  author = {Silero Team},
  title = {Silero VAD: pre-trained enterprise-grade Voice Activity Detector (VAD), Number Detector and Language Classifier},
  year = {2021},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/snakers4/silero-vad}},
  commit = {insert_some_commit_here},
  email = {hello@silero.ai}
}

Distil-Whisper

@misc{gandhi2023distilwhisper,
      title={Distil-Whisper: Robust Knowledge Distillation via Large-Scale Pseudo Labelling},
      author={Sanchit Gandhi and Patrick von Platen and Alexander M. Rush},
      year={2023},
      eprint={2311.00430},
      archivePrefix={arXiv},
      primaryClass={cs.CL}
}

Parler-TTS

@misc{lacombe-etal-2024-parler-tts,
  author = {Yoach Lacombe and Vaibhav Srivastav and Sanchit Gandhi},
  title = {Parler-TTS},
  year = {2024},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/huggingface/parler-tts}}
}

命令行参数

选项:

-h, --help          显示此帮助信息并退出
--device DEVICE     如果指定，将覆盖所有处理器的设备。（默认：None）
--mode {local,socket,websocket,realtime}
    运行流水线的模式。可选 'local', 'socket', 'websocket', 或 'realtime'。默认是 'realtime'。
    （默认：realtime）
--local_mac_optimal_settings [LOCAL_MAC_OPTIMAL_SETTINGS], --local-mac-optimal-settings [LOCAL_MAC_OPTIMAL_SETTINGS]
    如果指定，将为 Mac OS 设置最优配置。为 STT 设置 Parakeet TDT，为语言模型设置 MLX LM，为 TTS 设置 Qwen3-TTS，使用 MPS 设备和本地模式。（默认：False）
--stt {whisper,whisper-mlx,mlx-audio-whisper,faster-whisper,parakeet-tdt,paraformer}
    要使用的 STT。可选 'whisper', 'whisper-mlx', 'mlx-audio-whisper', 'faster-whisper', 'parakeet-tdt' 或 'paraformer'。默认是 'parakeet-tdt'。（默认：parakeet-tdt）
--llm_backend {transformers,mlx-lm,responses-api}, --llm-backend {transformers,mlx-lm,responses-api}
    要使用的 LLM 后端。可选 'transformers', 'mlx-lm' 或 'responses-api'。默认是 'responses-api'。（默认：responses-api）
--tts {melo,chatTTS,facebookMMS,pocket,kokoro,qwen3}
    要使用的 TTS。可选 'chatTTS', 'facebookMMS', 'pocket', 'kokoro' 或 'qwen3'。默认是 'qwen3'。（默认：qwen3）
--log_level LOG_LEVEL, --log-level LOG_LEVEL
    提供日志级别。例如 --log_level debug，默认=info。（默认：info）
--enable_live_transcription [ENABLE_LIVE_TRANSCRIPTION], --enable-live-transcription [ENABLE_LIVE_TRANSCRIPTION]
    启用用户说话时的实时转录显示（适用于 parakeet-tdt）。默认是 true。（默认：True）
--no_enable_live_transcription, --no-enable-live-transcription
    启用用户说话时的实时转录显示（适用于 parakeet-tdt）。默认是 true。（默认：False）
--live_transcription_update_interval LIVE_TRANSCRIPTION_UPDATE_INTERVAL, --live-transcription-update-interval LIVE_TRANSCRIPTION_UPDATE_INTERVAL
    实时转录的更新间隔，单位为秒（默认：0.25 秒 = 250毫秒）（默认：0.25）
--live_transcription_min_silence_ms LIVE_TRANSCRIPTION_MIN_SILENCE_MS, --live-transcription-min-silence-ms LIVE_TRANSCRIPTION_MIN_SILENCE_MS
    启用实时转录时，结束语音前的最小静音持续时间（毫秒）（默认：500毫秒）（默认：500）
--recv_host RECV_HOST, --recv-host RECV_HOST
    Socket 连接的主机 IP 地址。默认是 '0.0.0.0'，绑定到主机所有可用接口。（默认：localhost）
--recv_port RECV_PORT, --recv-port RECV_PORT
    Socket 服务器监听的端口号。默认是 12346。（默认：12345）
--chunk_size CHUNK_SIZE, --chunk-size CHUNK_SIZE
    通过 socket 发送或接收的每个数据块的大小。默认是 1024 字节。（默认：1024）
--send_host SEND_HOST, --send-host SEND_HOST
    Socket 连接的主机 IP 地址。默认是 '0.0.0.0'，绑定到主机所有可用接口。（默认：localhost）
--send_port SEND_PORT, --send-port SEND_PORT
    Socket 服务器监听的端口号。默认是 12346。（默认：12346）
--ws_host WS_HOST, --ws-host WS_HOST
    WebSocket 服务器的主机 IP 地址。默认是 '0.0.0.0'，绑定到主机所有可用接口。（默认：0.0.0.0）
--ws_port WS_PORT, --ws-port WS_PORT
    WebSocket 服务器监听的端口号。默认是 8765。（默认：8765）
--thresh THRESH       Voice Activity Detection (VAD) 的阈值。值范围通常为 0 到 1，值越高表示语音检测所需的置信度越高。（默认：0.6）
--sample_rate SAMPLE_RATE, --sample-rate SAMPLE_RATE
    音频的采样率，单位为赫兹。默认是 16000 Hz，这是语音音频的常用设置。（默认：16000）
--min_silence_ms MIN_SILENCE_MS, --min-silence-ms MIN_SILENCE_MS
    用于分割语音的静音段的最小长度。以毫秒为单位。默认是 250 毫秒。（默认：300）
--min_speech_ms MIN_SPEECH_MS, --min-speech-ms MIN_SPEECH_MS
    被视为有效语音的语音段的最小长度。以毫秒为单位。默认是 500 毫秒。（默认：500）
--max_speech_ms MAX_SPEECH_MS, --max-speech-ms MAX_SPEECH_MS
    强制分割前连续语音的最大长度。默认为无限，允许不间断的语音段。（默认：inf）
--speech_pad_ms SPEECH_PAD_MS, --speech-pad-ms SPEECH_PAD_MS
    在 VAD 触发前保留并添加到检测到的语音段开头的音频量。一旦检测到语音，会继续保留音频直到 VAD 宣告段结束。以毫秒为单位。默认是 500 毫秒。（默认：500）
--audio_enhancement [AUDIO_ENHANCEMENT], --audio-enhancement [AUDIO_ENHANCEMENT]
    通过应用降噪、均衡和回声消除等技术提高音质。默认是 False。（默认：False）
--enable_realtime_transcription [ENABLE_REALTIME_TRANSCRIPTION], --enable-realtime-transcription [ENABLE_REALTIME_TRANSCRIPTION]
    启用渐进式音频释放，用于说话期间的实时转录。默认是 False。（默认：False）
--realtime_processing_pause REALTIME_PROCESSING_PAUSE, --realtime-processing-pause REALTIME_PROCESSING_PAUSE
    说话期间释放渐进式音频块的时间间隔（秒）。默认是 0.2 秒。（默认：0.2）
--stt_model_name STT_MODEL_NAME, --stt-model-name STT_MODEL_NAME
    要使用的预训练 Whisper 模型。默认是 'distil-whisper/distil-large-v3'。（默认：distil-whisper/distil-large-v3）
--stt_device STT_DEVICE, --stt-device STT_DEVICE
    模型运行的设备类型。默认是 'cuda' 用于 GPU 加速。（默认：cuda）
--stt_torch_dtype STT_TORCH_DTYPE, --stt-torch-dtype STT_TORCH_DTYPE
    模型和输入张量的 PyTorch 数据类型。可选 `float32`（全精度）、`float16` 或 `bfloat16`（半精度）。（默认：float16）
--stt_compile_mode STT_COMPILE_MODE, --stt-compile-mode STT_COMPILE_MODE
    torch 编译的编译模式。可选 'default', 'reduce-overhead' 和 'max-autotune'。默认为 None（不编译）（默认：None）
--stt_gen_max_new_tokens STT_GEN_MAX_NEW_TOKENS, --stt-gen-max-new-tokens STT_GEN_MAX_NEW_TOKENS
    生成的最大新令牌数。默认是 128。（默认：128）
--stt_gen_num_beams STT_GEN_NUM_BEAMS, --stt-gen-num-beams STT_GEN_NUM_BEAMS
    束搜索的束数量。默认是 1，表示贪婪解码。（默认：1）
--stt_gen_return_timestamps [STT_GEN_RETURN_TIMESTAMPS], --stt-gen-return-timestamps [STT_GEN_RETURN_TIMESTAMPS]
    是否返回转录的时间戳。默认是 False。（默认：False）
--stt_gen_task STT_GEN_TASK, --stt-gen-task STT_GEN_TASK
    要执行的任务，通常是转录的 'transcribe'。默认是 'transcribe'。（默认：transcribe）
--language LANGUAGE   对话的语言。可选 'en'（英语）、'fr'（法语）、'es'（西班牙语）、'zh'（中文）、'ko'（韩语）、'ja'（日语）、'hi'（印地语）或 'None'。如果使用 'auto'，语言会自动检测并可能在对话过程中改变。默认是 'en'。（默认：en）
--paraformer_stt_model_name PARAFORMER_STT_MODEL_NAME, --paraformer-stt-model-name PARAFORMER_STT_MODEL_NAME
    要使用的预训练模型。默认是 'paraformer-zh'。可以从 https://github.com/modelscope/FunASR 选择（默认：paraformer-zh）
--paraformer_stt_device PARAFORMER_STT_DEVICE, --paraformer-stt-device PARAFORMER_STT_DEVICE
    模型运行的设备类型。默认是 'cuda' 用于 GPU 加速。（默认：cuda）
--faster_whisper_stt_model_name FASTER_WHISPER_STT_MODEL_NAME, --faster-whisper-stt-model-name FASTER_WHISPER_STT_MODEL_NAME
    要使用的预训练 Faster Whisper 模型。可选 ('tiny', 'tiny.en', 'base', 'base.en', 'small', 'small.en', 'distil-small.en', 'medium', 'medium.en', 'distil-medium.en', 'large-v1', 'large-v2', 'large-v3', 'large', 'distil-large-v2', 'distil-large-v3')。默认是 'small'。（默认：tiny.en）
--faster_whisper_stt_device FASTER_WHISPER_STT_DEVICE, --faster-whisper-stt-device FASTER_WHISPER_STT_DEVICE
    模型运行的设备类型。可选 ('cpu', 'cuda', 'auto')。默认是 'auto'。（默认：auto）
--faster_whisper_stt_compute_type FASTER_WHISPER_STT_COMPUTE_TYPE, --faster-whisper-stt-compute-type FASTER_WHISPER_STT_COMPUTE_TYPE
    计算使用的数据类型。可选 ('default', 'auto', 'int8', 'int8_float32', 'int8_float16', 'int8_bfloat16', 'int16', 'float16', 'float32', 'bfloat16')。默认是 'auto'。参考 'https://opennmt.net/CTranslate2/quantization.html#quantize-on-model-loading'（默认：auto）
--faster_whisper_stt_gen_max_new_tokens FASTER_WHISPER_STT_GEN_MAX_NEW_TOKENS, --faster-whisper-stt-gen-max-new-tokens FASTER_WHISPER_STT_GEN_MAX_NEW_TOKENS
    生成的最大新令牌数。默认是 128。（默认：128）
--faster_whisper_stt_gen_beam_size FASTER_WHISPER_STT_GEN_BEAM_SIZE, --faster-whisper-stt-gen-beam-size FASTER_WHISPER_STT_GEN_BEAM_SIZE
    束搜索的束数量。默认是 1，表示贪婪解码。（默认：1）
--faster_whisper_stt_gen_return_timestamps [FASTER_WHISPER_STT_GEN_RETURN_TIMESTAMPS], --faster-whisper-stt-gen-return-timestamps [FASTER_WHISPER_STT_GEN_RETURN_TIMESTAMPS]
    是否返回转录的时间戳。默认是 False。（默认：False）
--faster_whisper_stt_gen_task FASTER_WHISPER_STT_GEN_TASK, --faster-whisper-stt-gen-task FASTER_WHISPER_STT_GEN_TASK
    要执行的任务，通常是转录的 'transcribe'。默认是 'transcribe'。（默认：transcribe）
--faster_whisper_stt_gen_language FASTER_WHISPER_STT_GEN_LANGUAGE, --faster-whisper-stt-gen-language FASTER_WHISPER_STT_GEN_LANGUAGE
    要转录的语音的语言。默认是 'en' 表示英语。（默认：en）
--mlx_audio_whisper_model_name MLX_AUDIO_WHISPER_MODEL_NAME, --mlx-audio-whisper-model-name MLX_AUDIO_WHISPER_MODEL_NAME
    要使用的预训练 MLX Audio Whisper 模型。默认是 'mlx-community/whisper-large-v3-turbo'。（默认：mlx-community/whisper-large-v3-turbo）
--mlx_audio_whisper_gen_kwargs MLX_AUDIO_WHISPER_GEN_KWARGS, --mlx-audio-whisper-gen-kwargs MLX_AUDIO_WHISPER_GEN_KWARGS
    传递给模型的其他生成参数。默认是空字典。（默认：{}）
--parakeet_tdt_model_name PARAKEET_TDT_MODEL_NAME, --parakeet-tdt-model-name PARAKEET_TDT_MODEL_NAME
    要使用的 Parakeet TDT 模型。对于 MPS 默认是 'mlx-community/parakeet-tdt-0.6b-v3'，对于 CUDA/CPU 默认是 'nvidia/parakeet-tdt-0.6b-v3'。（默认：None）
--parakeet_tdt_device PARAKEET_TDT_DEVICE, --parakeet-tdt-device PARAKEET_TDT_DEVICE
    运行模型的设备。'auto' 在 macOS 上使用 MPS，否则使用 CUDA。可选：'auto', 'cuda', 'mps', 'cpu'。默认是 'auto'。（默认：auto）
--parakeet_tdt_compute_type PARAKEET_TDT_COMPUTE_TYPE, --parakeet-tdt-compute-type PARAKEET_TDT_COMPUTE_TYPE
    模型的计算类型。可选：'float16', 'float32'。默认是 'float16'。（默认：float16）
--parakeet_tdt_language PARAKEET_TDT_LANGUAGE, --parakeet-tdt-language PARAKEET_TDT_LANGUAGE
    转录的目标语言代码。如果未指定，模型将自动检测语言。支持 25 种欧洲语言。（默认：None）
--model_name MODEL_NAME, --model-name MODEL_NAME
    与 OpenAI 兼容 API 一起使用的模型。默认是 'gpt-5.4-mini'。（默认：gpt-5.4-mini）
--user_role USER_ROLE, --user-role USER_ROLE
    在聊天上下文中分配给用户的角色。默认是 'user'。（默认：user）
--init_chat_role INIT_CHAT_ROLE, --init-chat-role INIT_CHAT_ROLE
    设置聊天上下文的初始角色。默认是 'system'。（默认：system）
--init_chat_prompt INIT_CHAT_PROMPT, --init-chat-prompt INIT_CHAT_PROMPT
    为语言模型建立上下文的初始聊天提示。（默认：You are a helpful and friendly AI assistant. You are polite, respectful, and aim to provide concise responses of less than 20 words.）
--chat_size CHAT_SIZE, --chat-size CHAT_SIZE
    聊天中保留的助手-用户交互次数。（默认：30）
--stream_batch_sentences STREAM_BATCH_SENTENCES, --stream-batch-sentences STREAM_BATCH_SENTENCES
    在产生批处理前累积的句子数量。设置为 1 可实现逐句流式传输。默认是 3。（默认：3）
--enable_lang_prompt [ENABLE_LANG_PROMPT], --enable-lang-prompt [ENABLE_LANG_PROMPT]
    如果为 True，则附加一条用户消息，指示模型以检测到/选择的语言回复（例如 '请用法语回复我的消息。'）。默认是 False。（默认：False）
--responses_api_api_key RESPONSES_API_API_KEY, --responses-api-api-key RESPONSES_API_API_KEY
    用于验证 OpenAI 兼容 API 访问的 API 密钥。默认是 None。（默认：None）
--responses_api_base_url RESPONSES_API_BASE_URL, --responses-api-base-url RESPONSES_API_BASE_URL
    OpenAI 兼容 API 端点的基础 URL。默认是 None（使用 OpenAI）。（默认：None）
--responses_api_stream [RESPONSES_API_STREAM], --responses-api-stream [RESPONSES_API_STREAM]
    stream 参数通常表示数据是否应以连续流的形式传输，而不是单个完整响应，常用于处理大量或实时数据。默认是 True。（默认：True）
--no_responses_api_stream, --no-responses-api-stream
    stream 参数通常表示数据是否应以连续流的形式传输，而不是单个完整响应，常用于处理大量或实时数据。默认是 True。（默认：False）
--responses_api_disable_thinking [RESPONSES_API_DISABLE_THINKING], --responses-api-disable-thinking [RESPONSES_API_DISABLE_THINKING]
    当 OpenAI 兼容后端支持时，禁用提供商端的思考/推理。对于 Together Qwen3.5 模型，这会发送 chat_template_kwargs.enable_thinking=false。（默认：True）
--no_responses_api_disable_thinking, --no-responses-api-disable-thinking
    当 OpenAI 兼容后端支持时，禁用提供商端的思考/推理。对于 Together Qwen3.5 模型，这会发送 chat_template_kwargs.enable_thinking=false。（默认：False）
--chat_tts_stream [CHAT_TTS_STREAM], --chat-tts-stream [CHAT_TTS_STREAM]
    TTS 模式是流式。默认是 'stream'。（默认：True）
--no_chat_tts_stream, --no-chat-tts-stream
    TTS 模式是流式。默认是 'stream'。（默认：False）
--chat_tts_device CHAT_TTS_DEVICE, --chat-tts-device CHAT_TTS_DEVICE
    用于语音合成的设备。默认是 'cuda'。（默认：cuda）
--chat_tts_chunk_size CHAT_TTS_CHUNK_SIZE, --chat-tts-chunk-size CHAT_TTS_CHUNK_SIZE
    设置每个周期处理的音频数据块的大小，以平衡播放延迟和 CPU 负载。默认是 512。（默认：512）
--facebook_mms_model_name FACEBOOK_MMS_MODEL_NAME, --facebook-mms-model-name FACEBOOK_MMS_MODEL_NAME
    要使用的模型名称。默认是 'facebook/mms-tts-eng'。（默认：facebook/mms-tts-eng）
--tts_language TTS_LANGUAGE, --tts-language TTS_LANGUAGE
    TTS 模型的语言代码。默认是 'en' 表示英语。（默认：en）
--facebook_mms_device FACEBOOK_MMS_DEVICE, --facebook-mms-device FACEBOOK_MMS_DEVICE
    用于 TTS 模型的设备。默认是 'cuda'。（默认：cuda）
--facebook_mms_torch_dtype FACEBOOK_MMS_TORCH_DTYPE, --facebook-mms-torch-dtype FACEBOOK_MMS_TORCH_DTYPE
    用于 TTS 模型的 torch 数据类型。默认是 'float32'。（默认：float32）
--pocket_tts_device POCKET_TTS_DEVICE, --pocket-tts-device POCKET_TTS_DEVICE
    Pocket TTS 模型运行的设备类型。可选：'cpu', 'cuda', 'mps'。默认是 'cpu'。（默认：cpu）
--pocket_tts_voice POCKET_TTS_VOICE, --pocket-tts-voice POCKET_TTS_VOICE
    用于 Pocket TTS 的声音。可以是预设名称（'alba', 'marius', 'javert', 'jean', 'fantine', 'cosette', 'eponine', 'azelma'）、本地音频文件路径或 HuggingFace 路径，如 'hf://kyutai/tts-voices/...'。默认是 'jean'。（默认：jean）
--pocket_tts_sample_rate POCKET_TTS_SAMPLE_RATE, --pocket-tts-sample-rate POCKET_TTS_SAMPLE_RATE
    Pocket TTS 的输出采样率（Hz）。Pocket TTS 内部使用 24kHz，但会被重采样到此速率以匹配音频输出。默认是 16000，以匹配流水线的音频流媒体。（默认：16000）
--pocket_tts_blocksize POCKET_TTS_BLOCKSIZE, --pocket-tts-blocksize POCKET_TTS_BLOCKSIZE
    在 Pocket TTS 中流式传输产生的音频块大小。默认是 512。（默认：512）
--pocket_tts_max_tokens POCKET_TTS_MAX_TOKENS, --pocket-tts-max-tokens POCKET_TTS_MAX_TOKENS
    Pocket TTS 中每个句子生成的最大令牌数。默认是 50。（默认：50）
--kokoro_model_name KOKORO_MODEL_NAME, --kokoro-model-name KOKORO_MODEL_NAME
    要使用的 Kokoro TTS 模型。根据设备自动选择：MPS 使用 'mlx-community/Kokoro-82M-bf16'，CUDA/CPU 使用 'hexgrad/Kokoro-82M'。（默认：None）
--kokoro_device KOKORO_DEVICE, --kokoro-device KOKORO_DEVICE
    运行 Kokoro TTS 的设备。可选：'auto', 'cuda', 'cpu', 'mps'。默认是 'auto'（在 Mac 上使用 MPS，在 GPU 系统上使用 CUDA）。（默认：auto）
--kokoro_voice KOKORO_VOICE, --kokoro-voice KOKORO_VOICE
    用于合成的声音。有关选项，请参阅 Kokoro 仓库中的 VOICES.md。默认是 'bm_fable'（英式男声）。（默认：bm_fable）
--kokoro_lang_code KOKORO_LANG_CODE, --kokoro-lang-code KOKORO_LANG_CODE
    语言代码：'a' 表示美式英语，'b' 表示英式英语，'j' 表示日语等。默认是 'b'。（默认：b）
--kokoro_speed KOKORO_SPEED, --kokoro-speed KOKORO_SPEED
    语速乘数。值 > 1.0 加速，< 1.0 减速。默认是 1.0。（默认：1.0）
--kokoro_blocksize KOKORO_BLOCKSIZE, --kokoro-blocksize KOKORO_BLOCKSIZE
    流式输出的音频块大小（样本数）。默认是 512。（默认：512）
--qwen3_tts_model_name QWEN3_TTS_MODEL_NAME, --qwen3-tts-model-name QWEN3_TTS_MODEL_NAME
    要使用的 Qwen3-TTS 模型（HuggingFace Hub ID 或本地路径）。默认是 'Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice'。在 Apple Silicon 上，Qwen/* 模型 ID 会尽可能自动映射到相应的 mlx-community/* 模型，除非模型名称已指定特定后缀，否则默认使用 6bit MLX 变体。（默认：Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice）
--qwen3_tts_device QWEN3_TTS_DEVICE, --qwen3-tts-device QWEN3_TTS_DEVICE
    Qwen3-TTS 的首选设备。可选：'cuda', 'cpu', 'mps', 'auto'。默认是 'cuda'。在 Apple Silicon 上会自动选择 mlx-audio 后端。（默认：cuda）
--qwen3_tts_dtype QWEN3_TTS_DTYPE, --qwen3-tts-dtype QWEN3_TTS_DTYPE
    推理的数据类型。可选：'auto', 'float16', 'bfloat16', 'float32'。默认是 'auto'。（默认：auto）
--qwen3_tts_attn_implementation QWEN3_TTS_ATTN_IMPLEMENTATION, --qwen3-tts-attn-implementation QWEN3_TTS_ATTN_IMPLEMENTATION
    注意力实现。可选：'eager', 'flash_attention_2', 'sdpa'。在 Jetson 上使用 'eager'。默认是 'eager'。（默认：eager）
--qwen3_tts_ref_audio QWEN3_TTS_REF_AUDIO, --qwen3-tts-ref-audio QWEN3_TTS_REF_AUDIO
    用于声音克隆的参考音频文件的可选路径。使用 CustomVoice 模型时请保持未设置状态。（默认：None）
--qwen3_tts_ref_text QWEN3_TTS_REF_TEXT, --qwen3-tts-ref-text QWEN3_TTS_REF_TEXT
    用于声音克隆的参考音频的转录文本。（默认：I'm confused why some people have super short timelines, yet at the same time are bullish on scaling up reinforcement learning atop LLMs. If we're actually close to a human-like learner, then this whole approach of training on verifiable outcomes.）
--qwen3_tts_speaker QWEN3_TTS_SPEAKER, --qwen3-tts-speaker QWEN3_TTS_SPEAKER
    用于 CustomVoice 模型的说话人名称。默认是 'Aiden'。如果未提供，当可用时使用第一个支持的说话人。（默认：Aiden）
--qwen3_tts_instruct QWEN3_TTS_INSTRUCT, --qwen3-tts-instruct QWEN3_TTS_INSTRUCT
    用于 VoiceDesign 模型的指令文本（声音设计需要）。（默认：None）
--qwen3_tts_xvec_only [QWEN3_TTS_XVEC_ONLY], --qwen3-tts-xvec-only [QWEN3_TTS_XVEC_ONLY]
    仅使用 x-vector 声音克隆模式（推荐用于更清晰的开头和语言切换）。默认是 False。（默认：False）
--qwen3_tts_parity_mode [QWEN3_TTS_PARITY_MODE], --qwen3-tts-parity-mode [QWEN3_TTS_PARITY_MODE]
    禁用 CUDA-graph 流式传输路径并使用奇偶校验模式以提高稳定性。默认是 False。（默认：False）
--qwen3_tts_non_streaming_mode [QWEN3_TTS_NON_STREAMING_MODE], --qwen3-tts-non-streaming-mode [QWEN3_TTS_NON_STREAMING_MODE]
    Qwen3-TTS 文本预填充行为的可选覆盖。默认值为 true，即在 faster-qwen3-tts 上解码前预填充完整的目标文本。

Speech To Speech：使用开源模型构建本地语音智能体

方法

架构

模块化

安装

使用说明

推荐设置

实时方法

服务端/客户端方法

WebSocket方法

本地方法（Mac）

实时模式

使用 OpenAI Realtime 客户端连接

支持的事件

LLM后端

兼容 OpenAI 的后端（`--llm_backend responses-api`）

完全本地（Apple Silicon）

Docker服务端

安装 NVIDIA Container Toolkit

启动 Docker 容器

使用 Cuda 的推荐用法

多语言支持

服务端版本：

本地 Mac 设置

使用 Pocket TTS

命令行使用

模块级参数

VAD参数

STT、LLM 和 TTS 参数

生成参数

引用

Silero VAD

Distil-Whisper

Parler-TTS

命令行参数

相关文章

搭建 Reachy Mini 语音对话智能体

Reachy Mini Conversation App

OpenAI API Documentation Speech to Text

方法

架构

模块化

安装

使用说明

推荐设置

实时方法

服务端/客户端方法

WebSocket方法

本地方法（Mac）

实时模式

使用 OpenAI Realtime 客户端连接

支持的事件

LLM后端

兼容 OpenAI 的后端（--llm_backend responses-api）

完全本地（Apple Silicon）

Docker服务端

安装 NVIDIA Container Toolkit

启动 Docker 容器

使用 Cuda 的推荐用法

多语言支持

服务端版本：

本地 Mac 设置

使用 Pocket TTS

命令行使用

模块级参数

VAD参数

STT、LLM 和 TTS 参数

生成参数

引用

Silero VAD

Distil-Whisper

Parler-TTS

命令行参数

相关文章

搭建 Reachy Mini 语音对话智能体

Reachy Mini Conversation App

OpenAI API Documentation Speech to Text

兼容 OpenAI 的后端（`--llm_backend responses-api`）