Agent开发 09|Model Gateway:怎么选模型、做降级、算成本?

0 阅读19分钟

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 的超时预留28080 × 1 + 100 × 2
strong 的已知费用36080 × 3 + 20 × 6
当前预算占用640280 + 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:请求超时后怎样算费用?

记录结果与用量不确定,保留预留或其他保守估算,后续核对实际用量。不能直接算零,也不能把预留金额当成已经确认的账单。

试着回答:

  1. 主模型 SDK 重试三次,Gateway 又重试三次,可能产生什么问题?
  2. 备用模型不支持工具调用,能否删掉工具说明后继续?
  3. 先前补发工具已经成功,模型最后总结时超时,是否应该重跑补发?

参考思路:重试叠加会放大请求与成本;能力不满足不能静默改变任务契约;只恢复必要的模型交互,业务操作需要核对与幂等保护。

十、总结

模型网关让调用策略有一个统一落点,但不能靠统一接口掩盖模型差异。路由需要质量证据,重试需要明确条件,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|可观测性:怎样追踪一次任务并定位故障? 我们将把这些步骤关联到同一条可追查的执行链路。