NVIDIA-NeMo/Switchyard

Switchyard 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.

Switchyard – 面向 LLM 调用的成本感知路由

是什么 – Switchyard 是一个轻量级的路由层，位于一个或多个大语言模型（LLM）提供商之前。对于每个请求，它基于可配置的算法决定是将调用发送到廉价的“高效”模型，还是发送到更强大（通常也更昂贵）的模型，旨在在保持任务准确性的前提下降低总体成本。

为何重要 – 在许多面向代理的工作负载中，单个强大模型对大多数轮次来说是过度的。通过仅自动“升级”困难情况，Switchyard 可在成功率仅轻微下降（或甚至略有提升）的情况下，将令牌成本降低 13–30%，如 Terminal-Bench 2.1 基准测试所示。

核心组件（预 1.0 版）

组件	稳定性	作用
`switchyard-libsy`	Beta	纯 Rust 库，暴露路由算法。可嵌入您自己的网关或框架中；您可自行控制 HTTP 调用、重试和凭据。
`switchyard-llm-client`	Alpha	帮助程序，用于在库的中立请求/响应类型与真实 HTTP LLM API 之间进行转换。
`switchyard-runner`	Alpha	桥接代码，可在其他运行时（如 NeMo Relay）中运行路由配置。
`switchyard-server`	演示	独立代理，模拟 OpenAI/Anthropic 端点；适用于快速演示或评估。

如何使用

NeMo Relay 插件 – 将 routes.toml 文件加载到现有的 NeMo Relay 部署中。插件处理对选定提供者的 HTTP 分发，而 Relay 保持其常规的传输和重试逻辑。
嵌入库 – 安装 Python 包（pip install nemo-switchyard）或在项目中添加 Rust crate。构建一个路由算法（例如 stage_router(picker="efficient_first", confidence_threshold=0.5)），并使用 run_stream 循环驱动，向模型特定的 HTTP 客户端提供输入。
独立代理 – 安装 Rust 二进制文件（cargo install switchyard-server），编写一个简单的 routes.toml 将目标 ID 映射到 OpenRouter（或任何 OpenAI 兼容）端点，然后启动服务器。任何 OpenAI/Anthropic 客户端现在都可以指向 http://localhost:4000，并自动受益于路由功能。

路由算法（在 TOML 配置中选择一个）

能力（llm_classifier） – 首个请求由一个小 LLM 判断；如果认为任务困难，则调用被升级。
阶段（stage_router） – 在决定是否切换模型之前，对工具生成的响应使用模式匹配或裁判 LLM 进行评估。
升级 – 从廉价模型开始，然后对结果运行裁判 LLM；如果检测到问题，则请求将重新发送到强大模型。
随机 / 建议 / 子代理感知 / 自定义 – 其他各种用于实验的策略。

快速上手（Python 示例）

from switchyard.libsy import LlmResponse, Step
from switchyard.libsy.algorithms import stage_router

algorithm = stage_router(picker="efficient_first", confidence_threshold=0.5)

async def route(request, clients):
    async for step in algorithm.run_stream(request, {
        "efficient": ["fast"],
        "capable":   ["quality"],
    }):
        if isinstance(step, Step.CallModel):
            # 为每个候选模型调用您自己的 HTTP 客户端
            resp = await clients[step.models[0]].call(step.request)
            step.respond(LlmResponse.Agg(resp))
        elif isinstance(step, Step.Done):
            return step.outcome.response

Rust 中也存在相同逻辑；switchyard-libsy crate 提供了 Algorithm::run_stream 迭代器。

成熟度与许可

该项目为 预 1.0 版；API 和配置格式可能会更改，因此集成时请固定版本。
服务器组件标记为演示，目前不建议用于生产环境。
许可证为 Apache 2.0（NVIDIA Corporation）。