多模型 API 接入层设计:用适配器统一请求格式、路由与用量记录

简介: 本文介绍一个轻量级LLM网关实现:业务代码仅对接统一接口;协议差异由适配器处理(已支持OpenAI/Anthropic);失败策略精细化(额度耗尽即停用、400不重试、429可重试);每次调用(含失败)均记入账本,便于对账与追踪。含190行Python代码及10个本地可复现单元测试。(239字)

业务代码只面向一个内部接口。协议差异放在适配器里,失败处理放在路由层,每一次上游尝试都写入账本。下面给出一个约 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 说明请求本身有问题,重试和切换都不应发生。如果三种情况都做同样的处理,就会浪费配额,或者掩盖真正的错误。

第三类是账单难以核对。一次用户请求可能经过多次尝试,才有一次成功。如果只记录最终结果,就无法知道哪个上游失败了几次,也无法和供应商账单对齐。

二、整体架构

一次调用的处理顺序如下:

  1. 业务代码调用 Gateway.call,传入逻辑模型名(例如 chat-default)和统一格式的消息。
  2. 路由层查出该逻辑模型名对应的候选上游列表,按优先级排序。
  3. 跳过已停用或处于熔断冷却期的上游。
  4. 适配器把统一格式转换为该上游的协议,发送请求。
  5. 成功则返回统一格式的结果;失败则按错误类型决定重试、切换或直接报错。
  6. 每次尝试,无论成功还是失败,都向账本写入一行记录。

三、技术选型

下面列出几种做法,并说明为什么选择现在的方案。

  • 业务直接调用各家 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 调用,先用供应商提供的测试额度或小批量请求验证错误映射,再逐步扩大流量。

参考资料

  1. Anthropic Python SDK 2.8.0(PyPI 发行包源码,类型定义):https://pypi.org/project/anthropic/
  2. OpenAI Python SDK 3.49.0(PyPI 发行包源码,类型定义):https://pypi.org/project/openai/
  3. AWS Architecture Blog, Exponential Backoff And Jitter:https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
  4. Google SRE Book, Addressing Cascading Failures:https://sre.google/sre-book/addressing-cascading-failures/
  5. LiteLLM 文档:https://docs.litellm.ai/
相关文章
|
1月前
|
JavaScript Ubuntu Shell
国内怎么用 Claude Code:从零到跑通的完整步骤(2026 年 9 月实测)
本文详解国内直连使用 Claude Code 的最优路径——API 中转方案:仅需配置 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN` 两个环境变量,10分钟完成从 Node.js 安装到首条命令运行。每步附验证命令,精准定位问题(如 `/v1/v1/` 错误、Key 未生效等)。兼容任意中转服务,含自查方法与避坑指南。作者所属 Code2AI 为同类服务商,文末已披露。
|
1天前
|
缓存 前端开发 API
Qwen4-Max 对比 GPT-6.2 Astra、Claude Fable 5.2、Gemini 4 Carbon:能力、价格与 API 选型
Qwen4-Max是阿里云2026年11月发布的旗舰多模态智能体模型,总参数2.4T,激活仅71B,支持100万Token上下文与图文视频输入;主打中文任务、编程及成本敏感场景,单任务费用直降58%,API输入¥10/百万Token起。(239字)
|
3天前
|
API 开发工具 编解码
图片 URL 浏览器能打开,为什么大模型 API 仍然读取失败?
本文详解视觉模型图片输入失败的排查逻辑:浏览器能打开≠模型可读取。重点指出四大关键检查点——公网可访问性、真实格式校验、尺寸/分辨率合规性、模型本身是否支持视觉输入,并提供可运行的Python预检工具,帮助开发者快速定位防盗链、假200、MIME错配等问题。(239字)
|
4天前
|
Prometheus 监控 Cloud Native
API 服务商承诺的 SLA 99.9% 怎么验证?从 Python 监控到企业验收清单
本文揭秘如何科学验证API服务商承诺的99.9% SLA:不靠宣传,而用Python脚本在真实网络中连续采样,严格定义“有效成功”,精准统计成功率、错误分布与延迟分位数,并提供可落地的监控代码、报告模板和采购验收清单。(239字)
|
9天前
|
人工智能 缓存 安全
客服机器人接入多个大模型后,AI 网关如何管住路由、限流和成本?
本文以客服团队为背景,用LiteLLM Proxy搭建本地可运行的LLM治理实验环境(v1.108.5 LTS),演示如何统一管控模型路由、多维限流(RPM/TPM/并发/预算)、Fallback降级、可观测性与安全审计,避免业务后端重复实现治理逻辑。
|
15天前
|
缓存 JSON API
大模型 API 费用异常上涨怎么排查:用单次成功任务成本定位变化发生在哪一步
当费用增速超调用量时,应计算“单次成功任务成本”(总费用÷验收通过数),并拆解为三个归因乘数:每任务调用次数、单次请求平均费用、任务通过率。通过本地JSON Lines日志+轻量Python脚本即可精准定位成本异动根源,无需建库。
|
16天前
|
人工智能 API PHP
大模型 API 请求没有到达网关?从 Cursor 的路由规则到服务端日志排查
Cursor自定义模型配置失败?根源常在请求路由逻辑,而非Key或地址错误。本文依据Cursor员工论坛回复,厘清OpenAI Override机制、模型命名规则与服务端验证方法,助你精准定位404/无请求等顽疾。(239字)
|
6天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
7269 18
|
6天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
2399 10
|
1天前
|
人工智能 安全 应用服务中间件
NGINX 爆出两处高危漏洞 可导致未经身份验证的远程代码执行
NGINX曝出两个高危漏洞(CVE-2026-123633和CVE-2026-123007),CVSS 9.2分,均属HTTP/2内存安全缺陷,无需认证即可远程执行代码。影响自2015年起的多个版本,静态站点亦受威胁。修复版本为开源版1.30.7/1.31.9。(239字)
1120 0
NGINX 爆出两处高危漏洞 可导致未经身份验证的远程代码执行

热门文章

最新文章