每个团队接 LLM 的第一周都会撞上同一堵墙：OpenAI 的 SDK 说的是 `tools[].function.parameters`，Anthropic 说的是 `tools[].input_schema`；OpenAI 把 system 当一条 message，Anthropic 把它当顶层字段；一个返回 `choices[].delta`，另一个发 `content_block_delta`。于是你写了三个客户端封装、四套重试逻辑，外加一份永远对不齐的错误码映射表。

`respanai/respan-gateway` 想干的事就是把这堵墙变成一行 base_url。它是个 Rust 写的单二进制网关，宣称"一个端点接所有厂商，任何 SDK、任何模型、任何工具"。

这个项目 2026 年 9 月 25 日创建，到现在刚满一个月，303 star，33 fork，Apache-2.0 / MIT 双许可。年龄不大，但代码量不小：**265 个 `.rs` 文件、84,553 行**，39 个包组成一个 workspace。

我没停在读 README。下面每一条都有本机跑出来的证据：编译、测试、跨格式翻译的线上报文、5 万 QPS 的压测、工具环的两轮往返、以及对冲路由的延迟对照。

## 一、它把"网关"拆成了五个同心层

`Cargo.toml` 的 workspace 成员直接暴露了架构：

| 目录 | 行数 | 职责 |
|---|---:|---|
| `crates/kinds/` | 3,482 | 中立类型：conversation / media / realtime / mcp / decision |
| `crates/formats/` | 29,304 | 各家的线上格式编解码（conversation-http 一个就 14,713 行） |
| `crates/wires/` | 6,850 | HTTP / SSE / WebSocket 传输 |
| `crates/vendors/` + `tool-vendors/` | 12,606 | 20 家模型厂商、14 家工具厂商的元数据 |
| `crates/plugins/` | 6,376 | 9 个一等方插件 |
| `crates/core/` | 4,867 | Gateway、Plugin、Call、Fault —— 公共 API |

关键是中间那层：`kinds` 定义了与厂商无关的 `Input` / `Output`。一个 chat 请求进来，被客户端格式解码成 `Input`；出去时，被供应商格式重新编码。翻译只发生在这两次编解码里，中间所有插件看到的是同一个 Rust 类型。

这就是它敢说"插件看不到字节、看不到 header、看不到 key"的原因。`docs/plugins.md` 里那句话我核对过源码，是真的：`ClientContext::filter` 的泛型参数决定你编辑的是什么类型，闭包签名是 `&mut Input` 还是 `&mut Output`，与厂商无关。

## 二、四个钩子，一个 trait

`crates/core/src/plugin.rs` 里的 trait 只有四个方法，全部有默认实现：

```rust
#[async_trait]
pub trait Plugin: Send + Sync + 'static {
    async fn on_client(&self, _cx: &mut ClientContext) -> Result<Option<Response>> { Ok(None) }
    async fn on_client_end(&self, _cx: &ClientContext, _end: &Result<()>) {}
    async fn on_provider(&self, _px: &mut ProviderContext) -> Result<()> { Ok(()) }
    async fn on_provider_end(&self, _px: &ProviderContext, _end: &Result<()>) {}
}
```

两条边，各一对前后钩子。`on_client` 每个请求一次，返回 `Ok(None)` 放行、`Ok(Some(resp))` 自己应答（跳过后续插件）、`Err` 拒绝。`on_provider` 每次**调用**一次——注意是调用不是请求，一次请求可能产生多次调用：重试、降级、对冲、judge 的额外提问、工具环的每一步。

这套设计的重量在"end 钩子"上。`on_provider_end` 和 `on_client_end` 是**分离到 runtime 上跑的**，客户端已经拿到答案之后才执行，所以不计入延迟；`gateway.idle().await` 会等它们全部结束。计费、埋点、限额结算都挂在这里，不会拖慢主路径。

我特意去看了 `plugin.rs` 的测试：6 个用例全在测"失败路径下的钩子语义"——一个 filter 的 `edit` 失败后它的 `end` 还跑不跑（跑）、多个 filter 的 `end` 只跑一次且第一个失败胜出（是）、某个 filter 在 `end` 里 panic 会不会阻断其它 filter（不会，且该请求判 internal fault）。这种测试写得比功能测试更值钱。

## 三、跨格式翻译：我把上游的报文抓下来了

这是最该验证的地方。我写了一个假厂商端点（Python，记录每一个收到的请求），把网关的两个 provider 都指向它，然后用 **OpenAI 的格式**请求一个 **Anthropic 的模型**：

```bash
curl http://127.0.0.1:8099/v1/chat/completions -d '{
  "model": "anthropic/claude-sonnet-4-5",
  "messages": [{"role":"system","content":"be terse"},
               {"role":"user","content":"hello"}],
  "max_tokens": 64, "temperature": 0.3 }'
```

客户端拿到的是标准 OpenAI 响应。而假厂商实际收到的是：

```
POST /v1/messages
x-api-key: sk-fake-anthropic
anthropic-version: 2023-06-01

{ "model": "claude-sonnet-4-5",
  "max_tokens": 64,
  "system": "be terse",
  "messages": [{"role": "user", "content": "hello"}],
  "temperature": 0.3 }
```

三件事同时发生了：system message 被**提升**成 Anthropic 的顶层 `system` 字段；`x-api-key` 换成了供应商的 key（客户端的 key 一个字节都没过去）；`anthropic-version` 由格式自己补上，客户端不需要知道这个 header 存在。

反向也一样。用 Anthropic 格式请求 GPT：

```bash
curl http://127.0.0.1:8099/v1/messages -d '{
  "model":"openai/gpt-4o", "max_tokens":64, "system":"be terse",
  "messages":[{"role":"user","content":"weather?"}],
  "tools":[{"name":"get_weather","description":"Get weather",
            "input_schema":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}]}'
```

上游收到：

```json
{ "model": "gpt-4o",
  "messages": [{"role":"system","content":"be terse"},{"role":"user","content":"weather?"}],
  "tools": [{"type":"function","function":{"name":"get_weather","description":"Get weather",
             "parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}],
  "max_completion_tokens": 64,
  "stream": true,
  "stream_options": {"include_usage": true} }
```

`input_schema` 变成了 `parameters`，`max_tokens` 变成了 `max_completion_tokens`（OpenAI 新模型的参数名），而 `stream_options.include_usage` 是网关**主动加**的——因为 Anthropic 客户端期待流里有 usage，而 OpenAI 默认不给你。这种细节不是"字段映射表"能覆盖的，得真的理解两边的语义差。

流式我单独测了一遍。客户端发 `stream: true`，上游回 Anthropic 的 SSE，客户端收到的是 OpenAI 的 chunk 序列，一个 delta 对应一个 chunk，id 沿用上游的 `msg_fake_1`：

```
data: {"id":"msg_fake_1","choices":[{"index":0,"delta":{"content":"pong "},"finish_reason":null}]}
data: {"id":"msg_fake_1","choices":[{"index":0,"delta":{"content":"from "},"finish_reason":null}]}
...
data: [DONE]
```

### 那些"翻不过去"的字段去哪了

跨厂商翻译最脏的部分不是能翻的，是翻不了的。OpenAI 有 `logprobs`、`seed`、`parallel_tool_calls`，Anthropic 有 `thinking`、`cache_control`、`metadata.user_id`。硬塞会 400，直接丢会静默改变语义。

源码里的做法是 `NativeFields`：认不出的字段按"原格式名"打包存起来，随中立类型一路带着。`crates/formats/conversation-http/src/fields.rs` 里两个函数说清了策略：

- `native_of(format, fields)` —— 把剩下的字段打上来源格式的标签；
- `kept(format, native)` —— 只在**同一个格式**里还原；如果目标是另一个格式，直接 `Fault::bad_request`，因为"只有它自己知道这些字段是什么意思"。

