Agent开发 09|Model Gateway:怎么选模型、做降级、算成本?
《Agent开发》系列 · 第 09 篇
设想一个订单助手原来只调用一个模型。随着需求增加,团队发现:提取订单号希望更快,分析多段异常日志需要更好的判断能力,生成最终解释又不一定需要昂贵模型。
接着,模型服务开始偶尔限流。有人在查询模块加重试,有人在审批模块加备用模型,还有人在报表里统计 Token。几周之后,大家很难回答:同一个任务到底调用了哪些模型,失败后重试了几次,花了多少钱?
这些重复的调用管理工作,可以集中到一层组件中。业务代码向它表达“需要什么能力、允许多少时间和费用”,它负责选择允许使用的模型、处理服务错误、记录用量,并返回统一结果。这一层就是 Model Gateway(模型网关)。
本篇从订单助手的调用链出发,解释路由、Fallback、重试、超时和成本控制怎样配合,并通过一个可运行的 Mock 示例验证故障路径。
一、Model Gateway 在系统里做什么?
1.1 它管理模型调用,不替代 Agent Runtime
Runtime 是后端中组织任务步骤、模型调用、工具执行与状态维护的程序。它在需要模型判断时调用 Gateway:
用户任务
↓
Runtime:构建上下文,说明本轮需要的能力与预算
↓
Model Gateway:选择允许的模型,调用、重试、记录用量
↓
模型返回回答或工具请求
↓
Runtime:校验并执行工具,保存结果,决定是否继续
模型返回“查询订单 1001”的请求,不表示 Gateway 应直接查询订单。工具执行、审批和业务权限仍属于 Runtime 与业务系统的职责。
Gateway 可以是后端中的一个模块,不一定独立部署成服务。只有多个应用需要共享策略、配额、密钥管理或调用观测时,才更值得评估独立服务的收益与运维成本。
1.2 统一接口不等于抹平所有差异
上层通常希望得到一致的请求与响应结构,例如输入消息、可用工具、输出限制、模型标识、停止原因、工具请求和用量。
但模型可能在工具格式、图片支持、结构化输出、流式事件和 Token 计数上不同。因此,Gateway 需要适配器转换协议,同时保留能力差异和必要的原始标识。
某个模型不支持当前工具协议,不能悄悄删掉工具说明后当作同等调用成功。应该排除该模型,或明确返回能力不满足。
二、模型怎么选:先定义任务,再谈路由
2.1 模型选择不能只看名字和价格
订单号提取、知识问答、复杂排障和补发建议,对模型的要求不同。选择时至少比较:
| 维度 | 在订单助手中要观察什么 |
|---|---|
| 任务质量 | 订单号提取、工具选择、事实解释是否正确 |
| 能力兼容 | 是否支持所需工具、输入类型与输出格式 |
| 时延 | 首次输出与完整结果分别需要多久 |
| 费用 | 一次完整任务的总调用和重试成本 |
| 稳定性 | 限流、错误和长尾延迟如何 |
| 数据边界 | 该租户的数据允许发到哪些服务 |
这些需要用代表性任务评测。一个单次 Token 价格更低的模型,如果经常选错工具、增加循环或需要多次修复,单任务成本未必更低。
本篇不提供会随时间变化的模型排行榜。具体选型应以当前候选版本在你的评测集上的结果为依据。
2.2 Routing:根据条件选择调用路径
Routing(路由)就是决定本次请求交给哪个模型。例如,规则明确的字段提取优先使用经过验证的快速模型;复杂日志分析使用另一条已验证路径。
路由可以从简单规则开始:任务类型、输入长度、是否需要图片、是否需要工具、租户允许列表和剩余预算。只有规则不足以稳定判断时,再考虑分类模型或更复杂的策略。
模型路由本身也会出错。把关键任务误分到能力不足的模型,同样需要进入评测。不能只验证每个模型单独表现,却不检查最终的路由组合。
2.3 切换模型不应改变业务授权
某个模型认为应该补发,另一个模型认为应先查询,两者是建议不同。允许访问哪个订单、补发多少金币、审批是否有效,不能随着模型变化而改变。
模型供应商允许列表也应来自可信配置。不能让用户一句“换到另一家服务试试”就把受限制的数据发送到未授权目的地。
三、重试与 Fallback:失败后应该做什么?
3.1 Retry 是再试一次,Fallback 是换一条已允许路径
临时服务故障后再次调用同一模型,是 Retry(重试);主模型不可用时切换到备用模型或其他处理路径,是 Fallback(降级或回退)。
备用模型不一定更弱、更便宜。关键是它已经验证过能承担当前任务,并满足数据和能力约束。降级也可以是返回稍后重试、排队或转人工,而不是必须继续调用另一个模型。
3.2 不同错误需要不同处理
| 情况 | 通常应考虑的处理 |
|---|---|
| 临时服务错误 | 在总预算内有限重试,必要时切换已验证路径 |
| 限流 | 尊重等待提示、退避或排队,避免立刻增加流量 |
| 请求参数错误 | 修正请求,重复发送相同错误通常无效 |
| 认证或权限错误 | 停止并排查配置,不自动绕过访问限制 |
| 输入超过容量 | 调整上下文或任务,不盲目原样重试 |
| 客户端超时 | 结果和用量可能不确定,记录后按策略处理 |
| 回答不符合要求 | 属于质量问题,结合校验与评测决定是否修复或升级模型 |
不要把安全拒绝当作“服务故障”,再通过切换模型绕过既定限制。质量重试、网络重试和业务工具重试也应分开记录。
3.3 为什么需要退避和抖动?
服务已经繁忙时,很多客户端同时立即重试,会进一步增加压力。退避让后续重试间隔增大,抖动则在允许范围内加入随机等待,减少大量客户端同时再次发起请求。
重试还可能在多层叠加:SDK 重试三次,Gateway 再试三次,Runtime 又重做整步,实际请求数可能远超预期。因此需要明确由哪一层负责重试,并设置跨模型共享的总尝试次数。AWS 超时、重试与退避说明
3.4 模型请求重试与业务写入重试不能混为一谈
重新请求一次模型生成,可能增加费用并产生不同工具建议;重新执行一次补发工具,可能改变真实余额。
Gateway 的重试不能顺带重放已经执行过的业务工具。工具的幂等与结果核对仍需由 Runtime 和业务服务负责。即使模型调用成功恢复,也不代表之前的业务操作没有发生。
四、超时和限流:控制的是哪一种资源?
4.1 单次超时与总时限
单次超时限制一次模型调用等待多久;总时限限制本轮经过排队、尝试、退避与切换后,最多花多长时间。
如果总时限只剩 200 毫秒,不能给下一次调用重新分配完整的 30 秒。应把剩余时间传给底层调用,并在没有余量时停止。
真实网络还可能有连接、读取、流式空闲和整体请求等不同超时。仅在调用前看一次时钟,不能保证阻塞调用会按时停止;底层客户端必须支持相应超时和取消机制。
4.2 流式输出的特殊情况
模型已经输出了一半回答后失败,不能把备用模型从头生成的内容直接拼到用户看到的文字后面。需要明确中断、重新生成或恢复策略,并记录哪些内容已经交付。
工具请求也必须完整解析和校验后才能执行,不能因为流里刚出现一段看似完整的参数就立即写入业务系统。
4.3 限流不仅是每秒请求数
模型服务可能同时限制请求次数、Token 速率和并发数。应用也需要避免某个租户占满共享资源。
可以在入口检查配额,控制同时进行的调用数量,对短暂峰值有限排队,并为队列设置最大长度和等待时间。排队时间也属于用户等待的一部分。
本篇 Demo 模拟服务端限流响应与等待提示,没有实现真实分布式限流器、排队系统或多租户配额。它们属于网关扩展职责,不能因为代码处理了一个 rate_limit 字符串就宣称已经具备。
五、Token 与成本:不要把未知当作零
5.1 一次请求的费用需要哪些数据?
最简教学公式是:
费用 = 输入 Token × 输入单价 + 输出 Token × 输出单价
任务费用 = 各次实际调用费用的总和
真实服务可能还有缓存、推理、图片、音频、工具等不同计量项,必须按具体接口、价格版本和账单口径核对。本篇使用虚构整数单价,不代表任何服务的真实价格。
同一份文本在不同模型下的 Token 数也可能不同。模型切换时需要兼容的计数与预算方式,不能原封不动复用另一模型的估算并当作精确值。
5.2 调用前预留,调用后结算
在教学示例中,输入 Token 数已知,输出最多 100 Token。调用前先按上限预留预算,收到可信用量后再结算实际费用,并释放多余部分。
如果超时,没有收到用量,不能推断模型没有执行。应将本次用量记为未知,并保留一定预算占用,等待后续核对。
| 记录 | 表达什么 |
|---|---|
| 已报告用量对应费用 | 按当前计量与价格记录计算的已知部分 |
| 未知请求预留 | 尚未确认的潜在支出,不是已经确认的账单 |
| 预算占用 | 已知费用与仍保留的预留之和 |
真实计费可能与本地估算不同。预留是一种控制策略,不是没有边界条件的账单上限保证。还要监控估算偏差、补充供应商用量,并核对延迟到达的账单。
5.3 预算也要考虑并发
两个并发请求如果都读取同一个剩余额度,再各自发起调用,就可能超支。生产预算需要原子的预留与结算,不能只靠一个进程里的普通变量。
本例 Gateway 对象中的账本用于串行教学调用。同一对象的多次调用共享预算,但不提供多线程、多进程或持久化保证。
六、代码实践:限流、超时与备用模型
6.1 示例里有哪些组件?
完整代码见附录,配套文件为 demo/09-model-gateway/model_gateway.py。Python 3.10+,无第三方依赖。
Request 表示已归一化的需求;Model 是脚本适配器;Outcome 描述一次模拟响应;Gateway 负责选择、尝试与记账。
没有真实模型、网络调用或 Tokenizer。 时间由虚拟时钟推进,不实际等待;价格是虚构的“微单位/Token”。示例输出只能验证程序控制逻辑,不能用于比较模型质量或真实性能。
6.2 一条请求经过三次尝试
第一次:fast 返回限流,脚本明确报告用量为零
↓ 等待 0.2 个虚拟秒
第二次:fast 超时,用量未知,保留预留
↓ 切换已允许且支持工具的模型
第三次:strong 成功,按脚本用量结算
只有第一次脚本明确给出零用量,才记为零;这不意味着现实中的所有限流响应都免费。
保存附录为 model_gateway.py,在文件所在目录运行:
python3 model_gateway.py
结果使用 strong,共尝试 3 次,虚拟耗时为 0.85 秒。账本中:
| 项目 | 示例数值 | 算法 |
|---|---|---|
| fast 的超时预留 | 280 | 80 × 1 + 100 × 2 |
| strong 的已知费用 | 360 | 80 × 3 + 20 × 6 |
| 当前预算占用 | 640 | 280 + 360 |
第三次调用前,需要为 strong 预留 80 × 3 + 100 × 6 = 840。因此,虽然成功后预算占用只有 640,如果总预算只有 1000,第三次调用仍会被拒绝:当时已经保留 280,再预留 840 会达到 1120。
这是保守预留的取舍。不能根据事后才知道的 20 个输出 Token,反过来批准调用前的预算。
6.3 代码怎样控制边界?
尝试前检查剩余时限和预算;所有候选模型共享尝试上限,而不是每换一个模型就把总次数清零。
if self.known_cost + self.held_cost + reserve > self.budget:
raise GatewayError("预算不足,未发出下一次请求")
self.held_cost += reserve
收到用量时,释放该次预留并记入已知费用。没有用量则保留预留,并在事件里记录 usage: unknown 和 cost: null。
本例适配器约定报告的输入与输出不超过请求提供的上限。违反约定会报错并保留待核对记录,不悄悄接受。真实系统中估算与实际用量偏差需要更完整的核对机制,不能照搬这个约定就认为供应商计费也被限制住了。
6.4 如何验证故障处理?
配套测试运行:
python3 -m unittest -v test_model_gateway.py
测试覆盖预算不足时不发出备用请求、认证错误不重试、能力与允许列表过滤、总时限、等待提示超过截止时间、全局尝试上限、未知用量预留以及串行调用共享预算。
这些测试没有证明真实 HTTP 请求会在 0.4 秒被取消。示例的脚本适配器按虚拟时限返回超时,真实接入时必须再次验证底层客户端的超时、取消、重试和用量行为。
七、成本和延迟优化,应该从哪里开始?
先按任务统计模型轮数、输入输出量、重试和工具耗时,找出主要成本来源。可能是历史无限增长,也可能是同一查询被重复调用,不能只盯着模型单价。
| 方法 | 可能收益 | 需要验证的边界 |
|---|---|---|
| 减少无效循环 | 同时降低延迟与费用 | 是否过早终止必要调查 |
| 缩减无关上下文 | 减少输入开销 | 是否丢失事实、约束和证据 |
| 按任务选择模型 | 在质量可接受时降低成本 | 路由是否引入新的失败 |
| 限制输出长度 | 减少输出开销 | 是否截断关键结论或工具请求 |
| 缓存稳定内容 | 减少重复计算 | 权限、时效和缓存口径 |
| 并行独立步骤 | 缩短关键路径 | 是否存在数据依赖,是否增加峰值费用 |
需要区分模型服务的输入缓存,与应用缓存完整回答。后者可能复用过时订单状态,甚至泄露其他用户数据。缓存键应覆盖必要的租户、权限、输入与配置版本,并明确失效规则;动态资产状态不能因为“问题长得像”就直接复用答案。
八、模型升级怎样做灰度与回退?
Gateway 可以把业务模型别名映射到具体版本,但映射改变仍应经过回归评测。记录本次实际使用的模型和配置版本,避免日志里永远只有一个模糊的“默认模型”。
小范围启用新版本时,比较任务成功率、工具参数错误、关键回归、延迟和成本。会话或任务内是否保持同一配置,应事先约定,避免执行到一半突然改变能力与输出协议。
回退模型只能影响后续调用,不能撤销已经发出的业务操作。旧任务的状态、工具协议与新旧模型是否兼容,也需要在发布前检查。
九、面试与自查
Q:Model Gateway 与 Agent Runtime 有什么区别?
Gateway 集中管理模型接口、选择、故障与用量;Runtime 管理任务执行、上下文、工具、状态和停止条件。Gateway 返回的工具请求仍需 Runtime 校验和执行。
Q:怎样设计模型降级?
先限定允许的候选与能力要求,根据错误类型决定是否重试或切换;所有尝试共享总时限、次数和费用预算。备用方案需要事先评测,切换不能绕过数据边界与业务权限。
Q:请求超时后怎样算费用?
记录结果与用量不确定,保留预留或其他保守估算,后续核对实际用量。不能直接算零,也不能把预留金额当成已经确认的账单。
试着回答:
- 主模型 SDK 重试三次,Gateway 又重试三次,可能产生什么问题?
- 备用模型不支持工具调用,能否删掉工具说明后继续?
- 先前补发工具已经成功,模型最后总结时超时,是否应该重跑补发?
参考思路:重试叠加会放大请求与成本;能力不满足不能静默改变任务契约;只恢复必要的模型交互,业务操作需要核对与幂等保护。
十、总结
模型网关让调用策略有一个统一落点,但不能靠统一接口掩盖模型差异。路由需要质量证据,重试需要明确条件,Fallback 需要能力与权限边界,预算需要区分已知和未知支出。
先把一次调用经过了什么、为什么切换、哪些费用已经确认记录清楚,再逐步加入复杂策略,才能让模型管理保持可解释。
参考资料
附录:完整可运行代码
文件名:model_gateway.py,与配套文件一致。
"""模型网关教学:脚本模型、虚拟时间、虚构价格,不发送网络请求。"""
from dataclasses import dataclass, field
import json
import math
class GatewayError(RuntimeError):
pass
@dataclass(frozen=True)
class Request:
input_tokens: int
max_output_tokens: int
requires_tools: bool = True
allowed_models: tuple = ("fast", "strong")
@dataclass(frozen=True)
class Outcome:
kind: str
latency: float
usage: tuple | None = None
retry_after: float = 0.0
text: str = "请先核对订单的最终发放状态。"
@dataclass
class Model:
name: str
input_price: int # 虚构的微单位/Token,不代表真实价格。
output_price: int
supports_tools: bool
outcomes: list = field(default_factory=list)
def call(self, timeout):
if not self.outcomes:
raise GatewayError("脚本响应耗尽")
outcome = self.outcomes.pop(0)
if not math.isfinite(outcome.latency) or outcome.latency < 0 or not math.isfinite(outcome.retry_after) or outcome.retry_after < 0:
raise GatewayError("脚本时间参数非法")
if outcome.latency > timeout:
# 客户端先超时,无法确认服务端用量。
return Outcome("timeout", timeout, None)
return outcome
class Gateway:
def __init__(self, models, budget=2000, deadline=2.0, max_attempts=3):
if type(budget) is not int or budget < 0 or not math.isfinite(deadline) or deadline <= 0:
raise ValueError("预算与时限非法")
if type(max_attempts) is not int or max_attempts <= 0:
raise ValueError("最大尝试次数必须是正整数")
if len({m.name for m in models}) != len(models):
raise ValueError("模型名称不能重复")
if any(type(p) is not int or p < 0 for m in models for p in (m.input_price, m.output_price)):
raise ValueError("价格必须为非负整数")
self.models = models
self.budget = budget
self.deadline = deadline # 单次 generate 的虚拟总时限。
self.max_attempts = max_attempts
self.now = 0.0
self.known_cost = 0
self.held_cost = 0
self.events = []
def generate(self, request):
if any(type(v) is not int or v < 0 for v in (request.input_tokens, request.max_output_tokens)):
raise ValueError("Token 数必须是非负整数")
if request.max_output_tokens == 0:
raise ValueError("输出上限必须大于零")
candidates = [m for m in self.models if m.name in request.allowed_models
and (not request.requires_tools or m.supports_tools)]
if not candidates:
raise GatewayError("没有同时满足权限与能力要求的模型")
started = self.now
attempts = 0
for model in candidates:
# 每个模型最多两次,但所有模型共享总尝试上限。
for local_attempt in range(2):
remaining = self.deadline - (self.now - started)
if attempts >= self.max_attempts:
raise GatewayError("总尝试次数耗尽")
if remaining <= 0:
raise GatewayError("总时限耗尽")
reserve = request.input_tokens*model.input_price + request.max_output_tokens*model.output_price
if self.known_cost + self.held_cost + reserve > self.budget:
raise GatewayError("预算不足,未发出下一次请求")
self.held_cost += reserve
attempts += 1
timeout = min(0.4, remaining)
event = {"attempt": attempts, "model": model.name, "reserved": reserve,
"status": "in_flight", "usage": "unknown", "cost": None}
self.events.append(event)
try:
outcome = model.call(timeout)
except Exception:
event["status"] = "adapter_error"
raise # 无法确认用量,保留预留,不继续自动降级。
self.now += outcome.latency
event["status"] = outcome.kind
if outcome.usage is not None:
valid = (len(outcome.usage) == 2
and all(type(x) is int and x >= 0 for x in outcome.usage)
and outcome.usage[0] <= request.input_tokens
and outcome.usage[1] <= request.max_output_tokens)
if not valid:
event["status"] = "usage_contract_error"
raise GatewayError("用量违反教学适配器约定,需要核对")
cost = outcome.usage[0]*model.input_price + outcome.usage[1]*model.output_price
self.held_cost -= reserve
self.known_cost += cost
event.update(usage="reported_mock", cost=cost)
if outcome.kind == "success":
return {"text": outcome.text, "model": model.name,
"attempts": attempts, "elapsed": round(self.now-started, 6)}
if outcome.kind not in {"rate_limit", "transient", "timeout"}:
raise GatewayError("不可自动重试的错误: " + outcome.kind)
# 超时在本示例中直接尝试下一个允许模型;未知用量仍保留预留。
if outcome.kind == "timeout" or local_attempt == 1:
break
delay = max(0.1 * (2**local_attempt), outcome.retry_after)
if self.now - started + delay >= self.deadline:
raise GatewayError("退避后没有剩余执行时间")
if attempts >= self.max_attempts:
raise GatewayError("总尝试次数耗尽")
self.now += delay # 虚拟时钟,无真实 sleep;生产应使用异步等待和抖动。
raise GatewayError("允许的模型均未返回成功结果")
def report(self):
return {"known_mock_cost": self.known_cost, "held_for_unknown": self.held_cost,
"occupied_budget": self.known_cost+self.held_cost, "events": self.events}
def demo_gateway(budget=2000):
return Gateway([
Model("fast", 1, 2, True, [
Outcome("rate_limit", 0.05, (0, 0), retry_after=0.2),
Outcome("timeout", 0.4, None),
]),
Model("strong", 3, 6, True, [Outcome("success", 0.2, (80, 20))]),
], budget=budget)
def main():
gateway = demo_gateway()
result = gateway.generate(Request(80, 100))
print("结果:", json.dumps(result, ensure_ascii=False))
print("账本:", json.dumps(gateway.report(), ensure_ascii=False, indent=2))
limited = demo_gateway(budget=1000)
try:
limited.generate(Request(80, 100))
except GatewayError as error:
print("低预算场景:", error)
print("已尝试模型:", [e["model"] for e in limited.events])
if __name__ == "__main__":
main()
可以调整总预算和时限,观察请求会在第几次尝试之前停止,再对照事件账本解释原因。看清“没有调用”“调用失败”和“用量未知”的区别,才能真正理解降级与预算控制。
当模型、检索与工具都参与执行,单靠一条错误日志已经很难定位问题。下一篇:Agent开发 10|可观测性:怎样追踪一次任务并定位故障? 我们将把这些步骤关联到同一条可追查的执行链路。