1. Switchyard 简介

Switchyard 是一款用 Rust 编写的代理和库，专为处理大语言模型（LLM）的流量而设计。它能够在不同的模型提供商之间路由请求，实现 OpenAI 和 Anthropic API 之间的转换，记录操作指标，并提供类型化、可组合的路由算法。

2. 为何选择 Switchyard？

你可以将像 Claude Code 或 Codex 这样的编码代理指向开源模型。Switchyard 能在 OpenAI Chat、Anthropic Messages 和 OpenAI Responses 等格式之间进行转换，这样编码代理可以继续使用其原生 API，而请求则由 vLLM、NVIDIA NIM、Ollama 或任何兼容 OpenAI 的端点来处理。同一个代理还能将流量分散到多个模型，用于 A/B 测试、应用基于信号的阶段路由，或者运行你自己编写的自定义算法。

3. 主要特性

协议转换：支持在 OpenAI Chat、Anthropic Messages 和 OpenAI Responses 格式之间进行转换。多后端路由：提供随机路由、以大语言模型作为分类器的路由、基于信号的阶段路由，也支持你自定义算法。操作指标：通过 Prometheus 指标记录请求、错误、延迟、令牌数量和路由开销等信息。

4. 成熟度

Switchyard 目前处于预 alpha 阶段，仍在快速发展。在达到 v1.0 版本之前，其 API 和算法预计会有重大变化。请注意，这是实验性软件，请勿用于生产环境。

5. 快速开始

你可以根据需求选择以下三种使用方式：启动器方式：通过 Switchyard 运行 Claude Code、Codex CLI 或 OpenClaw。若尚未安装 uv，需先进行安装，然后安装已发布的 Switchyard 工具：
curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
uv tool install --python 3.10 "nemo-switchyard[cli]"
你启动的编码代理也必须安装并在系统的 PATH 环境变量中。此方式不会安装独立的 switchyard - server 二进制文件，若要安装，请使用服务器方式。设置 OpenRouter 密钥并针对打包部署进行启动：
export OPENROUTER_API_KEY="your - openrouter - key"
switchyard launch claude --model switchyard
switchyard launch codex --model switchyard
switchyard launch openclaw --model switchyard
若要使用你自己的原生 TOML 部署，需传递其路由 ID 和配置：
switchyard launch claude --model my - route --config routes.toml
服务器方式：用于安装和运行独立的 Rust 代理。使用 Cargo 安装 Rust，然后安装已发布的二进制文件：
cargo install --locked switchyard - server
switchyard - server --help
Cargo 默认会将发布版二进制文件构建并安装到 `~/.cargo/bin` 目录。根据快速上手指南创建 `routes.toml` 文件，然后验证并启动服务器：
export OPENROUTER_API_KEY="your - openrouter - key"
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` 配合使用。在 `Cargo.toml` 中添加以下依赖：
[dependencies]
switchyard - libsy = { git = "https://github.com/NVIDIA - NeMo/Switchyard.git" }
switchyard - protocol = { git = "https://github.com/NVIDIA - NeMo/Switchyard.git" }
有关设置和算法列表，请参考快速上手指南或 `switchyard - libsy` 包文档。

6. 路由策略

| 策略 | 使用场景 | 路由类型 |
| ---- | ---- | ---- |
| LLM 分类器 | 请求内容应决定某个回合需要使用弱层级还是强层级模型。 | llm_classifier |
| 阶段路由 | 对话中已有的信号（如工具结果和错误）应在无需额外模型调用的情况下对大多数回合进行路由。 | stage_router |
| 升级路由 | 每个回合先在弱层级模型上运行，然后由评判器根据结果决定是否将相同请求发送到强层级模型。 | llm_classifier（模式为 "escalation"） |
| 随机路由 | 你需要为 A/B 测试、基线测试或成本实验进行固定的流量分配。 | random |
直通路由会在一个模型 ID 下注册一个目标，无需进行路由决策。有关常见路由形状和自托管目标的详细信息，请参考路由概述。

7. 架构

客户端保持其原生的 OpenAI 或 Anthropic API 格式。Switchyard 会选择一个已配置的后端，将请求以该后端的格式转发，并将响应转换回客户端期望的格式。服务器支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages。每个配置的大语言模型客户端会选择一种上游格式。

8. 文档

快速上手：提供完整的启动器和独立服务器使用指南。核心概念：介绍大语言模型客户端、目标、路由、模型 ID 和路由算法等概念。路由概述：帮助你选择和配置路由算法。switchyard - server：介绍服务器配置、路由算法和指标。switchyard - libsy：说明如何将路由算法嵌入到 Rust 应用程序中。switchyard - protocol：提供与提供商无关的请求、响应和流式传输类型。switchyard - translation：介绍请求、响应和流的转换。

9. 社区

问题反馈：可在 GitHub Issues 上提交问题。行为准则：请遵守行为准则。

10. 许可证

采用 Apache 2.0 许可证，版权归 NVIDIA Corporation 所有。