结果是：OpenAI 客户端带 `logprobs` 去找 OpenAI，字段原样回去；带 `logprobs` 去找 Anthropic，请求被明确拒绝，不会被悄悄丢掉。这是个有主张的选择，我认同它。

## 四、路由、降级、对冲：1.013 秒变 0.211 秒

配置里一条 route 就能定义候选顺序：

```toml
[routes.smart]
to    = ["slow/claude-sonnet-4-5", "fast/claude-sonnet-4-5"]
hedge = "200ms"
```

我起了一个"慢供应商"（每次响应固定延迟 1 秒）和一个"快供应商"，同一条 route 跑两次对照：

| 配置 | 5 次调用耗时 | 回复来自 |
|---|---|---|
| `hedge = "200ms"` | 0.211 / 0.210 / 0.212 / 0.212 / 0.212 s | 快供应商 |
| 去掉 hedge | 1.014 / 1.011 / 1.011 s | 慢供应商 |

慢的那个其实**没有失败**，它只是慢。传统的 fallback 完全不会触发；对冲在第 200 毫秒就并行发出第二个请求，谁先出内容谁赢。

这里有个容易被做错的地方：流式请求一旦开始吐字，就不能再重试，否则客户端会看到重复文本。`crates/plugins/fallback/src/lib.rs` 的解法是把"算成功"的判定点做成参数：

```rust
first_success(calls, &backoff, Until::content(Output::is_content), retryable)
```

`Until::content` 表示"只有拿到第一个内容事件才算成功，此后绝不重试"。一个流如果在第 500 个 token 才断，客户端看到的是流被切断，不会被悄悄重放一遍。文档注释里写得很直白：`a stream that fails later reaches the client cut short, not replayed`。

## 五、工具环：一次普通 chat 请求，用上了它不知道的 MCP 工具

这是整个项目最"哇"的功能，也是最容易被做成 demo 的功能。我认真验了一遍。

准备：一个 40 行的 MCP stdio server（实现 `initialize` / `tools/list` / `tools/call`，提供 `word_count`），配置里挂上去：

```toml
[tools.wordcount]
command = "python3"
args    = ["/tmp/rg-fake/mcpserver.py"]

[plugins.tool_loop]
servers   = ["wordcount"]
max_steps = 4
```

然后发一个**最普通的** OpenAI chat 请求，请求体里没有任何 `tools` 字段：

```bash
curl http://127.0.0.1:8094/v1/chat/completions -d '{
  "model":"gpt-4o",
  "messages":[{"role":"user","content":"how many words in: one two three four five"}]}'
```

客户端收到：

```json
{"choices":[{"message":{"role":"assistant","content":"the tool said: 5 words"},"finish_reason":"stop"}],
 "usage":{"prompt_tokens":40,"completion_tokens":18,"total_tokens":58}}
```

一次回复，客户端全程不知道有工具存在。但假厂商的日志显示上游被调用了**两次**：

```
--- 第 1 次 ---
注入的 tools: ['wordcount__word_count']
  user       how many words in: one two three four five

--- 第 2 次 ---
注入的 tools: ['wordcount__word_count']
  user       how many words in: one two three four five
  assistant  None
  tool       5 words
  tool_call_id: call_1
```

第一次，网关把 MCP 服务器的工具以 `{server}__{tool}` 的名字注入请求；模型回 `tool_calls`；网关执行 MCP 调用，把结果作为 `role: tool` 消息、带上匹配的 `tool_call_id` 塞回去；第二次模型给出最终答案。usage 是两次之和（20+20 / 9+9），说明计费按真实调用累加，没有按一次请求算。

这个能力的意义在于：客户端可以是一个只会说 OpenAI 协议的老应用，模型可以是任意厂商，工具可以是任何 MCP 服务器，三者互不知道对方存在。

## 六、性能：我自己压了一遍，数字站得住

README 宣称 0.07ms 附加延迟、56,734 QPS、31MB 内存，是 Bifrost 的 3 倍、LiteLLM 的 200 倍。这类数字我一向先怀疑。

