Hy-SimulMT 本地实时同传
是怎么跑起来的

01全链路数据流

整条链路上只有一个模型进程，启动时加载一次（约 8 秒），之后全程常驻。 音频以 16kHz / 单声道 / PCM16LE 这个统一格式贯穿始终 —— 浏览器、网络、Python、C++、Swift 原生进程 都认这一种格式，所以中间不需要任何转码环节。

系统一共有三种运行形态，共用同一套切块 / 账本 / 丢块逻辑，区别只在音源是谁：

02模型层：三处改动打通实时

Hy-SimulMT-30B-A3B 是按轮次工作的模型：先听 1600ms，之后每 800ms 一轮， 每轮都要在听下一轮之前先作答。而官方 llama-mtmd-cli 只能读一个完整音频文件， 跑完就退出 —— 每次重新加载 18GB 权重约 8 秒，实时无从谈起。官方文档还明确写了 llama-server 跑不了这批 GGUF。

项目用三步把这件事打通，每一步都踩了一个具体的坑：

改动一：让 llama-server 认内嵌投影器

这批 GGUF 是单文件，音频塔（audio tower）已经打包进文本模型，所以正常情况下不需要 --mmproj。但 llama-server 判断"有没有多模态能力"只看 --mmproj 是否非空。把参数直接指向模型自己，投影器就装上了：

llama-server -m models/Hy-SimulMT-30B-A3B-Interleave-Q4_K_M.gguf \
             --mmproj models/Hy-SimulMT-30B-A3B-Interleave-Q4_K_M.gguf

/props 里 modalities.audio 变成 true， 一次能跑通整段音频（14.16s 音频 1.76s，约 8 倍实时）。但这条路最终没被采用—— 原因就是改动二。

改动二：不走 server 的 chat 模板

llama-server 走 OpenAI 消息协议，模板里给助手回合只发了 <｜hy_Assistant｜><think><>， 漏掉了 src_tgt checkpoint 必需的分支标记 溯源。少了它，源文分支会退化，实测输出直接变成重复片段：

"下一季度我们将重点提升下一季度我们将重点提升下一季度我们将重点提升…"

而且模板里根本没有"每轮重放助手头"这个概念 —— 硬套一定会失真。所以最终方案是绕开 server， 直接改造 CLI。

改动三：给 llama-mtmd-cli 加 --stream（+260 行）

这是本次最核心的改动。音频不再来自 --audio 文件，而是从 stdin 读裸 PCM16LE 单声道 16kHz，每凑满一轮就跑官方那套轮次逻辑，把结果按 JSON 行打到 stdout：

// live streaming variant: the same turn logic as run_turn_stream, but the audio
// arrives as raw PCM16LE mono 16 kHz on stdin instead of a file on disk, and
// every answered turn is reported as one JSON line on stdout.
//
// stdin blocking is what paces the pipeline: the loop will not start a turn
// until a full step of audio has been buffered, so the model never runs ahead
// of the speaker.

static int  g_stream_first = 1600; // ms of audio in the opening turn
static int  g_stream_step  = 800;  // ms of audio per following turn

协议极简，三种消息：

{"type":"ready"}
{"type":"turn","i":0,"ms":1600,"src":"Good morning, everyone.","tgt":"大家早上好。","n_gen":11,"gen_ms":149.0,"pos":312}
{"type":"done","turns":17}

pos 是当前的上下文位置，Python 侧用它判断何时该换一个干净会话。

03分轮 schedule 与 prompt 结构

理解这个项目，关键是理解一次 decode 同时产出源文和译文。 模型不是先 ASR 再 MT 的两级流水线，而是在同一个生成序列里用 溯源 这个特殊 token 做分界：出现之前的部分是源文，之后是译文。

对应的常量定义在 live.py 顶部：

HEAD = "<｜hy_begin▁of▁sentence｜><｜reasoning_mode｜>reasoning_effort:no_think<｜hy_User｜>"
TAIL = "<__media__><｜hy_Assistant｜><think></think>溯源"
INSTR = {
    "en-zh": "请完成下面的同声传译任务，将陆续收到的语音翻译成中文。"
             "请结合上下文边听边译，输出能够确定的译文，不必等待整句结束。",
    "zh-en": "Please act as a simultaneous interpreter. Translate the incoming speech "
             "into English as you listen. Output what you are confident about instead of "
             "waiting for the whole sentence to finish.",
}

注意 指令语种决定翻译方向。指令在首轮就被解码进上下文了，所以换方向必须重启模型进程 （约 8 秒）—— 这是"只能单向"这个边界的根因。

生成阶段的分流逻辑就一行判断：

