Switchyard

项目动机

Switchyard 是一个基于 Rust 的 LLM 流量代理与路由库。它主要用于让 Claude Code、Codex 这类编码代理以原生 API 形式请求第三方模型，再由 Switchyard 将请求在 OpenAI Chat、Anthropic Messages、OpenAI Responses 三种协议之间互译，转发到 vLLM、NVIDIA NIM、Ollama 或任意 OpenAI 兼容端点。同一代理实例还可对多个模型做流量切分、A/B 对比，或接入自定义路由算法。

核心特性

• 协议转换：在 OpenAI Chat、Anthropic Messages、OpenAI Responses 之间双向翻译
• 多后端路由：内置随机路由、LLM 分类路由、信号驱动的阶段路由，也支持自定义算法
• 可观测指标：导出 Prometheus 指标，覆盖请求数、错误、时延、Token 消耗与路由开销
• 成熟度：当前为 pre-alpha，API 与算法在 v1.0 之前仍可能发生较大调整，仅供实验使用

技术架构

客户端以 OpenAI 或 Anthropic 原生协议接入 Switchyard；Switchyard 根据路由策略选择已配置的后端，按目标后端的原生格式转发，并把响应翻译回客户端所期望的形态。服务端统一接收 OpenAI Chat Completions、OpenAI Responses 与 Anthropic Messages，每条路由的目标端则按上游原生格式出站。

服务器模式使用

cargo install --locked switchyard-server
switchyard-server --help

安装后创建 routes.toml（参见官方 Getting Started 指南），先做 dry-run 校验，再启动：

export OPENROUTER_API_KEY="your-openrouter-key"   # pragma: allowlist secret
switchyard-server --config routes.toml --dry-run
switchyard-server --config routes.toml --host 127.0.0.1 --port 4000

服务启动后可在另一终端验证：

curl http://localhost:4000/health

库模式使用

switchyard-libsy 把路由算法嵌入既有 Rust 应用，不内置 HTTP 层；算法决定目标端，再把模型调用交回宿主，适合嵌入现有代理、网关或代理运行时。若希望由库直接发起模型调用，可与 switchyard-llm-client 搭配使用。

[dependencies]
switchyard-libsy    = { git = "https://github.com/NVIDIA-NeMo/Switchyard.git", tag = "v0.2.0" }
switchyard-protocol = { git = "https://github.com/NVIDIA-NeMo/Switchyard.git", tag = "v0.2.0" }

路由策略速查

此外，passthrough 类型路由可在单一模型 ID 下挂接单个目标，不做任何路由决策。

配置示例与文档入口

完整配置结构、路由条目示例以及自托管目标端说明，可查阅路由算法概览文档。进一步的配置、指标和算法实现细节分别由 switchyard-server、switchyard-libsy、switchyard-protocol、switchyard-translation 四个 crate 的文档承载。问题反馈通过 GitHub Issues 提交，项目遵循 Apache 2.0 许可证，版权归 NVIDIA Corporation 所有。