但直接对比"有网关 vs 没网关"是不公平的：网关天然多一跳网络。所以我加了一个**哑中继**做基线——一个纯 `copy` 的 TCP 转发器，多一跳、零解析、零翻译。三者对照（wrk，4 线程 64 连接 10 秒，同一台 M 系列 Mac，全部 loopback）：

| 路径 | 跳数 | 吞吐 | p50 | p99 |
|---|---:|---:|---:|---:|
| A 直连假厂商 | 1 | 130,674 /s | 0.43 ms | 183 ms* |
| B 哑中继（纯字节转发） | 2 | 67,389 /s | 0.91 ms | 1.45 ms |
| C 网关（OpenAI→Anthropic 翻译） | 2 | 52,138 /s | 1.16 ms | 3.00 ms |
| D 网关（OpenAI→OpenAI 同格式） | 2 | 51,125 /s | 1.18 ms | 3.30 ms |

\* A 的 p99 有抖动，两轮分别 4.20 ms 和 183 ms，直连时 wrk 自己成了瓶颈，看 p50 更可靠。

三个结论：

1. **网关自身的开销约 0.25 ms**（C 减 B 的 p50）。README 说的 0.07 ms 我没复现出来，但同一数量级；差异大概率来自测量方法——他们大概是在更强的机器上、用更低的并发、只算网关内部的耗时。
2. **翻译几乎不要钱**。跨格式（C）和同格式（D）的 p50 只差 0.02 ms，吞吐差 2%。JSON 解析和类型转换相对于两次 HTTP 往返可以忽略。
3. **吞吐 5.2 万/秒**，和它宣称的 5.67 万在同一水平。考虑到我的"假厂商"是个 thread-per-connection 的玩具实现，这个数字更可能是被上游限制的。

内存和启动，用 `ru_maxrss` 量（macOS 上单位是字节）：

| 指标 | 实测 |
|---|---|
| release 编译 | 1m25s |
| 二进制 | 20 MB |
| 启动到首个 200 | 208 ms |
| 空闲 RSS | 21.3 MB |
| 64 并发压 10 秒后峰值 | 33.2 MB |

31 MB 那个宣称基本准确，甚至偏保守。

## 七、那些不显眼但很难做对的约束

**全仓库只有一个 `unsafe`。** workspace 的 lint 里写着 `unsafe_code = "deny"`。我 grep 了 84,553 行，只命中一处：`crates/formats/mcp-http/src/session.rs:408`，用 `libc::kill(-group, signal)` 杀 MCP 子进程的进程组，带 `// SAFETY:` 注释和一个作用域内的 `#[allow(unsafe_code)]`。一个要管子进程、要处理 WebSocket、要解析上百种 JSON 的服务，做到这个程度不容易。

**没有 client key 就拒绝上公网。** 我试了 `--listen 0.0.0.0:8096`：

```
error: refusing to listen on 0.0.0.0:8096 with no client keys: anyone who can
reach it would spend your provider keys, and without keys it answers only to
localhost anyway.
  Set `client_keys` in the config (`respan-gateway init --client-key` writes a
strong one), or listen on 127.0.0.1.
```

配上 key 之后，无 key 请求 401，错误体里把三种传 key 的方式（Bearer / x-api-key / x-goog-api-key）和 WebSocket 的两种都列了出来。我核对了假厂商的日志：**客户端 key 从未出现在上游请求里**，只有供应商自己的 key。

**SIGHUP 热重载真的不重启。** 我往配置文件里加了一条 route，`kill -HUP`，1 秒后新路由生效，管理 API 的 `uptime_seconds` 连续、`reloaded_at` 更新：

```json
{"uptime_seconds": 327, "reloaded_at": "2026-10-26T01:39:53.995Z",
 "totals": {"requests": 5, "errors": 0, "in_flight": 0,
            "input_tokens": 44, "output_tokens": 28}}
```