if (tok == t_tgt) {
    in_tgt = true;
} else if (!llama_vocab_is_control(ctx.vocab, tok)) {
    const std::string piece = common_token_to_piece(ctx.lctx, tok);
    (in_tgt ? tgt : src) += piece;      // 溯源 之前归源文，之后归译文
}

04服务层：零依赖 live.py

live.py 有 1238 行，只用 Python 标准库 —— 连 WebSocket 的握手和帧编解码都是自己实现的（ws_accept_key / ws_frame / ws_read，共 50 行）。这样整条链路不需要 pip install 任何东西。

进程与线程模型

切块：Python 与 C++ 的边界对齐

Python 侧按 800ms 切块送进 stdin。C++ 首轮吃 1600ms（= 2 块）、之后每轮 1 块， 而 1600 是 800 的整数倍 —— 所以两边块边界天然对齐。这一点很重要： 只有对齐了，才敢整块丢弃；丢半块会让后面所有音频错位一格。

block = SAMPLE_RATE * BLOCK_MS // 1000 * 2        # 16000 * 800 / 1000 * 2 = 25600 字节
while len(self.stage) >= block:
    chunk = bytes(self.stage[:block])
    del self.stage[:block]
    if self.sent_ms - self.done_ms > MAX_BACKLOG_MS:   # 积压超限 → 整块丢掉追平
        self.dropped_ms += BLOCK_MS
        self.sent_ms += BLOCK_MS
        continue
    p.stdin.write(chunk); p.stdin.flush()
    self.sent_ms += BLOCK_MS

WebSocket：只实现服务端需要的最小子集

三个 opcode 就够了：0x1 文本（控制指令）、0x2 二进制（PCM16）、 0x8 关闭，外加 0x9 ping 回 0xA pong。 客户端发来的控制指令很薄：ping（带字节账）、direction、 tts、source、interrupt、level、 device、rebuild。

05音频账本：一把尺子量全链路

这是整个项目最有工程价值的设计。"漏了一句"这种问题，靠听是查不出来的 —— 必须有一把统一的尺子，把浏览器采集、网络发送、服务端接收、模型处理四个环节放在同一个单位（毫秒）下对账。

换算关系固定：16kHz × 2 字节 = 32000 字节/秒 = 32 字节/毫秒，所以账本里到处是 // 32。

06实时性的四道闸门

"实时"不是自然产生的，是四个机制共同兜出来的。每一个都对应一个具体会发生的失败。

还有两处自动自愈

• 空轮自动重启会话：连续 30 轮空轮，且最近 25 块的平均 RMS 确实有声 （>400，说明不是真的静音）→ 判定会话已废，自动重启，8 秒自愈。 纯静音（视频暂停）不触发 —— 靠 block_rms 区分"真没声"和"有声但不译"。
• 麦克风能量上报：浏览器每秒把 RMS 报给服务端。 这一项是判断"没声音"的唯一硬证据 —— 因为数字静音的字节数照样在涨， 账本照样完美对平，模型照样吐空轮，界面上完全看不出来。

07浏览器层：双 AudioContext

前端 live.html 是单文件、零外部依赖。它最要紧的一条设计是： 采集和播放必须是两个独立的 AudioContext。

AudioWorklet：为什么不用 ScriptProcessor

采集用 AudioWorkletNode（处理器名 tap），源码以字符串形式内联、用 Blob URL 注册， 因此保持单文件零依赖。它每攒满 1024 帧就 postMessage 一次：

class Tap extends AudioWorkletProcessor{
  constructor(){ super(); this.buf=new Float32Array(1024); this.n=0; }
  process(inputs){
    var ch=inputs[0]&&inputs[0][0];
    if(ch){ for(var i=0;i<ch.length;i++){
        this.buf[this.n++]=ch[i];
        if(this.n===1024){ this.port.postMessage(this.buf); this.buf=new Float32Array(1024); this.n=0; }
    }}
    return true;
  }
}

重采样与软件 AGC

优先让浏览器自己的重采样器去做（它有抗混叠滤波）；代码里保留了一份纯线性插值的 Resampler 作为 fallback，并明确注释了代价： 44.1k→16k 会把 8k 以上的能量折叠进语音频段，听起来没差，但模型的识别率会明显下降。

关闭 Chrome 的 AGC 后，内置麦克风阵列送来的电平可能低到 −60 dBFS —— 人耳觉得"我明明在说话"， 模型那边几乎是静音。所以自己实现了慢速包络归一化：

