Soniox “Invalid language hint“ 事故复盘：一个披着空闲超时外衣的配置型会话死亡

Soniox "Invalid language hint" 事故复盘：一个披着空闲超时外衣的配置型会话死亡

【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend

本篇文章完整复盘 Friend 后端（Python backend）在 2026-09-02 至 09-03 期间发生在 backend-listen 服务上的一起真实事故：Soniox 流式语音识别会话反复以400 invalid_request Invalid language hint报错死亡，却被监控体系误判为"VAD 空闲超时"。文章以 backend/docs/operational/soniox-invalid-language-hint.md 的故障记录为主体，结合 backend/config/stt_provider_policy.py、backend/utils/stt/soniox.py、backend/utils/stt/live_failure.py 等源码与对应单元测试，还原根因、修复契约与验证方法。读完你将掌握：如何在多提供商 STT 架构中管理"提供商封闭词汇表"这类配置边界、如何让错误分类与日志/指标严重级别保持一致，以及为什么这类问题不能靠熔断整个提供商来解决。

事故窗口与传感器特征：先看数据的"形状"

事故记录给出的第一组事实来自监控信号：

• 影响窗口：2026-09-02 至 09-03，发生在 backend-listen（Loop S 传感器）；
• 日志签名：ERROR:utils.stt.soniox:Soniox streaming error: 400 invalid_request Invalid language hint.；
• 出现频率：在 6+ 小时的时段内（约 24 小时中的 16 小时），几乎每个 30 分钟监控窗口都会出现，且每个窗口稳定出现 1–2 次。

这种"每个窗口少量、但持续不断"的节奏，与全量故障（fleet-wide outage）有本质区别：它指向一小撮不断重连的会话。换句话说，有少数用户一旦打开 App，其会话就会建立 → 报错死亡 → 重连 → 再死亡，如此循环，只要 App 保持打开就停不下来。这个"稳定 ×1–2 每窗口"的指纹，正是事后判断影响面时最关键的线索——它不是大面积宕机，而是特定语言配置下用户的"永久性死亡循环"。

根因：选择逻辑很诚实，客户端却"多嘴"了

未验证的language_hints字段

Soniox 的核心能力是自动识别语言，因此选择（selection）逻辑对它的评价是诚实的——"Soniox 自己能识别语言，所以任何请求的语言都可以服务"。问题在于，客户端随后在配置帧里还是把语言"告诉"了提供商：

• process_audio_soniox 之前对每一个非multi语言都会无条件发送language_hints: [<规范化基础代码>]，不做任何校验；
• 而 Soniox 服务端会对language_hints字段逐一核对它自己文档化、带版本号的支持语言词汇表，一旦发现词汇表外的代码，就返回400 invalid_request Invalid language hint；
• 关键在于时机：这个 400 是在 WebSocket 升级已经成功之后以流内错误帧（in-stream error frame）的形式返回的，而不是连接阶段失败。因此它不会表现为"连接失败"，而表现为"连接成功、配置帧被拒、会话随即死亡"。

从 backend/utils/stt/soniox.py 可以看到配置帧的完整形态：api_key、model、audio_format: 'pcm_s16le'、sample_rate、num_channels: 1、enable_speaker_diarization、enable_language_identification，以及有问题的language_hints。其中model默认是stt-rt-v5（环境变量SONIOX_MODEL可覆盖），SONIOX_WS_URL默认指向 Soniox 的实时转写 WebSocket 端点——这正是文档中提到的"单一统一模型"。

真实案例：马耳他语（mt）用户的死亡闭环

事故记录给出了一个活生生的例子——mt（马耳他语）：

1. App 层面接受mt作为用户语言：批处理 Parakeet 模型的 25 语言列表里确实包含mt（见 PARAKEET_SUPPORTED_LANGUAGES_BY_MODEL 中parakeet-tdt-0.6b-v3的集合，mt在列）；
2. 但 Modulate 的自动检测表不包含mt（对照 MODULATE_SUPPORTED_LANGUAGES，其中没有mt），所以该用户在选择链路上跳过 Modulate；
3. Soniox 被选中（因为选择逻辑对 Soniox 的承诺是"什么语言都能服务"）；
4. 客户端把language_hints: ['mt']发给 Soniox，而mt不在 Soniox 的 hint 词汇表中，配置帧即被拒，socket 死亡；
5. Soniox 分支自己的回退也是空的：modulate_is_configured_fallback('mt')返回False，Deepgram 没有mt模型，于是没有任何提供商可救援；
6. 结果：每次重连都复现同样的死亡，只要用户不关 App。

