业务代码只面向一个内部接口。协议差异放在适配器里,失败处理放在路由层,每一次上游尝试都写入账本。下面给出一个约 190 行的 Python 实现和 10 个单元测试。测试使用模拟上游运行,没有调用任何真实 API,因此文中的行为都是可以在本地复现的,但不代表任何供应商的实际表现。
一、场景与问题
假设一个 SaaS 后端有三个业务模块,需要调用两种协议的模型:一种是 OpenAI Chat Completions 格式,另一种是 Anthropic Messages 格式。直接调用 SDK 会遇到三类问题。
第一类是请求和响应的字段不同。Anthropic 要求 max_tokens 必填,系统提示放在顶层的 system 参数里,用量字段叫 input_tokens 和 output_tokens。OpenAI 的用量字段叫 prompt_tokens 和 completion_tokens。
第二类是失败的含义不同。429 可以等待后重试,额度耗尽时同一个上游再试也没有用,400 说明请求本身有问题,重试和切换都不应发生。如果三种情况都做同样的处理,就会浪费配额,或者掩盖真正的错误。
第三类是账单难以核对。一次用户请求可能经过多次尝试,才有一次成功。如果只记录最终结果,就无法知道哪个上游失败了几次,也无法和供应商账单对齐。
二、整体架构
一次调用的处理顺序如下:
- 业务代码调用
Gateway.call,传入逻辑模型名(例如chat-default)和统一格式的消息。 - 路由层查出该逻辑模型名对应的候选上游列表,按优先级排序。
- 跳过已停用或处于熔断冷却期的上游。
- 适配器把统一格式转换为该上游的协议,发送请求。
- 成功则返回统一格式的结果;失败则按错误类型决定重试、切换或直接报错。
- 每次尝试,无论成功还是失败,都向账本写入一行记录。
三、技术选型
下面列出几种做法,并说明为什么选择现在的方案。
- 业务直接调用各家 SDK。这种做法最简单,但每新增一家供应商,业务代码就要改一次,失败处理也会分散在各个模块里。放弃。
- 对所有错误统一重试。这样实现简单,但额度耗尽或参数错误时重试没有意义,还会放大故障。放弃。
- 失败时只切换,不重试。单次超时或 503 就换上游,会让本来可以恢复的请求过早切换,也会增加备用上游的压力。放弃。
- 直接使用现成的网关产品。LiteLLM 等项目可以覆盖这些功能,其文档说明预算执行依赖数据库 [5]。本文的目的是说明判断顺序,所以自己实现,便于逐行核对。生产环境中,应优先评估成熟产品。
- 本文采用的做法(自己实现,但判断逻辑写清楚):同一上游有限次数重试,额度耗尽立即停用并切换,熔断连续失败的上游,账本记录每一次尝试。
协议适配只实现了 OpenAI 和 Anthropic 两种格式。新增协议时,只需要添加一对转换函数,并注册到适配器表中。
字段名称来自供应商 SDK 的类型定义,而不是记忆。我从 PyPI 下载了 anthropic 2.8.0 和 openai 3.49.0 的发行包,核对了 max_tokens、system、input_tokens、output_tokens、prompt_tokens、completion_tokens 等字段 [1][2]。
四、实现步骤
第一步,定义适配器。每个协议两个函数,一个把统一格式转成供应商格式,一个把供应商响应转回统一格式。源文件中的完整代码如下:
def to_openai_body(req):
return {
"model": req["upstream_model"],
"messages": req["messages"],
"max_tokens": req.get("max_tokens", 1024),
}
def from_openai_body(data):
msg = data["choices"][0]["message"]
return {
"text": msg["content"] or "",
"input_tokens": data["usage"]["prompt_tokens"],
"output_tokens": data["usage"]["completion_tokens"],
}
def to_anthropic_body(req):
system = [m["content"] for m in req["messages"] if m["role"] == "system"]
messages = [m for m in req["messages"] if m["role"] != "system"]
body = {
"model": req["upstream_model"],
"max_tokens": req.get("max_tokens", 1024), # Anthropic 要求必填
"messages": messages,
}
if system:
body["system"] = "\n".join(system) # system 是顶层参数
return body
def from_anthropic_body(data):
text = "".join(b["text"] for b in data["content"] if b["type"] == "text")
return {
"text": text,
"input_tokens": data["usage"]["input_tokens"],
"output_tokens": data["usage"]["output_tokens"],
}
ADAPTERS = {
"openai": (to_openai_body, from_openai_body),
"anthropic": (to_anthropic_body, from_anthropic_body),
}
第二步,实现路由和失败处理。call 方法遍历候选上游,对每个上游按次数限制尝试。错误类型决定后续动作:quota_exhausted 停用上游并切换,bad_request 直接抛出,rate_limited 和 server_error 等可恢复错误在同一上游重试一次,并且连续失败会触发熔断。
def call(self, req):
request_id = uuid.uuid4().hex[:12]
last_error = None
for target in self.routes[req["model"]]:
up = self.upstreams[target["upstream"]]
if not up.available(self.clock()):
continue
for attempt in range(MAX_ATTEMPTS_PER_UPSTREAM):
started = self.clock()
try:
to_body, from_body = ADAPTERS[up.protocol]
body = to_body({
**req, "upstream_model": target["model"]})
raw = up.send(body)
result = from_body(raw)
except UpstreamError as e:
self.ledger.write(
request_id=request_id, upstream=up.name, model=target["model"],
attempt=attempt + 1, ok=False, error=e.kind, status=e.status,
latency_ms=round((self.clock() - started) * 1000, 1),
)
last_error = e
if e.kind not in SWITCH_ON: # 例如 bad_request:直接失败
raise
if e.kind == "quota_exhausted": # 额度用完:不重试,停用并切换
up.disabled = True
break
up.record_failure(self.clock())
if e.kind not in RETRYABLE or not up.available(self.clock()):
break
if attempt + 1 < MAX_ATTEMPTS_PER_UPSTREAM:
self.sleep(self.backoff_base * (2 ** attempt))
continue
self.ledger.write(
request_id=request_id, upstream=up.name, model=target["model"],
attempt=attempt + 1, ok=True, error=None, status=200,
input_tokens=result["input_tokens"], output_tokens=result["output_tokens"],
latency_ms=round((self.clock() - started) * 1000, 1),
)
up.record_success()
return {
"request_id": request_id, "upstream": up.name, **result}
raise AllUpstreamsFailed(f"请求 {request_id} 所有上游均失败") from last_error
第三步,配置路由。逻辑模型名到上游模型 ID 的映射写在一张表里,业务代码不接触上游模型 ID:
routes = {
"chat-default": [
{
"upstream": "primary", "model": "model-a"},
{
"upstream": "backup", "model": "model-b"},
],
}
第四步,接入账本。账本每行是一条 JSON,记录请求 ID、上游、尝试序号、是否成功、错误类型、HTTP 状态码、耗时和 Token 数。同一个用户请求的所有尝试共享一个 request_id,因此能看出它经过了哪些上游。
五、验证与结果
测试文件 test_gateway.py 含 10 个用例,使用模拟上游运行。在本机 Python 3.14.3 上执行 python -m unittest -v test_gateway,结果为 10 个用例全部通过,耗时 0.029 秒。
| 用例 | 验证内容 |
|---|---|
| OpenAI 适配器 | 请求体字段正确,用量字段 prompt_tokens、completion_tokens 解析正确 |
| Anthropic 适配器 | system 被移到顶层,max_tokens 默认补齐,响应文本拼接正确 |
| 主上游成功 | 不调用备用上游 |
| 5xx 连续两次 | 同一上游尝试两次,然后切换到备用上游 |
| 429 后成功 | 在同一上游重试一次即成功,不切换 |
| 400 参数错误 | 不重试,不切换,直接抛出 |
| 额度耗尽 | 不重试,切换到备用上游;之后的请求跳过该上游 |
| 连续失败熔断 | 第三次失败后熔断,冷却期内不发送;冷却结束后恢复 |
| 所有上游失败 | 抛出 AllUpstreamsFailed |
| 账本记录 | 每次尝试一行,request_id 相同,成功行带 Token 数 |
用一个示例请求验证账本的输出。主上游连续两次返回 503,然后切换到备用上游成功:
| 尝试 | 上游 | 上游模型 | 结果 | HTTP 状态 |
|---|---|---|---|---|
| 1 | primary | model-a | 失败,server_error | 503 |
| 2 | primary | model-a | 失败,server_error | 503 |
| 3 | backup | model-b | 成功,输入 12、输出 3 个 Token | 200 |
三行共享同一个 request_id。备用上游收到的请求体为 {"model": "model-b", "max_tokens": 1024, "messages": [...]},与 Anthropic 格式一致,没有 OpenAI 的字段。
本文没有任何延迟、成功率或吞吐量的数据。测试只说明判断顺序正确,不说明任何真实供应商的表现。
六、风险与边界
- 没有接入真实上游。
send()在测试中由模拟对象代替。真实部署时,要按每家供应商的文档把 HTTP 状态码和错误信息映射到rate_limited、quota_exhausted等类型。这一步是模拟中最不确定、也最需要核对的部分。 - 退避没有加抖动。当前的等待时间是固定的 0.5 秒、1 秒,多个客户端会在同一时刻重试。生产中应加入随机抖动,参考 AWS 的分析 [3]。
- 重试只做一次。这是为了避免故障放大。Google SRE 的文章讨论了级联故障的成因 [4],多层重试是常见诱因之一。
- 熔断状态保存在进程内。多个实例之间不共享熔断状态,需要外部存储,本文没有实现。
- 不支持流式输出。流式响应一旦开始,就很难在中途切换上游。当前设计只能在返回第一个响应之前切换。
- 账本只记录 Token 数,不计算费用。费用要按供应商的价格单独计算,并与供应商账单对账。账本写入的是本地文件,没有并发保护,也不是持久化存储。
- 切换上游可能改变输出。同一逻辑模型名下的不同上游,输出风格和能力可能不同。需要输出一致的业务,应只在同一模型组内切换。
七、总结
这个接入层适合多供应商、需要统一失败处理和用量对账的调用场景。它把协议差异限制在适配器中,把失败处理限制在路由层,并让每一次尝试都可以追溯。
它不适合的场景包括:只使用单一供应商、调用量很低,或者业务要求输出完全固定、不允许任何切换。
下一步可以把 send() 替换为真实的 HTTP 调用,先用供应商提供的测试额度或小批量请求验证错误映射,再逐步扩大流量。
参考资料
- Anthropic Python SDK 2.8.0(PyPI 发行包源码,类型定义):https://pypi.org/project/anthropic/
- OpenAI Python SDK 3.49.0(PyPI 发行包源码,类型定义):https://pypi.org/project/openai/
- AWS Architecture Blog, Exponential Backoff And Jitter:https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
- Google SRE Book, Addressing Cascading Failures:https://sre.google/sre-book/addressing-cascading-failures/
- LiteLLM 文档:https://docs.litellm.ai/