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-listenLoop 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马耳他语App 层面接受mt作为用户语言批处理 Parakeet 模型的 25 语言列表里确实包含mt见 PARAKEET_SUPPORTED_LANGUAGES_BY_MODEL 中parakeet-tdt-0.6b-v3的集合mt在列但 Modulate 的自动检测表不包含mt对照 MODULATE_SUPPORTED_LANGUAGES其中没有mt所以该用户在选择链路上跳过 ModulateSoniox 被选中因为选择逻辑对 Soniox 的承诺是什么语言都能服务客户端把language_hints: [mt]发给 Soniox而mt不在 Soniox 的 hint 词汇表中配置帧即被拒socket 死亡Soniox 分支自己的回退也是空的modulate_is_configured_fallback(mt)返回FalseDeepgram 没有mt模型于是没有任何提供商可救援结果每次重连都复现同样的死亡只要用户不关 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。这带来两个后果日志级别失真这类死亡被记为 WARNING含义是协议在回答这个会话是怎么被使用的即用户没说话、VAD 饿死了而真相是我们的配置违反了提供商的封闭词汇表指标失真在omi_live_stt_terminal_failures_total中它们被计为 VAD 空闲超时VAD-starvation而不是配置拒绝。于是一个配置 bug 穿着使用 bug 的服装对值班人员完全不可见——顶层错误签名里它被归类成用户不说话没人会去查配置。这解释了为什么它能在生产环境持续 16 小时而不被发觉。修复后的契约一张表说清所有行为事故记录用一张表格定义了修复后的行为契约这是理解整个修复的核心关注点修复后行为是否发送 hint仅当规范化基础代码在SONIOX_SUPPORTED_LANGUAGE_HINTS提供商文档词汇表内时才发送不支持的语音不发送 hint由enable_language_identification服务会话自动检测支持模型所支持的全部语言同时调用record_fallback(componentstt_selection, from_modesoniox_language_hint, to_modesoniox_language_identification, reasoncapability_mismatch, outcomedegraded)—— 静默修复用户体验可以静默掩盖运维信号不行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 日志且所有标签都要落在封闭的枚举内componentstt_selection、reasoncapability_mismatch、outcomedegraded都在各自允许集合中见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 端点动态获取支持语言事故记录给出了明确的工程权衡词汇表是文档化、带版本的。SONIOX_SUPPORTED_LANGUAGE_HINTS对应的是提供商文档中针对单一统一模型stt-rt-v5的支持语言页面按部署节奏维护策略归位。把词汇表放在 backend/config/stt_provider_policy.py 里与其他能力表MODULATE_SUPPORTED_LANGUAGES、PARAKEET_SUPPORTED_LANGUAGES_BY_MODEL并列意味着提供商词汇表变更 在唯一拥有提供商能力归属的模块里做一次经过评审的改动与既有的MODULATE_SUPPORTED_LANGUAGES、PARAKEET_SUPPORTED_LANGUAGES_BY_MODEL模式完全一致零收益的网络依赖。认证 Get-models 端点会为选择链路引入一个启动期的网络依赖启动失败 无法选择提供商而今天它带来的行为差异为零——因为选择的承诺本来就不依赖 hinthint 只是可选项。这个决策的核心理念是能力表是代码所有code-owned而非环境所有environment-owned。正如 stt_provider_policy.py 模块 docstring 所写改变一个提供商的可用性要求一次经过评审的改动部署清单可以调整顺序但不能复活一个不在策略里的提供商。源码级实现修复落在哪里词汇表60 个代码的frozensetSONIOX_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 顺序是normalized normalized_stt_language(language)先规范化切-/_后缀 小写得到基础代码if normalized and normalized ! multi此时比较的是规范化后的值Multi已经变成multi不会再泄漏调用soniox_accepts_language_hint(normalized)做词汇表门控在词汇表内 →config[language_hints] [normalized]不在词汇表内 → 触发record_fallbackfrom_modesoniox_language_hint→to_modesoniox_language_identificationreasoncapability_mismatchoutcomedegraded并记录一条Soniox language hint dropped: ...的 WARNING 日志然后不带 hint继续连接。normalized_stt_language 的实现是language.split(-)[0].split(_)[0].lower()它统一了所有提供商的比较基准——ja-JP→jaEN_us→en。死亡分类从 free-text 到有界词汇表修复后的 soniox_death_reason 按error_codeerror_typeerror_message三元组分类400 消息包含invalid language hint→soniox_invalid_hint配置问题ERROR400 其他如No audio received→soniox_idle_timeoutVAD 饥饿WARNING402organization_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_REASONSlive_failure.py确保它进入终端失败词汇表后会以phaseinitialization出现在omi_live_stt_terminal_failures_totalmetrics.pylabels 为 provider、outcome、client_platform、deployment_environment、phase中值班人员一眼就能看出会话死在初始化阶段而不是用户没说话。验证单元测试驱动真实的代码路径事故记录列出的验证点全部有测试落地集中在 backend/tests/unit/test_soniox_language_hint_vocabulary.py。这套测试的关键设计是驱动真实的process_audio_soniox配置构建器与真实的SafeSonioxSocket接收循环只 patch 掉websockets.connect传输层和 socket 构造因此测试的是生产代码本身而非模拟副本词汇表外语言不发 hinttest_an_out_of_vocabulary_language_sends_no_hint用mt验证language_hints not in config且enable_language_identification is True——这正是生产事故的精确形状词汇表内语言照常发 hinttest_a_supported_language_still_sends_its_hintja→[ja]、test_a_region_tagged_locale_sends_its_normalized_base_codept-BR→[pt]哨兵与大写输入test_a_capitalized_sentinel_is_not_sent_as_a_hintMulti不再泄漏、test_the_auto_detect_sentinel_still_sends_no_hintmulti不发、test_uppercase_input_sends_the_normalized_hintJA→[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 帧断言日志级别是ERRORtest_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死亡零调用终端词汇表与 phasetest_a_terminal_funnel_reports_the_config_rejection_with_its_phase驱动真实 terminate 路径断言客户端收到reasonsoniox_invalid_hint且指标 phase 为initialization产品承诺不变test_selection_still_promises_soniox_for_an_out_of_vocabulary_language通过真实选择接口验证mt用户仍被选到 Soniox只是不发 hinttest_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断言每个代码都是两字母基础代码。结语这起事故教给多提供商架构的三件事提供商能力承诺与字段校验是两回事。选择逻辑说Soniox 支持所有语言并没错——错的是把这一承诺延伸到了提供商按封闭词汇表校验的language_hints字段上。能力边界要精确到字段级soniox_accepts_language_hint这样的 gate 只约束 hint 字段不缩小选择范围。错误分类决定可观测性。一个 400 被无差别映射成soniox_idle_timeout就把配置事故变成了用户不说话日志级别从 ERROR 降到 WARNING、指标从 initialization 归到 connection值班人员无从发现。修复的核心不是修一个语言代码而是让类型typed reason、严重级别ERROR/WARNING、phaseinitialization/connection、指标四者保持一致。不要用熔断掩盖配置错误。熔断器是为提供商不健康设计的当提供商健康、是我们的配置出错时正确动作是修正配置并以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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考