这条链路的每一步都有单元测试锁定：测试test_the_mt_session_has_no_configured_fallback_provider明确断言modulate_is_configured_fallback('mt') is False且deepgram_fallback_model('mt') is None。

大写哨兵绕过：'Multi'泄漏

旧代码还有一个隐蔽的绕过路径。原始的守卫是这样写的：比较输入language != 'multi'，发送的却是规范化后的代码。而规范化的结果是"切掉-/_后缀、转小写"，所以：

• 用户配置'Multi'时，输入与'multi'不相等，守卫放行；
• 规范化后变成'multi'，被当作字面量 hint 发送出去；
• Soniox 词汇表里自然没有multi（它是我们自己的自动检测哨兵，不是 ISO 代码），于是同样被 400 拒绝。

也就是说，即使语言本身在词汇表内，只要用户以'Multi'这样的大小写形式配置了自动检测，就会踩进同一个坑。

二次故障：死亡被误分类为 VAD 空闲超时

最隐蔽的问题在于错误分类。旧的 soniox_death_reason 把每一个400 错误都映射为soniox_idle_timeout。这带来两个后果：

1. 日志级别失真：这类死亡被记为 WARNING，含义是"协议在回答这个会话是怎么被使用的"（即用户没说话、VAD 饿死了），而真相是"我们的配置违反了提供商的封闭词汇表"；
2. 指标失真：在omi_live_stt_terminal_failures_total中，它们被计为 VAD 空闲超时（VAD-starvation），而不是配置拒绝。

于是，一个配置 bug 穿着使用 bug 的服装，对值班人员完全不可见——顶层错误签名里它被归类成"用户不说话"，没人会去查配置。这解释了为什么它能在生产环境持续 16 小时而不被发觉。

修复后的契约：一张表说清所有行为

事故记录用一张表格定义了修复后的行为契约，这是理解整个修复的核心：

关注点	修复后行为
是否发送 hint	仅当规范化基础代码在SONIOX_SUPPORTED_LANGUAGE_HINTS（提供商文档词汇表）内时才发送
不支持的语音	不发送 hint；由enable_language_identification服务会话（自动检测支持模型所支持的全部语言），同时调用record_fallback(component='stt_selection', from_mode='soniox_language_hint', to_mode='soniox_language_identification', reason='capability_mismatch', outcome='degraded')—— 静默修复用户体验可以，静默掩盖运维信号不行
'Multi'/'ja-JP'/'EN'	在哨兵比较之前完成规范化；任何会被拒绝的条目都不可能被发送
携带 "Invalid language hint" 的 400 帧	归类为soniox_invalid_hint，以ERROR级别记录，phase 为initialization
其他 400	仍归类为soniox_idle_timeout，保持 WARNING 级别（VAD 饥饿形态）
选择熔断电路	刻意不打开：提供商是健康的，错的是我们的配置；为所有人禁用 Soniox 等于把一个用户的坏配置放大成全量提供商跳过

逐项拆解这条契约的设计动机：

• hint 是"可降级"的，不是"必须"的。Soniox 的enable_language_identification能识别模型支持的所有语言，hint 只是用于微调识别倾向。所以当语言在词汇表外时，正确做法是不发 hint、靠自动识别，而不是拒绝服务。这是"选择承诺不变、客户端行为修正"的关键。
• record_fallback是运维可见性的保证。在 backend/utils/observability/fallback.py 中，record_fallback会递增OMI_FALLBACK_TOTAL指标并输出一条 WARNING 日志，且所有标签都要落在封闭的枚举内：component='stt_selection'、reason='capability_mismatch'、outcome='degraded'都在各自允许集合中（见ALLOWED_COMPONENTS、ALLOWED_REASONS、ALLOWED_OUTCOMES）。测试test_the_fallback_event_labels_are_all_inside_the_telemetry_contract专门锁死了这一点——标签若不在枚举内会被静默归为other，那就等于又制造了一次隐性失效。
• phase 归属体现"什么时候死的"。在 backend/utils/stt/live_failure.py 的_FAILURE_PHASE_BY_REASON中，soniox_invalid_hint映射到initialization，而soniox_idle_timeout、soniox_account_state、soniox_rotation映射到connection。这准确反映了事实：配置帧在 WebSocket 升级之后、任何音频流动之前就被拒绝了，会话死在初始化阶段，而不是流传输中途。

为什么用静态词汇表，而不是实时 Get-models 端点

一个自然的疑问是：为什么不直接调用 Soniox 的认证 Get-models 端点动态获取支持语言？事故记录给出了明确的工程权衡：