顺带一提，这个 `/ui/api/overview` 还按 token 统计了流量，是免费的观测面。

**`check` 子命令把配置解释给你看。** 不是"配置合法/非法"，而是列出每个 provider 实际用哪个 base_url、支持哪些格式、key 从哪来、默认路由是谁：

```
providers  openai at http://127.0.0.1:8931/v1
             formats openai-chat, openai-responses, openai-realtime, ... (8 个)
           anthropic at http://127.0.0.1:8931
             formats anthropic-messages
routes     smart -> anthropic/claude-sonnet-4-5, openai/gpt-4o (first)
           <provider>/<model> -> that provider
```

排障时这比日志有用得多。

**新增一家厂商真的只要一个文件。** 我数了 `crates/vendors/`：`openrouter.rs` 17 行、`xai.rs` 20 行、`deepseek.rs` 32 行，连 Anthropic 带模型列表解析也才 67 行。一家厂商就是一个 `Vendor` 常量，声明 id、key 环境变量、支持的格式和 base_url，模型能力用一个小函数把厂商的 JSON 翻成 `Model`。CONTRIBUTING 里那句"a new vendor is usually one file"没有夸张。

## 八、测试：697 个，一次通过

```
cargo test --workspace --all-targets --exclude respan-gateway-python
→ 63 个测试二进制，697 passed，0 failed，0 ignored
```

排除 python 绑定是环境问题：那个 crate 要链接 `libpython3.13`，本机没有对应的开发库，链接阶段就失败了。这是我这边的限制，不是代码缺陷——但我也没验证到它。

测试分布很有意思：`openai/tests.rs` 68 个、`anthropic/tests.rs` 44 个、`responses/tests.rs` 37 个。翻译层的测试密度最高，符合"翻译错了就是事故"的判断。

## 九、诚实边界

必须说清楚哪些是我验证过的，哪些不是：

- **只跑了 chat 主路径。** 实时语音（OpenAI Realtime ⇄ Gemini Live）、图片、语音合成、转写、embedding、视频（Veo）这些端点我只在 `check` 的输出里看到它们存在，没有真实厂商 key，一个都没跑通。README 里"多模态"那一整块，我无法背书。
- **厂商是假的。** 所有"翻译正确"的结论都基于我自己写的假端点返回的报文。真实的 Anthropic 会不会因为某个字段缺失而 400，我不知道。我验证的是**网关发出的请求长什么样**，不是**厂商会不会接受**。
- **基准对比是自报的。** Bifrost / Portkey / LiteLLM 那三列我没跑，也没有它们的部署环境。我只独立测了"网关 vs 哑中继"这一个对照。
- **0.07ms 与 0.25ms 的差距。** 我测到的是 0.25ms，README 说 0.07ms。测量条件不同（机器、并发、是否计入第二跳），我不认为这是造假，但也不替它圆场。
- **工具环只测了一个玩具 MCP server。** `npx @modelcontextprotocol/server-filesystem` 那种真实服务器、OAuth 登录（`auth = "login"`）、`/mcp` 聚合端点，都没跑。
- **Python 进程内模式没跑。** `python/` 那个 crate 本机链接不上，README 说的"in-process、无服务器"形态未经我验证。
- **项目很年轻。** 一个月、303 star、26 个 open issue。工程完成度高不代表生产验证充分，这东西还没经过大规模流量的检验。

## 十、值得学的三件事

抛开"又一个 LLM 网关"的标签，这个仓库里有三处设计我认为值得抄：

**1. 把"多厂商"收敛成类型系统问题，不是 if-else 问题。** 大多数网关的做法是"为每对 (客户端格式, 供应商格式) 写一个转换函数"，N×M 爆炸。这里定义一层中立类型，转换变成 N+M：每个格式只负责"编码到中立类型"和"从中立类型解码"。代价是中立类型必须足够表达所有厂商的语义，做不到的部分用 `NativeFields` 显式标记"翻不过去"。这是把复杂度放在正确的位置。

