大模型异步任务回调：结果通知要能防重复

一、长任务不能只靠前端轮询

文档解析、批量生成、代码分析、视频总结这类大模型任务通常耗时较长。后端如果只让前端轮询状态，简单但不够可靠：页面关闭怎么办，重复刷新怎么办，任务完成后谁通知下游系统？

异步任务需要状态机和回调机制，而回调的第一原则是防重复。

二、任务状态要明确

stateDiagram-v2
  [*] --> queued
  queued --> running
  running --> succeeded
  running --> failed
  running --> canceled
  failed --> retrying
  retrying --> running

状态机要写进数据库，而不是只存在内存里。服务重启后，任务仍然能恢复或被补偿。

CREATE TABLE ai_task (
  task_id VARCHAR(64) PRIMARY KEY,
  status VARCHAR(32),
  callback_url VARCHAR(512),
  result_uri VARCHAR(512),
  updated_at TIMESTAMP
);

任务状态清楚，回调才有依据。

三、回调必须幂等

网络超时、下游 500、网关重试，都可能导致同一个结果回调多次。接收方必须用 task_id 或 callback_id 做幂等处理。

if (callbackRepository.exists(callbackId)) {
    return CallbackResult.duplicate();
}
callbackRepository.save(callbackId);

幂等记录要先写，再执行业务动作。否则并发回调仍可能重复触发。

四、失败重试要有边界

回调失败不能无限重试。要区分临时错误、永久错误和配置错误，并设置最大次数、退避策略和死信队列。

callback_retry:
  max_attempts: 8
  backoff: exponential
  retry_on: [timeout, 502, 503]
  no_retry_on: [400, 401, 403]

还要记录每次回调的请求、响应码、耗时和错误原因。否则用户只看到任务完成了，下游却没收到通知。

最后，回调安全也要考虑。签名、时间戳、防重放、租户校验都不能省。异步回调是系统边界，不是内部函数调用。

任务结果也不要直接塞进回调体。大结果可以放到对象存储或结果表里，回调只传 result_uri、校验值和状态。这样可以避免回调超时，也方便接收方按需拉取。

callback_payload:
  task_id: required
  status: succeeded
  result_uri: required
  checksum: required

还要处理用户取消。任务取消后，正在执行的模型调用不一定能立刻中断，回调服务必须识别 canceled 状态，避免晚到的成功结果覆盖取消结果。

最后，回调链路要有补偿入口。下游长期不可用时，任务结果不能丢，可以提供后台重推、手工确认和死信恢复能力。

回调顺序也要考虑。同一个会话里多个异步任务并发执行，后完成的旧任务不应该覆盖先完成的新任务。可以用 task_version、created_at 或业务状态版本做保护。

callback_order_guard:
  task_version: required
  reject_stale_result: true
  compare_business_state: true

五、总结

大模型异步任务回调要依赖持久化状态机、幂等键、重试边界、死信处理和安全签名。

结果通知要能防重复。长任务可靠，靠的是状态和幂等，不是多试几次。