AI 工具调用失败怎样设计可重试错误

AI 工具调用失败时，最危险的写法是把所有错误都交给同一个重试循环。参数格式错了，重试不会改变参数；扣款、下单这类工具已经产生副作用时，盲目重放还可能重复执行。更稳妥的做法是先按错误责任边界分类，再让重试次数、等待时间和幂等保护共同决定下一步。

官方地址：https://developers.openai.com/api/docs/guides/function-calling

把工具调用失败拆成“输入不可修复、服务暂时不可用、业务明确拒绝”三类：只有暂时性错误进入有限重试，带副作用的调用必须配合幂等键，最终仍失败则返回可解释的兜底结果。

本文使用 OpenAI 工具调用文档作为接口背景，但错误分类、幂等键和重试预算是应用侧设计，不是模型或平台自动替你完成的动作。

先分清错误发生在哪一层

一次工具调用至少有三段责任：模型生成工具名和参数，应用校验并执行工具，工具再访问数据库或外部 API。OpenAI 的函数调用结构包含工具名称、调用 ID 和 JSON 参数；文档也提醒应用在真正执行函数前校验模型生成的参数。因此，解析失败和业务 API 超时不能共用一个错误码。

可以先建立一个面向重试决策的错误对象，把“能不能重试”从原始异常中提取出来：

// RetryDecision 把底层错误翻译成统一的重试决策。
// Retryable 只表示“值得再次尝试”，不代表可以无限重放。
type RetryDecision struct {
    Class     string // input、temporary、business 或 unknown
    Retryable bool   // 只有暂时性错误通常为 true
    DelayHint time.Duration // 服务端给出的等待建议
    SafeToReplay bool // 工具是否有幂等保护
}

func classify(err error, retryAfter time.Duration, idempotent bool) RetryDecision {
    // 参数校验失败属于输入问题，修改请求前重试没有意义。
    if errors.Is(err, ErrInvalidArguments) {
        return RetryDecision{Class: "input", SafeToReplay: idempotent}
    }
    // 限流、连接超时和临时过载可进入有限退避，但仍受预算约束。
    if errors.Is(err, ErrRateLimited) || errors.Is(err, context.DeadlineExceeded) {
        return RetryDecision{Class: "temporary", Retryable: true, DelayHint: retryAfter, SafeToReplay: idempotent}
    }
    // 业务拒绝通常需要修正业务状态，不能靠重放绕过规则。
    return RetryDecision{Class: "business", SafeToReplay: idempotent}
}

这里的关键不是错误名称，而是分类依据。参数 JSON 无法解析、缺少必填字段、工具名不存在，通常应回到模型或调用方修正；限流、网络断开、服务端过载和可恢复超时，才适合交给退避器；权限不足、余额不足、库存不足等业务拒绝，则应直接形成可读的失败结果。

哪些错误值得重试，哪些错误应该停止

OpenAI 错误码文档把 429 限流、503 服务暂时过载、连接错误和超时列为需要等待或稍后重试的场景，同时明确指出额度、组织或项目支出上限等计费限制不会因重试恢复。应用侧可以用下面的表先做决策：

不要只按 HTTP 状态码判断。一个返回 200 的工具也可能在 JSON 中携带业务失败；同样，网络超时并不等于服务端没有收到请求。如果调用带有写操作，重试前要先回答“第一次请求是否可能已经成功”。

重试控制器要同时管等待和副作用

重试策略建议采用“服务器提示优先、指数退避兜底、总预算封顶”的组合。存在 Retry-After 时至少等待它指定的时间；没有提示时使用带抖动的指数退避，例如 500ms、1s、2s、4s，并设置最大次数和最大总耗时。这样既能避开瞬时拥塞，也不会让一个会话无限占用资源。

// nextDelay 计算带上限和抖动的等待时间，避免多个请求同时重试。
func nextDelay(attempt int, retryAfter time.Duration, max time.Duration, r *rand.Rand) time.Duration {
    if retryAfter > 0 {
        // 服务端的 Retry-After 是最低等待提示，应用仍应受总预算约束。
        if retryAfter > max { return max }
        return retryAfter
    }
    base := 500 * time.Millisecond
    delay := base * time.Duration(1 max { delay = max }
    // 加少量随机量，降低并发调用在同一时刻再次撞上限流的概率。
    return delay + time.Duration(r.Int63n(int64(delay/4)+1))
}

幂等键要和业务动作绑定，而不是每次重试都新生成。第一次请求超时后，应用可以用相同幂等键查询或复用上一次结果；如果下游不支持幂等，宁可把结果标记为“执行状态未知”，交给人工或补偿任务处理，也不要把扣款、发货、写入等动作直接重放。

把日志和最终兜底纳入方案

每次调用至少记录调用 ID、工具名、参数摘要、错误类别、HTTP 状态、服务端 request ID、尝试次数、等待时长、是否带幂等键和最终结果。参数摘要要脱敏，尤其不要把密钥、令牌和完整用户隐私写进日志。

当预算耗尽时，兜底不能只是“重试失败”。对查询类工具可以返回缓存或稍后再试；对写操作应返回状态未知并创建补偿任务；对参数问题应把具体字段错误反馈给调用方。这样模型下一轮才有机会修正输入，而不是重复同一个坏请求。

落地时可以按这份清单收尾：

• 每个错误都有稳定类别，而不是只保存原始字符串。
• 429、超时和 503 有 Retry-After、指数退避、最大次数和总时长。
• 所有写工具都明确幂等键或“不可安全重放”的状态。
• 日志能关联同一个工具调用的多次尝试，并且完成脱敏。
• 预算耗尽后有查询降级、补偿任务或人工处理路径。

常见疑问

参数错误能不能让模型自动再试一次？

可以，但这属于“修正输入后重新生成”，不是对同一请求做网络重试。应把字段路径、允许值和工具名称反馈给模型，并限制修正轮数。

网络超时后一定要重试吗？

不一定。超时只说明调用方没有在期限内拿到结果，写操作可能已经在下游完成。先依靠幂等键查询结果；无法确认时进入状态未知和补偿流程。