BroadRouter

长时间运行的智能体:可靠的超时、重试与检查点

BroadNet Inference 团队 · 阅读约 4 分钟 · 发布于 · 更新于

把每次模型调用视为可丢弃的,把智能体的状态视为持久的。为每次调用设置超时,用流式输出发现卡顿,对 429、5xx 和中断的流做有上限的退避重试,并给每个有副作用的工具一个幂等键。每一步后保存消息列表,这样崩溃后能从上一个检查点恢复,而不是从头开始。

运行五分钟的智能体可以不管失败。运行五个小时的智能体则会遇到超时、429、中断的流,很可能还有一次重启。大多数讲长时间运行智能体的文章都在推销工作流引擎。你未必需要。本文介绍让一个普通的智能体循环连续运行数小时的五个习惯,并附上 OpenAI Python SDK 的代码。

智能体运行数小时会出什么问题?

故障 表现 应对的习惯
调用卡死或太慢 几分钟都没有回复 每次调用的超时、流式输出
速率限制或过载 429、5xx 有上限的退避重试
流中断 连接在 [DONE] 之前结束 视为不完整,重试这次调用
副作用重复 重试后工具运行了两次 幂等键
进程崩溃或部署 智能体从第 1 步重新开始 每一步保存检查点

1. 一次调用最多允许多长时间?

OpenAI Python SDK 的 README 说,请求默认在 10 分钟后超时,某些错误会重试两次。用于智能体时,两者都自己设置,免得行为在你不知情时改变:

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"],
                timeout=300, max_retries=4)

超时要根据数据来定。把每次调用的耗时记录一天;把超时设得远高于最慢的成功调用。大的提示词启动更慢,推理模型也会先思考再输出。按 约每秒 100 个 token 计算,单是 8,000 个输出 token 就要一分多钟。另外为每个任务设一个总时长预算,防止一个停不下来的循环跑上一整夜。

2. 长时间运行的智能体为什么要用流式输出?

流式输出在模型工作时给你一个信号。没有它,慢调用和断掉的连接在超时触发之前看起来一模一样。有了它,你能看到数据块陆续到达,还能在最后一个数据块里拿到 token 用量。

BroadNet 的流式规则:一直读到字面上的 data: [DONE] 这一行。如果连接在此之前关闭,回答就是不完整的。记下 X-Request-ID,然后决定是否发起新请求。完整的流式输出指南。

def call_streaming(messages, tools=None):
    parts, done = [], False
    stream = client.chat.completions.create(
        model="broadnet/glm-5.3", messages=messages, tools=tools, stream=True,
        stream_options={"include_usage": True}, max_tokens=8000)
    for chunk in stream:
        if chunk.choices and chunk.choices[0].finish_reason:
            done = True
        if chunk.choices and chunk.choices[0].delta.content:
            parts.append(chunk.choices[0].delta.content)
    if not done:
        raise IncompleteStream()   # retry the whole call
    return "".join(parts)

这个示例只收集文本。如果你以流式方式接收工具调用,还要按 index 累积 delta.tool_calls。

3. 应该重试什么?

SDK 已经会重试连接错误、408、409、429 和 5xx。只为它看不到的情况(比如不完整的流)在上面再加一层你自己的重试:

  1. 重试: 连接错误、429、5xx、不完整的流。使用带随机抖动和上限的指数退避,例如最多 4 次。
  2. 修复,不要重试: 400、401、402、403、413、422。这些错误每次都会以同样的方式失败。见错误码以及何时重试。
  3. 按任务设置重试预算,而不仅是按调用。十个步骤各重试四次,就是四十次额外调用。
  4. 重试用完后切换服务商。 如果一次运行必须扛住服务商故障,就把连接错误、5xx 和限流导致的 429 转到第二个服务商。大模型 API 故障切换给出了客户端代码和熔断器。

按量付费时,每次重试都是一次新的推理,会再次计费。按量付费的密钥还限制每分钟 30 个请求、同时 4 个进行中的请求,所以重试风暴很快就会撞上速率限制;速率限制计算器能显示你的智能体还有多少余量。429 处理一文详细讲了退避。在不限量套餐上,重试不额外收费,但运行期间会占用会话唯一的请求槽位。

