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/SwitchyardSwitchyard 是一个 LLM 流量路由工具让 LLM 应用在保留原生 OpenAI 与 Anthropic API 兼容性的同时在多个模型与服务商之间灵活分发请求实现灵活选模、基准对比与成本/性能优化。本文结合官方 LiteLLM 路由插件完整演示在 LiteLLM 中部署阶段路由Stage Routing的每一步面向新手从零跑通只需 5 分钟。 Switchyard 路由插件解决什么问题LiteLLM 是 LLM 应用常用的统一网关把几十种厂商模型收敛成一个 OpenAI 兼容接口。但能调用不等于会调度——每次请求该用哪个模型往往才是成本和质量的真正瓶颈。Switchyard 路由插件正好插在 LiteLLM 原生的路由插件边界上同一个插件对象承担两个角色部署选择之前把 LiteLLM 的候选模型集合收窄为 Switchyard 算法选定的那一个模型部署选择之后在 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字段速查字段作用picker无信号时的默认档位efficient_first或capable_firstconfidence_threshold升级判定置信阈值0–1recent_window扫描失败信号的最近轮数escalation_note/deescalation_note上下档交接时自动追加的上下文说明capable_system_prompt/efficient_system_prompt各档位专属的系统指令完整文件见 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_PROFILErandom docker compose -f compose.yaml up -d --build --wait容器编排文件为 examples/litellm/deployment/compose.yaml默认只监听本机回环地址127.0.0.1:4000未启用鉴权适合本地开发对外暴露前请先按 LiteLLM 的指引配置认证。 自定义一个阶段路由 Profileexamples/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( pickerefficient_first, confidence_threshold0.5, recent_window3, ) router Router(model_listmodel_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回调在部署选择完成后消费它并在返回下游前剔除——私有的改写细节不会泄漏到后续链路。️ 常见问题快速排查症状排查方向Compose 提示缺少 key把OPENROUTER_API_KEY放进deployment/.env或用--env-file指定其他文件启动时报SWITCHYARD_LITELLM_CONFIG检查所选 profile 是否含可读的switchyard.tomlalgorithm与字段值是否匹配端口 4000 被占用启动前设置LITELLM_PORT并用新端口发请求服务一直不健康docker compose -f deployment/compose.yaml logs litellm看日志请求才报路由失败先核对 Stage 的候选顺序/数量、Random 的权重数量再检查消息格式 延伸阅读与源码路径插件完整文档含请求流程图与兼容矩阵examples/litellm/README.mdStage 路由算法设计docs/routing_algorithms/stage_router_routing.mdRandom 路由算法设计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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考