Switchyard：Rust 编写的 LLM 流量代理，支持 OpenAI/Anthropic 协议互转

Switchyard：Rust 编写的 LLM 流量代理，支持 OpenAI/Anthropic 协议互转 | 前端进阶之旅

Full translation

完整中文译文

Switchyard 是一个用于 LLM 流量的 Rust 代理（proxy）和库。它可以在不同 provider 之间路由请求，在 OpenAI 和 Anthropic API 之间做格式转换，记录运维指标，并提供类型化、可组合的路由算法。

为什么需要 Switchyard？将编程 Agent（如 Claude Code 或 Codex）指向一个开源模型。Switchyard 负责在 OpenAI Chat、Anthropic Messages 和 OpenAI Responses 格式之间进行转换，这样 Agent 可以继续使用自己熟悉的 API 格式，而请求则由 vLLM、NVIDIA NIM、Ollama 或任何 OpenAI 兼容的端点来提供服务。同一个代理可以在多个模型之间分配流量进行 A/B 测试，应用信号驱动的阶段路由，或者运行你自己编写的自定义算法。

协议转换：在 OpenAI Chat、Anthropic Messages 和 OpenAI Responses 格式之间转换

多后端路由：随机路由、LLM-as-classifier 路由、信号驱动的阶段路由器，或自定义算法

运维指标：Prometheus 指标覆盖请求、错误、延迟、tokens 和路由开销

Switchyard 是预-alpha 软件，正在快速演进。在达到 v1.0 之前，API 和算法预计会有重大变化。

实验性软件，不适合生产环境使用。

选择启动器路径，通过 Switchyard 运行 Claude Code、Codex CLI 或 OpenClaw。选择服务器路径，将 Switchyard 作为独立代理运行。选择库路径，将路由嵌入到你自己的 Rust 应用中。

安装 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]"

你启动的编程 Agent 也必须已安装并在 PATH 上。这不会安装独立的 switchyard-server 二进制文件；为此请使用服务器路径。

设置 OpenRouter 密钥并启动针对打包部署的请求：

export OPENROUTER_API_KEY="your-openrouter-key"  # pragma: allowlist secret
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 代理。安装 Rust 和 Cargo，然后安装发布的二进制文件：

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

Cargo 构建 release 二进制文件并默认安装到 ~/.cargo/bin。

使用入门指南创建 routes.toml，然后验证并启动服务器：

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 应用中。它本身不调用任何模型——算法决定使用哪个 target 并将每个模型调用回调给你，因此它可以插入现有的代理、网关或 Agent 运行时，而无需拥有自己的 HTTP 堆栈。当你想让调用为你执行时，可以将其与 switchyard-llm-client 配对使用。

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

有关设置和算法列表，请参阅入门指南，或查看 switchyard-libsy crate 文档。

直通路由在一个模型 ID 下注册一个 target，不做路由决策。有关常见路由形态和自托管 target，请参阅路由概览。

flowchart LR
    clients["Clients"]
    switchyard["Switchyard<br/>routing · translation · fallback"]
    backends["Model backends"]

    clients -->|"OpenAI / Anthropic API"| switchyard
    switchyard -->|"provider-native format"| backends

客户端保持其原生的 OpenAI 或 Anthropic API 格式。Switchyard 选择一个配置好的后端，以该后端自己的格式转发请求，然后将响应转换回客户端期望的形状。服务器接受 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages。每个配置的 LLM 客户端选择一个上游格式。

入门指南：完整的启动器和独立服务器演练

核心概念：LLM 客户端、targets、路由、模型 ID 和路由算法

路由概览：选择和配置路由算法

switchyard-server：服务器配置、路由算法和指标

switchyard-libsy：在 Rust 应用中嵌入路由算法

switchyard-protocol：provider 中立的请求、响应和流式类型

switchyard-translation：请求、响应和流转换

Issues：GitHub Issues

Code of Conduct：行为准则