4. 怎样让工具调用幂等?

模型调用没有副作用,工具调用可能有。如果智能体在 send_invoice 运行之后、步骤保存之前崩溃,重启后的智能体会再发一次。

给每个有副作用的调用一个由任务和步骤派生出的幂等键,执行前先检查,如果已经记录过就跳过这次调用:

def run_side_effect(task_id, step, call, store):
    key = f"{task_id}:{step}:{call.id}"
    if store.done(key):
        return store.result(key)       # already ran: return the saved result
    result = execute(call)             # pass key to the API if it supports one
    store.save(key, result)
    return result

许多支付和消息 API 接受幂等键请求头。如果支持,就把你的键传过去。

5. 怎样给智能体保存检查点?

每完成一步就保存:消息列表、步骤编号和副作用的键。启动时,如果有最新的检查点就加载它。

def save_checkpoint(path, step, messages):
    tmp = path + ".tmp"
    with open(tmp, "w") as f:
        json.dump({"step": step, "messages": messages}, f)
    os.replace(tmp, path)   # atomic on the same filesystem

先写入临时文件再重命名,意味着写到一半崩溃也绝不会留下半个检查点。对于非常长的会话,还要把摘要存进检查点:用简短的摘要替换旧的对话轮次,这样恢复后的智能体不必重新加载庞大的历史。这能让你保持在上下文窗口之内,即便是 DeepSeek V4.1 Flash 的 1,048,576 token。

通宵运行前的检查清单

  1. 在客户端上显式设置超时和 max_retries。
  2. 开启流式输出并带上 include_usage,不完整的流要重试。
  3. 每个任务有重试预算和总时长上限。
  4. 每个会写入、发送或付款的工具都有幂等键。
  5. 每一步后以原子方式写入检查点。
  6. 日志包含步骤编号、耗时、token 数和 X-Request-ID。

如果你同时运行多个智能体,请阅读用固定费用并行运行编程智能体和多智能体方案的成本。

BroadNet Inference 的定位

BroadNet Inference 使用标准的 chat completions 流式输出,返回可记录的 X-Request-ID 响应头,并在文档中写明哪些错误应该重试,所以上面的模式可以照搬使用。对于整天运行的智能体,不限量套餐每个会话每月 $60,在 DeepSeek V4.1 Flash 上不计 token,重试因此免费。注意,Meteor 的一小时在购买一小时后结束,Orbit 的一周在七天后结束,所以长任务必须在这个期限内完成,或者改用会自动续期的 Full Moon 会话。套餐见 inference.broadnet.ai/plans。

常见问题

智能体里的大模型 API 调用,超时设多少合适?

要长到能容纳最慢的正常调用,又要短到能发现卡死的调用。OpenAI Python SDK 默认是 10 分钟。许多智能体在开启流式输出时每次调用设 2 到 5 分钟,并为每个任务另设一个总时长上限。

智能体应该重试哪些大模型 API 错误?

对连接错误、429 和 5xx 做有上限的指数退避重试,并加上随机抖动。400、401、402、403、413 和 422 要修复而不是重试。在 BroadNet 上,还要为每次失败记录 X-Request-ID 响应头。

重试一次 chat completion 安全吗?

模型调用本身没有副作用,所以安全,但它是一次新的推理,按量付费时会再次计费。危险在工具上。除非工具使用幂等键,否则重试的步骤可能会把同一封邮件发两次。

智能体崩溃后怎么恢复?

每完成一步就保存消息列表和步骤编号,在执行副作用之前写入其 ID,启动时重新加载。智能体会从上一个保存的步骤继续。

长时间运行的智能体需要不限量套餐吗?

不需要,但按量付费时重试和长上下文的费用会累积。在 BroadNet 的不限量套餐上,DeepSeek V4.1 Flash 不计 token,所以重试不额外收费,不过每个会话仍然一次只能运行一个请求。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity