ModuleNotFoundError: No module named ‘semantic_router’

快速结论：这个报错通常发生在已启用 complexity_router（`auto_router`）的 LiteLLM 代理环境中，调用请求进入路由层时，`semantic_router` 相关模块未能被导入。优先排查该模块是否已安装、是否装在了 LiteLLM 实际使用的同一个 Python 环境里，以及代理进程启动时的依赖路径。

适用环境：Issue 中已确认的环境为 LiteLLM 1.105.0 自托管代理，使用 `complexity_router`（`auto_router`）多层级配置，`max_tokens_from_tier_model` 保持默认值（`true`），tiers 以普通模型名配置且未逐层固定输出上限；测试环境为 Python 3.12，依赖来自 `litellm[proxy] 1.105.0`。Issue 未提供操作系统、CUDA、显卡、PyTorch 等信息。

最快修复方案：暂无确认的一步修复方案。Issue 讨论聚焦 complexity_router 对调用方 `max_tokens` 的覆盖行为，并未给出该导入错误的验证过修复步骤。

注意事项：当前结论属于基于报错名称和 Issue 环境的排查方向，不是该 Issue 已验证的解决方案。Issue 原文记录的“clamp”模式验证针对的是 `max_tokens` 覆盖问题（PR #45556），不能据此推断它修复了 `semantic_router` 导入错误。

问题场景

用户在 LiteLLM 1.105.0 自托管代理中启用 `complexity_router`（`auto_router`）并配置多个层级模型，请求经过自动路由时触发模块导入失败。该 Issue 本身讨论的是 complexity_router 会把调用方较小的 `max_tokens` 替换为层级上限，但在同一条路由链路上暴露出 `semantic_router` 模块缺失的导入错误。

报错原文

ModuleNotFoundError: No module named 'semantic_router'

原因分析

最直接的原因是当前运行 LiteLLM 代理的 Python 环境中没有名为 `semantic_router` 的模块，而 complexity_router 的自动路由实现需要导入它。可能原因包括：安装 LiteLLM 时没有安装该可选依赖；代理进程与实际安装依赖的虚拟环境不是同一个；依赖装在系统 Python 而代理运行在容器或其他解释器中（后者为推测，Issue 未给出容器内报错细节）。

环境排查

确认 LiteLLM 版本与配置：Issue 中为 1.105.0，使用 `complexity_router`（`auto_router`），`max_tokens_from_tier_model` 为默认 `true`。
确认 Python 版本：Issue 测试环境为 Python 3.12。
确认依赖安装来源：Issue 使用 `litellm[proxy] 1.105.0`。
确认代理进程使用的解释器或容器镜像，与安装依赖的环境是否一致。
Issue 未提供 CUDA、显卡、PyTorch 信息，无需按这些项排查。

解决步骤

先确认报错发生的运行环境：检查启动 LiteLLM 代理所使用的 Python 解释器，是否为安装 `litellm[proxy]` 依赖的同一个环境。
核对复杂度路由配置：确认使用的是 `complexity_router`（`auto_router`），并记录 `max_tokens_from_tier_model` 的取值，以判断是否属于本 Issue 讨论的覆盖行为。
确认当前 LiteLLM 版本与隔离环境：Issue 中可安装的稳定基础版本为 1.105.0，Python 为 3.12；若使用容器镜像，需检查镜像内是否包含路由所需依赖。
若环境一致仍报错，可优先尝试在代理实际运行的环境中补齐 `semantic_router` 依赖，或改用已包含该依赖的 LiteLLM 安装方式；此项为排查方向，Issue 未验证。
如问题与调用方 `max_tokens` 被层级上限覆盖有关，可参考 PR #45556 引入的可选 `”clamp”` 模式；该 PR 验证的是覆盖行为，不是导入错误的修复。

验证方法

重新启动代理并发送一次经过 `auto_router` 的请求，确认不再出现 ModuleNotFoundError: No module named 'semantic_router'。同时可观察请求实际携带的 `max_tokens`：Issue 的验证中，默认 `true` 会把调用方 2,000 替换为层级上限 64,000，`”clamp”` 模式下保持 2,000；调用方未传或传 0 时仍使用层级上限。