**2. 钩子的语义边界画得极细。** 四个钩子，但文档用大量篇幅解释"什么时候跑、失败时跑不跑、顺序是什么、能不能 await"。`on_provider` 可以在任何 await 点被打断（对冲输掉的那一路会被 drop），但 `on_provider_end` 仍然会跑，所以"预留额度"必须在 await 之前完成。这种级别的契约描述，比多写十个功能更能决定一个插件系统能不能被别人用对。

**3. 拒绝比静默更安全。** 翻不过去的字段 → 400，不丢；没有 client key 绑公网 → 拒绝启动，不侥幸；流已经开始 → 不重放，让客户端看到真实的断流。三个地方都选择了让问题暴露，没有选择让请求成功。网关这种位置，静默降级造成的损失往往比一次明确失败大得多。

## 结语

303 star 对一个月的项目不算少，但也远没到"经过检验"的程度。它真正让我愿意写完这篇的原因不是 star 数，是**代码里的注释密度**：`plugin.rs` 用 40 行注释解释一个 4 方法的 trait，`fallback` 的模块文档直接告诉你"流失败后到达客户端的是被切断，不是被重放"，`fields.rs` 每个函数上面都写着"为什么"。

一个 8.4 万行的 Rust 项目，全仓库只有一处 `unsafe`，697 个测试一次通过，配置错了会告诉你错在哪一行，绑公网会拒绝启动。这些东西不上头条，但它们决定了一个网关能不能被放在生产流量的正中间。

---

**仓库**：https://github.com/respanai/respan-gateway
**版本**：0.3.0（commit `0507492`，2026-10-25）
**许可**：MIT OR Apache-2.0
**验证环境**：macOS / Apple Silicon，rustc 1.88.0，wrk 4 线程 64 连接


每个团队接 LLM 的第一周都会撞上同一堵墙：OpenAI 的 SDK 说的是 tools[].function.parameters，Anthropic 说的是 tools[].input_schema；OpenAI 把 system 当一条 message，Anthropic 把它当顶层字段；一个返回 choices[].delta，另一个发 content_block_delta。于是你写了三个客户端封装、四套重试逻辑，外加一份永远对不齐的错误码映射表。

303 star 的 Rust 网关：让 Anthropic SDK 直连 GPT，让一次普通 chat 请求自动用上 MCP 工具

每个团队接 LLM 的第一周都会撞上同一堵墙：OpenAI 的 SDK 说的是 tools[].function.parameters，Anthropic 说的是 tools[].inputschema；OpenAI 把 system 当…

软件研发

人工智能

开发工具

架构设计

respan-gateway：一个Rust编写的LLM网关，将OpenAI、Anthropic等20家厂商的API差异抽象为统一base_url，支持跨格式翻译、流式响应、工具环路由及对冲降级。实测验证：5.2万QPS、0.25ms附加延迟、697个测试通过、全仓库仅一处unsafe。代码结构清晰，插件钩子设计严谨，是生产级多模型接入的可靠选择。

代码解释

语音合成

服务器

WebSocket

DeepSeek

路由

Python

GitHub

MacOS

OAuth

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

respan-gateway：一个Rust编写的LLM网关，将OpenAI、Anthropic等20家厂商的API差异抽象为统一base_url，支持跨格式翻译、流式响应、工具环路由及对冲降级。实测验证：5.2万QPS、0.25ms附加延迟、697个测试通过、全仓库仅一处unsafe。代码结构清晰，插件钩子设计严谨，是...

303 star 的 Rust 网关：让 Anthropic SDK 直连 GPT，让一次普通 chat 请求自动用上 MCP 工具-腾讯云开发者社区-腾讯云

303 star 的 Rust 网关：让 Anthropic SDK 直连 GPT，让一次普通 chat 请求自动用上 MCP 工具

303 star 的 Rust 网关：让 Anthropic SDK 直连 GPT，让一次普通 chat 请求自动用上 MCP 工具

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