Async Task Queue
Async Task Queue 是将耗时操作从请求-响应链路中解耦出来的模式。在 AI Agent 应用中，它用于后台处理消息持久化、Embedding 生成、评估任务等。
#concept
#evergreen
#backend
#architecture
[!info] related notes
Async Task Queue
[!abstract] 一句话定义 Async Task Queue 把耗时、可延迟完成的工作从请求—响应链路移到后台 Worker。它缩短前台等待并削峰，但把原本同步可见的错误，转化为任务状态、重复执行、积压、重试和最终一致性问题。
基本模型
Client
→ API validates request
→ persist task / enqueue
→ return task_id
Broker / Queue
→ Worker claims task
→ execute side effect
→ ACK / retry / fail
→ update task status关键不变量：API 返回“已受理”不等于任务已经成功完成。
什么时候值得异步
适合：
- 图片、视频、OCR、Embedding 等长任务；
- 邮件、通知、报表、数据导出；
- 批量 Eval、索引重建；
- 突发流量需要削峰；
- 第三方服务慢或不稳定，但结果允许稍后完成。
不适合：
- 用户必须立即知道成败的短事务；
- 强依赖当前请求事务原子提交的动作；
- 没有任务状态、重试和观测能力的小系统。
任务状态机
pending
→ running
→ succeeded
→ failed / retrying / cancelled / dead-lettered建议保存：
task_id/ idempotency key；- task type 与 version；
- payload reference；
- status、attempt、next_run_at；
- owner / lease；
- created / started / completed time；
- last error 与 trace ID。
[!warning] Queue 不是任务数据库 Broker 负责交付，业务系统仍应有可查询的任务状态和结果。只靠消息是否还在 Queue，无法稳定回答用户“任务现在怎么样”。
ACK、Lease 与故障窗口
典型 Worker 流程：
receive / claim
→ mark or lease running
→ execute
→ persist result
→ ACK如果执行成功后、ACK 前崩溃，Broker 会再次投递。于是任务处理通常需要：
At-least-once Delivery
+ Idempotent Worker
+ Durable Task State如果先 ACK 再执行，Worker 随后崩溃则可能永久丢任务。
Retry 不是简单重新入队
Retry 需要：
- 区分瞬时错误和永久错误；
- 最大次数或总时间预算；
- Backoff + Jitter；
- 幂等副作用；
- Dead Letter / Manual Review；
- 保存每次 Attempt 的错误证据。
不可解析 Payload、权限失败或业务前置条件不满足，通常不应原样无限重试。
Backpressure 与积压
Queue Depth 增长只说明“进入速度长期高于离开速度”，还要定位原因：
producer rate increased?
consumer count decreased?
per-task latency increased?
downstream dependency slow?
poison task retry loop?
hot partition / unfair routing?治理手段：扩 Worker、限流入口、降低任务成本、按优先级隔离、设置有界容量、丢弃低价值任务或降级。
延迟、优先级与定时任务
- Delayed Queue：到时间后才可消费；
- Priority Queue：高优先任务先调度；
- Scheduled Job：由调度器产生任务；
- Retry Queue：失败后按下一次执行时间回到主链路。
优先级过多容易让低优先任务永久饥饿，必须监控等待时间而不只看总 Queue Depth。
取消语义
取消至少有三种状态：
pending task → remove / mark cancelled
running task → request cancellation cooperatively
completed task→ cannot undo; may need compensation“用户点击取消”不等于已经撤销外部副作用。Worker 必须在安全检查点读取取消状态，并明确不可逆阶段。
最小工程检查表
- API 返回
task_id，可查询状态和结果。 - Enqueue 与业务事务之间有 Outbox / 原子持久化策略。
- Worker 支持幂等、Lease、超时和取消。
- Retry 有分类、预算、Backoff 和 DLQ。
- Queue 有界，并监控 Depth、Age、Lag、Attempt 和成功率。
- Payload 有版本，敏感数据使用引用而不是整份复制。
- 部署和关闭时能停止接新任务并排空/释放在途任务。
Digital Biome