96 个 Python 文件怎么读：按目录找到你要改的地方

第一次 clone 下 speech-to-speech（github.com/huggingface/speech-to-speech，仓库标注 Apache-2.0，2026-08-09 快照 star 11893）的人，通常会做同一件事：打开 src/，然后发现 src/speech_to_speech/ 下有 96 个 Python 文件，加上 tests/ 41 个、demo/ 24 个、archive/ 10 个，再加上一个 18 个 dataclass、131 个 CLI 参数的参数层。从第一个文件顺着读到最后一个，是个能耗掉一整天而且读完还不知道该改哪的方案。

好消息是这个仓库的目录切得很规矩——README 自己说代码是为「易于修改」设计的，目录结构确实是照着这个目标切的。所以更有效的读法不是「按文件读」，而是按你要改的那件事倒推目录。这篇就是那张倒推表。

先记住三层，而不是 96 个文件

README 的「How it works」把这条流水线描述成四段级联：VAD → STT → LLM → TTS，每个组件跑在自己的线程里，用队列相连，对外通过一个兼容 OpenAI Realtime 的 WebSocket API 暴露。目录结构基本是这句话的一一对应：

层	目录	里面是什么
流水线层	VAD/、STT/、LLM/、TTS/	四段级联各自的 handler 实现
服务层	api/openai_realtime/	协议、两种传输、会话与取消状态、LLM 代理
参数层	arguments_classes/	18 个 dataclass，共 131 个 CLI 参数

这三层的关系是：参数层决定服务层给流水线层装配哪些实现。你在命令行敲的每一个 --xxx，都能在 arguments_classes/ 里找到定义它的那个文件；而它最终作用在哪一段，看它落在哪个 dataclass 里。

记住这三层之后，96 个文件就不再是一堆平铺的文件，而是四个盒子加两层胶水。

倒推表：我想改这件事，该开哪个目录

这张表是本文的主要内容。左边是你实际会遇到的诉求，右边是第一个该打开的目录。

你想做的事	先开这里	判断依据
改「什么时候算用户说完了」	VAD/（vad_handler.py、vad_iterator.py、smart_turn.py）+ arguments_classes/vad_arguments.py	回合切分、静音判定、重开窗口全在 VAD 侧，19 个参数集中在一个文件里
让它听得懂中文	STT/ 的 6 个 handler + 模块级 --stt	默认 STT 是 nvidia/parakeet-tdt-0.6b-v3，README 的多语言表写的是 25 种欧洲语言
改模型说什么、怎么调工具	LLM/（language_model.py、responses_api_language_model.py、tool_call/ 四个文件）	本地后端与 API 后端是两条不同的工具调用路径，改错文件等于没改
换音色 / 换合成后端	TTS/（chatTTS / facebookmms / kokoro / pocket_tts / qwen3_tts 五个 handler）	每个后端一个 handler，参数也是一个后端一个 dataclass
改客户端看到的事件、加传输方式	api/openai_realtime/	server.py、service.py、transports.py、websocket_router.py、webrtc_session.py、llm_proxy.py、pipeline_unit.py、runtime_config.py 加 handlers/ 五个文件，服务端全部在这
加一个自己的 CLI 参数	arguments_classes/	18 个 dataclass 文件，按组件命名

有两个位置值得单独点出来。

一是 smart_turn.py 在 VAD/ 里，对应参数也在 vad_arguments.py 里。这一点第一眼有点反直觉：Smart Turn 用的是 pipecat-ai/smart-turn-v3 这个外部 CPU ONNX 模型，跟 Silero VAD 不是一个东西。但它的职责是校验 Silero 给出的「说完了」判断，属于回合判定这件事，所以归在 VAD 侧是合理的。你要找 --smart_turn_threshold（默认 0.5）、--smart_turn_max_wait_ms（默认 2000）、--smart_turn_incomplete_delay_ms（默认 600），都在 vad_arguments.py，不在什么单独的 smart turn 参数文件里。

二是 LLM/lm_output_processor.py。这个文件的名字不起眼，但它是理解「为什么助手的文字和语音是两条事件流」的关键：LLM 产出之后，LMOutputProcessor 把输出劈成两路——干净文本交给 TTS，assistant_text 连同工具调用字典进 text_output_queue。你要在助手说的话上做任何加工（过滤、改写、打标），改的是这里，而不是 TTS 目录。

线索一：从参数名反查目录

大部分时候你手上先有的不是一个模糊的诉求，而是一个具体的参数名——文档里看到了，想知道它到底作用在哪。这个仓库的参数命名有前缀规律，反查很快：

