BUZZ AI Gateway
文档 · 核心概念 · 透明转发

透明转发

网关应该是一根线,不是翻译官。透明转发是 BUZZ 的核心承诺:按字节级代理 Anthropic Messages API,请求形状一致、响应形状一致、SSE 事件顺序一致、错误响应一致。你的代码不需要知道 BUZZ 的存在。

是什么

大多数所谓的 "AI 网关" 本质是一个穿着代理外衣的应用服务器。它会重新解析你的 JSON、把请求转换成它内部的数据模型、用自己的 SDK 调用上游 LLM、再把响应翻译回去给你。每一步都是一次行为漂移的机会。

BUZZ 的方向相反。原则非常简单:

Anthropic 接受什么字段,BUZZ 就转发什么。Anthropic 返回什么字段,BUZZ 就返回什么。Anthropic 发出什么 SSE 事件,BUZZ 就按相同顺序发出相同事件。

你发出的字节几乎原封不动到达 Anthropic,只在 header 层面做路由和鉴权改写。Anthropic 返回的字节几乎原封不动到达你,只在末尾追加 BUZZ 的计费透明字段,而且不修改任何 Anthropic 已经产生的字段。

为什么重要

三个理由。

前向兼容。当 Anthropic 发布新特性,比如 Extended Thinking、结构化 tool input、新的 stop_reason 取值,你不用等网关 "支持"。Anthropic 当天上线,你当天就能用上。

可调试。如果代码出问题,你可以把 BUZZ 的响应和 Anthropic 直连的响应逐字段对比。结果一致。网关不再是排错时的嫌疑人,你的调试面收敛得非常快。

可移植。对着 BUZZ base URL 写的代码,只要换一行 URL 就可以跑在 api.anthropic.com 上。协议层没有锁定,因为协议层根本没有可被锁定的东西。

BUZZ 怎么做的

转发流水线刻意保持极简:

  1. 鉴权改写。BUZZ 校验你的 key,然后在出口替换为上游通道的凭据。你的 key 不会到达 Anthropic。
  2. 流式直通。SSE chunk 一到就转发,字节对齐。事件顺序、event:/data: 帧结构、事件之间的时间间隔全部保留。
  3. 缓存指令不改。每个 cache_control 块原样转发。命中与否由 Anthropic 决定,不是 BUZZ。
  4. Tool 块不改。tool_use、tool_result、tool_choice 形状不做任何转换。
  5. 未知字段直通。BUZZ 没见过的请求字段,送上游;BUZZ 没见过的响应字段,送回你。

极少数 BUZZ 会主动介入的地方都是刻意为之,而且很轻:剥离 Bearer token 上的可选 sk- 前缀;anthropic-version 缺失时默认填 2023-06-01;少数通道级参数(inference_geo、speed、service_tier)在上游通道未授权时丢弃。这些都不会改变 Anthropic 返回字段的语义。响应中如出现 usage.iterations[] 这类字段,它们来自上游提供方,BUZZ 不会自行附加。

对比传统中转站

传统的 Claude 中转站基本都是一个 Node 或 Python 服务器,自己持有 SDK 调用 Anthropic。它会把你的请求转成内部类型,调用 anthropic.messages.create(),再把响应转回去。后果不小:

关注点传统中转站BUZZ 透明转发
Anthropic 新特性等中转站作者更新当天可用
流式行为常被重新缓冲或重新编码字节对齐 SSE 直通
缓存命中率请求改写常导致命中率下降与 Anthropic 直连一致
字段级一致性每次升级都有漂移风险对照实抓 fixture 回归
代码可移植性定制 SDK,不符合 Anthropic 形状Anthropic SDK 直接用

如果你只想暴露一个 chat completion 接口,中转站做法没问题。但只要你在乎 Prompt Cache、Tool Use 多轮回环、Extended Thinking 或者 Anthropic 未来 12 个月新增的任何特性,这种架构就开始崩。

关于信任

透明转发也是一份信任契约。一个会重新解析你请求的网关,同样有能力记录、修改、重放、保存这些请求。一个只在你的 TLS 连接和 Anthropic 的 TLS 连接之间搬运字节的网关,在消息体上根本没有这种能力。这是零数据留存的架构基础:不留存数据最简单的办法,就是从来不持有它。

面对任何网关都应该问一句:能不能给一个请求 fixture,通过你的网关返回的字节与 Anthropic 直连完全一致?能,透明转发就是真的;不能,那只是营销词。

相关链接