1. 词汇表是"文档化、带版本"的。SONIOX_SUPPORTED_LANGUAGE_HINTS对应的是提供商文档中针对单一统一模型stt-rt-v5的支持语言页面，按部署节奏维护；
2. 策略归位。把词汇表放在 backend/config/stt_provider_policy.py 里，与其他能力表（MODULATE_SUPPORTED_LANGUAGES、PARAKEET_SUPPORTED_LANGUAGES_BY_MODEL）并列，意味着"提供商词汇表变更 = 在唯一拥有提供商能力归属的模块里做一次经过评审的改动"，与既有的MODULATE_SUPPORTED_LANGUAGES、PARAKEET_SUPPORTED_LANGUAGES_BY_MODEL模式完全一致；
3. 零收益的网络依赖。认证 Get-models 端点会为选择链路引入一个启动期的网络依赖（启动失败 = 无法选择提供商），而今天它带来的行为差异为零——因为选择的承诺本来就不依赖 hint，hint 只是可选项。

这个决策的核心理念是：能力表是"代码所有"（code-owned）而非"环境所有"（environment-owned）。正如 stt_provider_policy.py 模块 docstring 所写：改变一个提供商的可用性要求一次经过评审的改动；部署清单可以调整顺序，但不能复活一个不在策略里的提供商。

源码级实现：修复落在哪里

词汇表：60 个代码的frozenset

SONIOX_SUPPORTED_LANGUAGE_HINTS 是一个Final[frozenset[str]]，包含 60 个两字母语言代码（af、ar、zh、en、fr、de、ja、ru等）。源码注释明确交代了三件事：

• multi哨兵故意缺席——它是我们自己的自动检测标记，不是 ISO 代码，自动检测会话必须完全不发 hint；
• 词汇表的来源是提供商文档化的支持语言页面（单一统一模型）；
• 它必须和其他能力表放在一起，这样提供商词汇表变更就是一次受控修改。

配套的 gate 函数 soniox_accepts_language_hint 只做一件事：判断"规范化的基础代码是否在词汇表内"。它的 docstring 点明了语义边界——选择（selection）对每个语言都认为 Soniox 可服务，因为模型自己识别语言；这个 gate 只约束language_hints这一个字段，即配置帧中唯一被提供商按封闭集合校验的部分。

配置帧构建：先规范化，再门控，再回退

修复后的 process_audio_soniox 顺序是：

1. normalized = normalized_stt_language(language)：先规范化（切-/_后缀 + 小写），得到基础代码；
2. if normalized and normalized != 'multi'：此时比较的是规范化后的值，'Multi'已经变成multi，不会再泄漏；
3. 调用soniox_accepts_language_hint(normalized)做词汇表门控：
   • 在词汇表内 →config['language_hints'] = [normalized]；
   • 不在词汇表内 → 触发record_fallback（from_mode='soniox_language_hint'→to_mode='soniox_language_identification'，reason='capability_mismatch'，outcome='degraded'）并记录一条Soniox language hint dropped: ...的 WARNING 日志，然后不带 hint继续连接。

normalized_stt_language 的实现是language.split('-')[0].split('_')[0].lower()，它统一了所有提供商的比较基准——'ja-JP'→'ja'，'EN_us'→'en'。

死亡分类：从 free-text 到有界词汇表

修复后的 soniox_death_reason 按error_code+error_type+error_message三元组分类：

• 400+ 消息包含invalid language hint→soniox_invalid_hint（配置问题，ERROR）；
• 400+ 其他（如No audio received）→soniox_idle_timeout（VAD 饥饿，WARNING）；
• 402+organization_balance_exhausted→soniox_account_state（账户问题）；
• 413→soniox_rotation（文档化的轮换，应重开 WebSocket）；
• 其他 →connection_lost（兜底）。

这个分类在 SafeSonioxSocket._recv_loop 中生效：当错误帧的 typed reason 是soniox_account_state或soniox_invalid_hint时，记录ERROR（"服务端评估了账户/会话配置后拒绝服务，这是我们这边该修的"）；而空闲超时与轮换属于"协议在回答会话如何被使用"，保持 WARNING，不再让配置问题藏在 WARNING 里。同时原始错误文本会保留在死亡闩锁（death latch）上供日志排查，而 typed reason 进入有界的终端失败词汇表。

电路刻意不打开：谁该为死亡负责

在 backend/utils/stt/live_failure.py 的_CIRCUIT_OPENING_REASONS中，只有soniox_account_state和modulate_serve_error会触发提供商熔断。soniox_invalid_hint刻意不在其中，原因正是事故记录强调的：提供商是健康的，错的是我们的配置。对一个健康的提供商打开熔断电路，等于让一个用户（甚至一个语言）的错误配置演变成全量用户跳过 Soniox。session 级的死亡形态（空闲超时、hint 拒绝、413 轮换）都不应该株连全量流量。