• --qwen3_tts_*（23 个）→ qwen3_tts_arguments.py → 作用在 TTS/
• --kokoro_*、--pocket_tts_*、--chat_tts_*、--facebook_mms_* → 各自的 TTS dataclass
• --parakeet_tdt_*、--faster_whisper_stt_*、--paraformer_stt_*、--mlx_audio_whisper_* → 各自的 STT dataclass
• --llm_* → language_model_arguments.py（本地 transformers / mlx-lm 那条路）；--responses_api_* → responses_api_language_model_arguments.py
• --host、--port → realtime_server_arguments.py（--host 默认 127.0.0.1，--port 默认 8765）
• --device、--stt、--llm_backend、--tts、--num_pipelines 这类不带组件前缀的 → module_arguments.py

前缀规律有两个例外，按前缀猜会直接落空，值得单独记：

例外一：Transformers 版 Whisper 的参数没有 whisper 前缀。 文件是 whisper_stt_arguments.py 没错，但里面的参数叫 --stt_model_name、--stt_device、--stt_torch_dtype、--stt_compile_mode、--stt_gen_* 这一串——统统只带 --stt_ 前缀。你按 --whisper_stt_ 去搜，一个都搜不到。反过来，--faster_whisper_stt_* 倒是老老实实带全名，两组名字长得不像同一套规矩。

例外二：--model_name 在两个文件里各定义了一次，默认值还不一样。 language_model_base_arguments.py（本地后端的公共基类，和 --chat_size、--init_chat_prompt、--stream_batch_sentences 这些放在一起）里默认是 Qwen/Qwen3-4B-Instruct-2507；responses_api_language_model_arguments.py 里默认是 gpt-5.4-mini。也就是说，同一个参数名，它实际取哪个默认值取决于你选的 --llm_backend。反查这个名字时找到第一处就收工，是会得出错误结论的。

这里有一个必须记住的坑：--enable_live_transcription 在 module_arguments.py（模块级，默认 True），而 --enable_realtime_transcription 在 vad_arguments.py（VAD 侧，默认 False）。两个名字长得几乎一样，默认值相反，所属文件也不同。查资料时把它们当成一个参数，是很容易发生的事。

还有一个行为让「改错地方」变得不容易被发现：README 明说 CLI 只为选中的后端构造配置，未激活后端的已知选项仍然被接受，但会带警告地忽略，JSON 配置同理。也就是说，你给一个没启用的后端传参数，程序不会报错停下，只会警告一声继续跑。「我明明改了参数怎么没反应」这类困惑，第一嫌疑就是它。

想确认某个组合到底有哪些参数、默认值是多少，README 给的办法是 speech-to-speech serve -h；要看另一种组合的参数，把选择器放在 -h 前面：

speech-to-speech serve --stt mlx-audio-whisper -h

线索二：从线上事件反查代码

如果你是在写客户端，遇到的问题往往是「这个事件是谁发的、什么时候发的」。这条线索走的是另一条路径。

仓库内 src/speech_to_speech/api/openai_realtime/README.md 是一份 259 行的 Realtime Engine 架构文档，客户端侧的问题基本能在这里解决，不必去啃 src/ 下的实现。它写清了六步数据流：入站音频从 input_audio_buffer.append 进来，解码、重采样到 16 kHz、切成 512 采样点的块进 recv_audio_chunks_queue；VAD 在 text_output_queue 上发 speech_started / speech_stopped；STT 输出经 TranscriptionNotifier；LLM 产出经 LMOutputProcessor 劈两路；TTS 的 PCM 进 send_audio_chunks_queue；路由器的异步 _send_loop 同时抽干两个队列，把内部消息翻译成协议事件。

看懂这条链之后，事件反查就是顺着队列往回走。举两个例子：

• response.output_audio_transcript.delta 是助手转写的增量后缀，它的上游是 LMOutputProcessor 放进 text_output_queue 的 assistant_text，最终由 _send_loop 翻译出来。要改助手转写的内容，改点在 LLM/，不在路由器。
• session.update 的落点是 runtime_config.py 里的 RuntimeConfig——一个共享的 Pydantic 模型，配置深合并进去，由 VAD、LLM、TTS 在处理时读取。这一点对写客户端的人很重要：改配置不是重启生效，是处理时现读。

读并发部分：单看一个文件读不懂

有一类改动没法靠「找到那个文件」解决，打断（barge-in）就是典型。

前提是那句「每个组件跑在自己的线程里，用队列相连」。正因为这几条线程是并发推进的，取消才不能靠一个布尔标志。仓库的做法是 cancel_scope.py 里的 CancelScope，它取代了旧的双信号模式（cancel_response Event 加 discard_stale_output 布尔值），一个对象管两样东西：世代计数器 cancel_scope.generation，流水线线程在每个响应开始时捕获当前世代、在每个流式 token 上检查 cancel_scope.is_stale(gen)；以及丢弃标志 cancel_scope.discarding，由 cancel() 置位、被 _send_loop 检查，用来丢掉在 cancel() 与 response_done() 之间抵达的、来自被取代世代的输出。

要读懂这套东西，你得同时打开 api/openai_realtime/ 下的 send loop 一侧和 LLM/、TTS/ 的 handler 一侧——状态在一个对象上，检查点分散在两边。只盯着其中一个文件看，会觉得这段代码莫名其妙。同理，in_response、response_pending、__RESPONSE_DONE__ 这几个标识符也是跨文件协作的产物，搜索时按原样搜，别按中文理解去猜。

几个别走错的门

• archive/（10 个文件）：已弃用的实现放在这里，含 MeloTTS，不再接入 CLI。搜索关键字时经常会命中它，照着改半天不会生效。
• demo/（24 个）与 tests/（41 个）：读实现时它们是噪声，但反过来，想知道某个 handler 的调用姿势，tests/ 常常比正文更直接。
• scripts/：仓库自带工具，例如 README 提到的 scripts/benchmark_tts.py，可以对比 Qwen3-TTS 的几种 MLX 量化变体。这类脚本存在本身是事实，跑出来的结果我们没有。
• examples/：README 指向了 examples/gemma4-12b-macos/README.md，称其为「tested」的 Apple Silicon 全本地示例。这份文档我们没有读过正文，只能说它存在。
• Dockerfile、Dockerfile.arm64、docker-compose.yml：README 说装好 NVIDIA Container Toolkit 后 docker compose up，compose 会起一个跑 Gemma 4 的 llama.cpp 服务和实时服务，暴露 8080 与 8765 两个端口。两个端口别记反：8765 是 Realtime 服务，8080 是那个 llama.cpp。

四个常见任务的走位

最后把上面的线索拧成几条具体路线，这是「读代码」和「解决问题」之间的最后一步。

做中文语音代理：别从 VAD 开始。默认 STT 覆盖的是 25 种欧洲语言，先去 module_arguments.py 看 --stt 的取值，再去 STT/ 挑 Whisper 系或 Paraformer 的 handler。回合参数那一堆毫秒值先别动，它们不解决听不懂中文的问题。

要承载多个并发会话：这件事也不在 VAD。module_arguments.py 里 --num_pipelines 默认是 1，而每个会话要从池里认领一个队列驱动的 PipelineUnit（api/openai_realtime/pipeline_unit.py），里面装着该会话的 RealtimeService、轮次追踪器与取消状态。这是多用户部署第一个要动的地方。

要把服务暴露到网络：入口是 realtime_server_arguments.py——serve 默认绑 127.0.0.1，要暴露必须显式传 --host 0.0.0.0；local 永远绑环回。如果还开了 --enable_llm_proxy（默认关闭），README 的安全声明必须原样记住：服务端自己不做任何认证，也不做任何限流，只在受信网络上启用该代理，或者把服务部署在一个自己掌管访问控制的网关后面。这不是「配好就安全了」的那类开关，它把你配置的远端 LLM 也当成普通 OpenAI 兼容端点暴露了出去。

只写客户端、不改服务端：那 96 个文件你一个都不用读。去看 api/openai_realtime/README.md 那 259 行，客户端到服务端 5 个事件、服务端到客户端 15 个事件都在里面。

按目录找入口这件事，本质上是承认一件事：你不需要理解整个仓库，只需要把「要改的东西」和「代码位置」之间那一跳走对。这个仓库的目录切法让这一跳成本很低——前提是先记住三层结构，别一上来就顺着文件列表往下翻。

延伸阅读

• speech-to-speech 是什么：一条能换掉每一段的语音代理流水线
• VAD 到 STT 到 LLM 到 TTS：四个线程、三道队列
• 从 pip install 到第一次 serve：默认装了些什么

---

本文依据 speech-to-speech 官方仓库（github.com/huggingface/speech-to-speech）的 README、 src/speech_to_speech/arguments_classes/ 下的参数定义与 Realtime Engine 架构文档整理，核对日 2026-08-09。 本文内容为仓库源码与文档口径，我们没有安装、部署或调用过该服务，文中毫秒值均为参数默认值而非实测延迟。 参数与默认值随版本变动，请以 speech-to-speech serve -h 的实际输出为准。

安全相关做法请结合自身环境评估，本文不构成安全方案建议。许可条款请以官方 LICENSE 原文为准。