Realtime client_secrets: session.model silently overrides the Router’s resolved model when using model groups/aliases

快速结论：该报错发生在通过 LiteLLM Proxy 调用 `/v1/realtime/client_secrets` 接口，并使用模型组（model group）或别名（alias）时——当客户端传入的模型组名称与实际底层模型字符串不一致，`session.model` 会静默覆盖 Router 已正确解析出的真实模型，导致请求发送到错误的供应商模型。

适用环境：LiteLLM Proxy（版本 1.92.0、1.96.2 已确认复现；当前 main 分支代码路径未变）；任何使用模型组/别名配置 realtime 模型的部署环境；不特定于某一家模型供应商。

最快修复方案：暂无确认的一步修复方案。已提交修复 PR（#36749），等待合并。可优先尝试在 Router 层绕过该问题，或等待上游修复后升级版本。

注意事项：Issue 中提到的临时绕过方法（将 `session.model` 设为空字符串）依赖 Python 真值判断的偶然行为，作者明确表示这不是受支持的用法，不应作为生产环境长期方案。

问题场景

用户在 LiteLLM Proxy 中配置了 realtime 模型（如 Whisper、实时语音转写等），且使用模型组或别名方式管理多个部署。当客户端调用 `/v1/realtime/client_secrets`（或 `/realtime/client_secrets`、`/openai/v1/realtime/client_secrets`）接口时，如果未显式传入 `session` 或传入的 `session` 中不含 `model` 字段，代理会自行合成一个 session，其中包含的是客户端请求时使用的模型组名称（即别名），而非该组背后真实部署的模型字符串。最终发往供应商的请求会错误地携带这个未解析的别名。

报错原文

Realtime client_secrets: session.model silently overrides the Router's resolved model when using model groups/aliases

原因分析

根本原因涉及三层逻辑叠加，全部位于 `litellm/realtime_api/main.py` 和 `litellm/proxy/realtime_endpoints/endpoints.py` 中：

1. 当客户端未显式传 `session` 或 `session.model` 为空时，代理的 `_prepare_client_secret_session` 会使用客户端请求时传入的模型组/别名名称来合成 session，而不是真实部署名称。

2. `acreate_realtime_client_secret` 的模型解析逻辑是 (req.session.model if req.session is not None else None) or req.model or "gpt-4o-realtime-preview"，即 `session.model` 优先级高于 Router 已正确解析并传入的 `model` 参数。结合第一点，`session.model` 通常是路由前的别名，导致正确结果被丢弃。

3. `_with_resolved_session_model` 仅在 session 字典中已有 `model` 键时才用正确解析值覆盖。如果尝试通过完全移除 `session.model` 绕过第二点，则会触发另一个问题——转发请求的 session body 中完全没有 model 字段。

值得注意的是，该问题并非一直存在。Issue 作者检查 git 历史发现，在 commit b723dfb93dd8c0edd26f024fd91122e2aeb95376（2026-07-03）之前，逻辑是 model_name = req.model or (req.session.model ...)，即 Router 解析后的模型优先。该 commit 为修复另一个独立的 bug（`_with_resolved_session_model` 误覆盖调用方自定义的嵌套转录模型），同时将优先级翻转为 session 优先，且未考虑“调用方是代理自身、经由 Router 部署分发”的场景。

环境排查

LiteLLM Proxy 版本：1.92.0、1.96.2 均已确认复现；main 分支代码路径未修复
确认是否在 realtime 模型配置中使用了模型组（model group）或别名，且组名与实际底层模型字符串不一致
检查调用 `/v1/realtime/client_secrets` 时是否显式传入了 `session`，以及 `session` 中是否包含 `model` 字段
确认 Router 是否正确解析了部署（可观察日志中 Router 层日志确认解析结果）

解决步骤

确认问题存在：在 LiteLLM Proxy 上配置一个模型组，组名与实际模型名不同，调用 realtime client_secrets 接口，观察发送到供应商的请求是否携带了未解析的组名。
查看当前版本：执行 litellm --version（或对应你环境的版本查询方式），确认是否处于已受影响的版本范围。
尝试临时绕过：如确有紧急需求可优先尝试，在调用接口时将 `session.model` 显式设为空字符串（""），使步骤 3 的覆盖逻辑能填入正确值，同时因空字符串为 falsy，`or` 逻辑会回退到 Router 正确解析的模型。但作者明确提示这是依靠 Python 真值判断的偶然行为，不是官方支持的用法，不应在生产环境长期使用。
等待或手动应用修复：上游已提交修复 PR（#36749），方案仅在 Router 层重写 `session.model` 为解析后的实际部署名，不影响直接调用 SDK 函数（不经过 Router）的场景。可关注该 PR 合并情况，合并后升级 LiteLLM 版本。
如果自行编译部署：可参考 PR #36749 的改动，在 Router 层（_ageneric_api_call_with_fallbacks_helper）调用 realtime 函数前，将 `session.model` 覆盖为已解析的 deployment 名称。

验证方法

修复后，使用与之前相同的模型组名称调用 `/v1/realtime/client_secrets` 接口，检查最终发送到供应商的请求中 `session.model`（或对应请求体字段）是否为 Router 解析后的真实模型字符串，而非组名/别名。可通过代理日志或抓包确认。若使用临时空字符串方案，同样确认最终发出请求携带的是真实模型名。