• 包络 agcEnv = max(peak, agcEnv × 0.995)，门限 8e-5（刚好在数字静音之上）
• 目标增益 min(150, 0.22 / agcEnv)，用 +(want−gain) × 0.08 平滑跟随
• 软限幅 ±0.95 兜住瞬时过冲；增益只在包络高于噪声底时才提升，所以纯底噪不会被放大成"人声"

发送缓冲：决不静默吞掉半句话

播放排队与高亮

译音不是"来一段播一段"，而是用 S.nextTime 单调递增地在 Web Audio 时间轴上排队， 段间留 15ms 间隙，落后超过 0.5 秒就重新对齐。同时用一个 requestAnimationFrame 循环把当前时间段对应的字幕行标为 .playing —— 播放高亮是跟着 AudioContext 时钟走的，不是跟着"刚收到哪条"走的。

08TTS：并行合成 + 顺序回传

TTS 用 macOS 原生 say（中文 Tingting / 英文 Ava Enhanced）， 实测 RTF≈0.11。但它有个要命的特点：每次调用有约 0.85 秒的固定启动开销， 跟文本长度几乎无关 —— 一个字 0.868s，七秒长的文本 0.916s。

而一轮音频才 800ms。串行合成会刚好卡在临界点上，说话人一旦不停就会越积越多。 解法是 2 个 worker 并行合成 + 1 个 emitter 严格按序回传：

# 严格按轮次顺序把音频推给页面，避免并行合成打乱播放次序
while True:
    with self.tts_cv:
        while not self.tts_order: self.tts_cv.wait(1.0)
        i = self.tts_order[0]
        waited = 0.0
        while i not in self.tts_done:
            self.tts_cv.wait(0.3); waited += 0.3
            if waited > 3.0:                     # 音频晚 3 秒就没意义了
                self.tts_done[i] = (None, 0)     # 超时跳过，不能堵死后面所有轮次
        path, dur = self.tts_done.pop(i)
        self.tts_order.pop(0)

那 1.15 秒的"说话→出声"里，约 0.9 秒是 say 的固定启动开销。 换语音压不下来，要做到更低必须用进程内合成（AVSpeechSynthesizer），那是另一件事。

09视频同传：系统声音与自激

看视频场景不需要麦克风 —— 用 native/sys-tap 直接抓 系统里正在播放的任何声音（浏览器视频、QuickTime 都行）， 翻译后由 native/ttsplay 常驻进程念出来。前提：macOS 14.4+， 且运行本服务的终端已在「隐私与安全性 → 屏幕与系统音频录制」里授权。

sys-tap 的实现路径

Swift 直接调 CoreAudio 私有 API，四步：

1. 建 tap：CATapDescription 用 stereoGlobalTapButExcludeProcesses， AudioHardwareCreateProcessTap；muteBehavior = .mutedWhenTapped
2. 建私有聚合设备：AudioHardwareCreateAggregateDevice，UUID 随机，不污染系统设备列表
3. IOProc 回调：多缓冲/多声道统一混成 mono → 线性插值重采样 48k→16k（跨块保持相位）→ s16le
4. 写 stdout：write() 失败就丢，不在实时线程里死等

ttsplay 的管道协议

stdin : [4 字节大端长度 N][N 字节 WAV]        N = 0 → 清空队列并停止当前播放
stdout: 每播完一条打印一行 "done"             供服务端对账（player_done）
EOF   : 播完队列里剩下的再退出

打断语义

模型每 800ms 吐一轮译文，连续轮次顺序连播才是完整句子，所以平时 不逐轮打断 —— 只在积压 ≥4 轮（明显跟不上）时自动清队，或手动点「打断播报」 （给 ttsplay 写一个 len=0 帧）。

10故障分诊：六种「没反应」

「说了几句就没反应」有几种完全不同的原因，过去都表现为界面无任何提示， 只能靠猜。现在每种都有自己的信号 —— 这是这个项目在工程上最见功力的部分。

另外还有一个诊断钩子，供自动化验证与排障使用：

window.__diag()  // → running / ws / audioCtx / rows / withAudio / scheduled /
                 //   playing / sampleRate / micRate / genMs / sentMs / dropMs /
                 //   sendFail / recvAge / warn

11实测数据

环境：M2 Max / 64GB / macOS，模型 Q4_K_M，Metal 后端。

服务启动时还会把麦克风原始音频默认落盘（HY_DUMP，16k 单声道 16bit ≈ 115MB/小时）。 出事时能把"用户到底说了什么"直接放出来听，不用再靠猜 —— 注意只落盘真的进了模型的音频， 以前连被拒的也一起落，排查时听到的是模型根本没听过的东西，反而被带偏。

12已知边界与设计取舍

文件清单