LiteLLM + Switchyard路由插件：在LiteLLM里跑阶段路由的完整方案

LiteLLM + Switchyard路由插件：在LiteLLM里跑阶段路由的完整方案

【免费下载链接】SwitchyardSwitchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.项目地址: https://gitcode.com/GitHub_Trending/switch/Switchyard

Switchyard 是一个 LLM 流量路由工具，让 LLM 应用在保留原生 OpenAI 与 Anthropic API 兼容性的同时，在多个模型与服务商之间灵活分发请求，实现灵活选模、基准对比与成本/性能优化。本文结合官方 LiteLLM 路由插件，完整演示在 LiteLLM 中部署阶段路由（Stage Routing）的每一步，面向新手，从零跑通只需 5 分钟。

🧭 Switchyard 路由插件解决什么问题？

LiteLLM 是 LLM 应用常用的统一网关：把几十种厂商模型收敛成一个 OpenAI 兼容接口。但"能调用"不等于"会调度"——每次请求该用哪个模型，往往才是成本和质量的真正瓶颈。

Switchyard 路由插件正好插在 LiteLLM 原生的路由插件边界上，同一个插件对象承担两个角色：

1. 部署选择之前：把 LiteLLM 的候选模型集合，收窄为 Switchyard 算法选定的那一个模型；
2. 部署选择之后：在 LiteLLM 翻译并发送请求前，应用算法产生的请求改写（如工具、采样参数等）。

应用侧一行代码都不用改：继续用 LiteLLM 的Router或 OpenAI 兼容代理，凭证、重试、厂商翻译仍归 LiteLLM 管，插件只负责"选哪个模型、怎么微调请求"。

⚠️ 兼容性边界：插件走的是"只决策"路径，因此 Stage、Random 这类决策型算法可用；Escalation、LLM 分类器这类需要中途额外调用一次模型的路由器不支持。完整行为矩阵见 examples/litellm/README.md。

⚙️ 阶段路由如何工作：成本与质量兼得

Stage 算法围绕两个候选模型分工协作：

• capable（强模型）：处理有难度的请求；
• efficient（高效模型）：默认优先接活，压低成本。

内置配置的picker = "efficient_first"表示默认走高效档；当近期对话中检测出失败信号（例如工具调用报错），Stage 就升级到强模型，并可自动追加"升级说明"与分档 system prompt；问题解决后还能带着"降级说明"切回高效档。整份 stage 配置只有 9 行：

algorithm = "stage" picker = "efficient_first" confidence_threshold = 0.5 recent_window = 3 only_on_wrong_signal_escalation = true

字段速查：

完整文件见 examples/litellm/deployment/profiles/stage/switchyard.toml。

🎯顺序陷阱：litellm.yaml中必须先声明强模型、后声明高效模型，顺序直接对应角色划分。参考 examples/litellm/deployment/profiles/stage/litellm.yaml。

🚀 本地代理最快启动方法

前置条件：Docker Compose + 一个 OpenRouter key（示例 profile 使用两个 OpenRouter 模型作演示值，可自行替换）。

git clone https://gitcode.com/GitHub_Trending/switch/Switchyard cd Switchyard/examples/litellm/deployment cp .env.example .env # 在 .env 中填入 OPENROUTER_API_KEY docker compose -f compose.yaml up -d --build --wait curl -fsS http://127.0.0.1:4000/health/liveliness

向公共模型组switchyard发一条请求：

curl -i http://127.0.0.1:4000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"switchyard","messages":[{"role":"user","content":"Reply with the word hello."}],"max_tokens":64}'

注意两个关键细节：

• 响应体里的model字段保持为公共组名switchyard；
• 真正被 Switchyard 选中的模型，由响应头x-litellm-model-name标明——这是验证路由生效的第一入口。

想换成随机路由 profile？不用改任何文件：

SWITCHYARD_LITELLM_PROFILE=random docker compose -f compose.yaml up -d --build --wait

容器编排文件为 examples/litellm/deployment/compose.yaml：默认只监听本机回环地址127.0.0.1:4000，未启用鉴权，适合本地开发；对外暴露前请先按 LiteLLM 的指引配置认证。

📝 自定义一个阶段路由 Profile

examples/litellm/deployment/profiles/ 下每个子目录就是一个完整 profile，由两个文件组成、职责清晰：

• litellm.yaml—— 模型清单、凭证、厂商参数（LiteLLM 负责）；
• switchyard.toml—— 算法及其全部参数（Switchyard 负责）。

例如 random profile 的算法配置只有两行：examples/litellm/deployment/profiles/random/switchyard.toml，还支持weights为各候选模型指定权重、seed固定随机行为。

新增 profile 三步走：复制现有目录 → 改两个文件 → 用目录名启动。静态错误（缺文件、TOML 写错、字段类型不符）会在代理启动时直接报出；依赖实时候选列表的约束（如 Stage 要求恰好两个候选）则在请求时报错。

🐍 Python Router 直接集成（不走代理）

也可以在长驻 Python 应用中直接构造插件，跳过代理部署：

import litellm from litellm import Router from switchyard_litellm import StageRoutingPlugin plugin = StageRoutingPlugin( picker="efficient_first", confidence_threshold=0.5, recent_window=3, ) router = Router(model_list=model_list, plugins=[plugin]) litellm.callbacks.append(plugin) # 构造器不接受部署回调，需手动注册一次

完整可运行示例在 examples/litellm/examples/python_router.py：它模拟了一段"pytest 工具调用失败"的对话历史，验证 Stage 会升级选中强模型。运行方式：

uv sync --locked --python 3.12 uv run --locked --env-file deployment/.env python examples/python_router.py

🔍 可观测性：插件留下了什么信号？

路由决策成功后，插件会在 LiteLLM 的请求上下文里写入：

• selected_model_id：最终选定的模型；
• fallback_models：仅作诊断用的元数据，不会转化为 LiteLLM 的 fallback 策略。

若算法同时改写了受支持的字段，信号中会临时附带一个私有request_patch；回调在部署选择完成后消费它，并在返回下游前剔除——私有的改写细节不会泄漏到后续链路。

🛠️ 常见问题快速排查

📚 延伸阅读与源码路径

• 插件完整文档（含请求流程图与兼容矩阵）：examples/litellm/README.md
• Stage 路由算法设计：docs/routing_algorithms/stage_router_routing.md
• Random 路由算法设计：docs/routing_algorithms/random_routing.md
• 全部路由算法总览：docs/routing_algorithms/overview.md
• 插件 Python 源码：examples/litellm/src/switchyard_litellm/
• Stage 算法 Rust 实现：crates/lbsy/src/algorithms/stage.rs

【免费下载链接】SwitchyardSwitchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.项目地址: https://gitcode.com/GitHub_Trending/switch/Switchyard