同时，soniox_invalid_hint已被注册进_KNOWN_FAILURE_REASONS（live_failure.py），确保它进入终端失败词汇表后，会以phase='initialization'出现在omi_live_stt_terminal_failures_total（metrics.py，labels 为 provider、outcome、client_platform、deployment_environment、phase）中，值班人员一眼就能看出"会话死在初始化阶段"，而不是"用户没说话"。

验证：单元测试驱动真实的代码路径

事故记录列出的验证点全部有测试落地，集中在 backend/tests/unit/test_soniox_language_hint_vocabulary.py。这套测试的关键设计是：驱动真实的process_audio_soniox配置构建器与真实的SafeSonioxSocket接收循环，只 patch 掉websockets.connect传输层和 socket 构造，因此测试的是生产代码本身，而非模拟副本：

• 词汇表外语言不发 hint：test_an_out_of_vocabulary_language_sends_no_hint用'mt'验证'language_hints' not in config且enable_language_identification is True——这正是生产事故的精确形状；
• 词汇表内语言照常发 hint：test_a_supported_language_still_sends_its_hint（'ja'→['ja']）、test_a_region_tagged_locale_sends_its_normalized_base_code（'pt-BR'→['pt']）；
• 哨兵与大写输入：test_a_capitalized_sentinel_is_not_sent_as_a_hint（'Multi'不再泄漏）、test_the_auto_detect_sentinel_still_sends_no_hint（'multi'不发）、test_uppercase_input_sends_the_normalized_hint（'JA'→['ja']）；
• 回退事件：test_dropping_a_hint_emits_the_fallback_mode_change_event精确断言record_fallback的五元组参数；
• 严重级别分离：test_an_invalid_hint_frame_logs_at_error_not_warning驱动真实 socket 收一个 400 帧，断言日志级别是ERROR；test_a_no_audio_400_still_types_as_the_idle_timeout断言'No audio received'仍归soniox_idle_timeout；
• 电路不打开：test_the_invalid_hint_death_does_not_bench_the_healthy_providerpatch 掉open_provider_selection_circuit，断言对soniox_invalid_hint死亡零调用；
• 终端词汇表与 phase：test_a_terminal_funnel_reports_the_config_rejection_with_its_phase驱动真实 terminate 路径，断言客户端收到reason='soniox_invalid_hint'且指标 phase 为initialization；
• 产品承诺不变：test_selection_still_promises_soniox_for_an_out_of_vocabulary_language通过真实选择接口验证'mt'用户仍被选到 Soniox（只是不发 hint），test_every_modulate_language_is_also_hintable_at_soniox则保证"Modulate 能服务的语言在 Soniox 也一定可 hint"，避免主提供商故障切换到 Soniox 时走降级路径；
• 词汇表本身：test_the_vocabulary_size_pins_the_documented_table把词汇表钉在 60 个代码（en在内、multi与mt不在），防止误截断；test_every_documented_hint_code_is_a_real_base_code断言每个代码都是两字母基础代码。

结语：这起事故教给多提供商架构的三件事

1. 提供商"能力承诺"与"字段校验"是两回事。选择逻辑说"Soniox 支持所有语言"并没错——错的是把这一承诺延伸到了提供商按封闭词汇表校验的language_hints字段上。能力边界要精确到字段级：soniox_accepts_language_hint这样的 gate 只约束 hint 字段，不缩小选择范围。
2. 错误分类决定可观测性。一个 400 被无差别映射成soniox_idle_timeout，就把配置事故变成了"用户不说话"，日志级别从 ERROR 降到 WARNING、指标从 initialization 归到 connection，值班人员无从发现。修复的核心不是修一个语言代码，而是让类型（typed reason）、严重级别（ERROR/WARNING）、phase（initialization/connection）、指标四者保持一致。
3. 不要用熔断掩盖配置错误。熔断器是为"提供商不健康"设计的；当提供商健康、是我们的配置出错时，正确动作是修正配置并以record_fallback暴露降级，而不是让一个用户的问题株连全量流量。

这条"配置型死亡"的修复模式（静态能力表 + 字段级门控 + 类型化错误分类 + 针对性的回退遥测）同样适用于其他对封闭词汇表做校验的提供商集成，可作为 Friend 后端多提供商 STT 选型与运维的长期参考。同系列的 soniox-typed-rejections.md 记录了更早的 400/402/413 类型化拒绝演进，可一并阅读。

【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend