NVIDIA Switchyard：让编程 Agent 自由换模型

给编程 Agent 换模型，最容易翻车的往往不是模型能力，而是协议。Claude Code 期待 Anthropic Messages，Codex 走 OpenAI Responses，本地 vLLM 多半只暴露 Chat Completions。接口地址填上了不代表真能跑，到了并行 tool call、流式输出和重试环节，问题才会一股脑冒出来。

NVIDIA NeMo Switchyard 就卡在这个缝里：它负责协议转换、模型路由和调用统计，让 Claude Code、Codex、OpenClaw 不改客户端，也能接 NVIDIA NIM、vLLM、Ollama、OpenRouter 等后端。

先说结论

• Switchyard 不是模型，而是开源 LLM proxy、协议转换器和路由器。
• 最实用的能力，是让现有编程 Agent 接入原本不兼容的模型后端。
• 简单任务可以走便宜模型，复杂任务再升级到强模型。
• 多一层 proxy 就多一层故障点，timeout、日志脱敏和协议回归测试不能省。
• 如果团队在乎模型可迁移性，它很值得试；只用一家云厂商时，未必需要。

三套 API 看起来差不多，细节完全不是一回事

OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 都能传对话、工具和模型输出，但 tool ID、stream event、reasoning 字段、stop reason、错误结构并不一致。

普通聊天可能凑合转换一下就能用。编程 Agent 不行。一个稍大的任务会产生几百次 tool call，任何一个事件顺序错位，都可能让客户端一直转圈，或者把已经执行过的工具再跑一遍。

Switchyard 官方仓库明确支持 OpenAI Chat、Anthropic Messages 与 OpenAI Responses 之间的转换。来源：NVIDIA NeMo。

它把处理链固定成下面这个形状：

request components -> LLM backend -> response components -> translation engine

这个设计看着朴素，实际很关键。认证、路由、buffer、日志都能分别替换，但一条合法链路只调用一次模型后端，最后再把结果翻译成客户端认识的格式。边界清楚，调试时不容易抓瞎。

先把 Claude Code 跑起来

安装包叫 nemo-switchyard，Python import 和 CLI 却叫 switchyard。第一次装时很容易以为找错包了。

python -m venv .venv
source .venv/bin/activate
python -m pip install "nemo-switchyard[cli,server]"

switchyard launch claude

Codex 和 OpenClaw 也有专门的 launcher：

switchyard launch codex
switchyard launch openclaw

如果要做长期配置，凭证要单独传，不要顺手塞进 routing YAML：

switchyard configure \
  --target provider \
  --provider openrouter \
  --api-key "$OPENROUTER_API_KEY" \
  --base-url https://openrouter.ai/api/v1 \
  --no-tui \
  --no-model-discovery

Switchyard 给 Claude Code、Codex 和 OpenClaw 做了单独的启动入口，省掉手工改一堆客户端配置。

真正有用的是按任务难度路由

把所有请求转到一个本地模型，只能证明链路通了。Switchyard 更有价值的地方，是把一个虚拟模型名映射到不同后端，支持固定模型、随机路由、classifier 路由、信号驱动升级和自定义逻辑。

工作方式可以概括成 5 步：

1. 编程 Agent 始终请求同一个虚拟模型。
2. request component 提取任务信号。
3. router 选择便宜模型或强模型。
4. 发生 context overflow、后端异常或低置信度时切换兜底。
5. 按 route 记录延迟、token、成本和失败率。

这比 round robin 靠谱得多。搜文件、改格式、补一行测试，用便宜模型就够了；跨模块重构、架构决策、工具错误恢复，再交给强模型。编程任务不是同一种请求平均分桶。

配置字段会随版本演进，我不在这里贴一份假装永远有效的完整 YAML。上线前应该以官方仓库当前的 example 为准，并把配置校验放进 CI。

Switchyard、LiteLLM 和云厂商路由怎么选

需求	Switchyard	LiteLLM	云厂商原生路由
Claude Code/Codex 换后端	最合适	能做，但配置更多	通常不是重点
三类主流协议互转	核心能力	通用 gateway 能力	主要服务自家生态
接 vLLM/Ollama	支持	支持	通常不支持
自定义路由	Profile 与 component	callback 与 routing policy	受产品规则限制
运维方式	自托管	自托管或托管	托管
运维负担最低	否	否	是

客户端不能换、模型想自由选，优先看 Switchyard。大量不同应用都需要统一模型入口，LiteLLM 更通用。如果模型本来全在一家云上，又不想维护 proxy，直接用云厂商的 router 更省心。

相关选型可以继续看 LiteLLM vs OpenRouter；如果 Agent 会执行生成的代码，还要配合 AI Agent Sandbox 对比 里的隔离方案。

上生产后最容易踩的 4 个坑

Stream 事件少一条，客户端就可能一直等

后端已经生成完，客户端却还在转圈，这类问题最难受。回归测试要覆盖事件顺序、tool-call ID、finish reason、并行工具和中途错误，不能只拿一个 curl 看 HTTP 200。

Proxy 会吃掉一部分 timeout

分类、协议转换、重试都会增加耗时。route selection、模型请求、stream idle 最好分别设 timeout。只配一个全局 120 秒，出事后根本不知道慢在哪层。

不同模型的 context window 不一样

弱模型和强模型未必有同样的 context 上限。路由前应该预留 headroom，而不是等 200K token 的请求依次撞上 3 个 128K 模型。那不是容错，只是把一次确定失败放大成 3 次付费失败。

请求日志里可能有整份私有代码

统计 route、延迟、token 没问题，但完整 payload 里可能包含源码、工具打印出的 secret 和用户数据。默认只留指标；确实要排障时才打开 payload，并设置短保留期。

路由选择、延迟、token、失败和 fallback 放在一起看，模型路由才算真正可运维。

Switchyard 和 SandBase 分别管什么

Switchyard 解决 Agent 如何连模型，不负责隔离 Agent 执行的 shell 和代码。两者不是一层能力。

SandBase 可以提供模型/API 与隔离执行环境，Switchyard 负责客户端兼容和模型路由。实际部署时，我建议把 3 类策略拆开：

• 模型策略：请求应该交给哪个 backend。
• 执行策略：工具能读哪些文件、访问哪些网络、启动哪些进程。
• 审批策略：哪些修改必须等人确认。

全塞进 system prompt 看着省事，直到仓库里一段恶意指令成功碰到高权限 tool call。

我的判断

Switchyard 最吸引人的地方，是它认真处理了枯燥但棘手的协议兼容，没有假装几套 API 只是字段名不同。Coding Agent launcher 把试用门槛压得很低，固定处理链和 routing profile 又给生产化留出了空间。

内部模型评测、从闭源模型迁移到自托管模型、保留 Claude Code/Codex 体验但更换推理后端，这 3 类场景值得用。反过来，如果一个应用只调用一个模型，前面再塞一层 proxy 就是在主动增加值班工作。

FAQ

NVIDIA Switchyard 是模型吗？

不是。它是 LLM proxy、协议转换与路由层，真正生成结果的是后端模型。

Switchyard 能让 Claude Code 使用本地模型吗？

可以。前提是本地模型通过 vLLM、Ollama 等兼容后端暴露接口，而且模型本身能稳定处理 tool call 和编程任务。

Switchyard 能完全替代 LiteLLM 吗？

不能一概而论。Switchyard 更偏编程 Agent launcher 和跨协议转换，LiteLLM 是覆盖面更广的通用模型 gateway。

协议能转换，是否代表 Agent 效果一样？

不代表。协议转换只解决“请求能不能正确送达”，模型仍然要有足够的编程、指令遵循、context 和工具调用能力。

API key 应该写进 routing YAML 吗？

不应该。凭证放环境变量或 secret manager，routing 配置按普通部署代码管理。