# RabbitMQ 一崩溃就丢排队任务，除非你另作设置

> 花一个晚上配好持久化队列、安全的 worker 和返回 202 的 API，耗时数分钟的模型调用就不会再超时或丢失。

原文: https://fdetimes.net/zh/guides/rabbitmq-queue-long-running-ai-jobs-http-202/

RabbitMQ 有个默认行为常让人踩坑：broker 退出或崩溃时，除非事先另作设置，它会忘掉所有队列和消息。对一个要跑五分钟的 AI 任务来说，这个默认行为意味着客户点了“分析”，等了半天，什么也没拿到。

大多数 LLM 演示都在 HTTP 请求里直接调用模型，一直保持连接，直到结果返回。这在笔记本上行得通。到了客户环境，就会遇到负载均衡器超时、客户端重试造成重复任务、worker 重启导致任务丢失等问题。

本指南按在客户现场最合理的顺序搭一条小型流水线：先做持久化队列，再写安全的 worker，最后实现异步 API。整个过程大约一个晚上，做完还能在面试中拿出来展示。

## 要搭建的是什么？

AWS 把消息队列定义为服务之间的一种异步通信方式，用来把繁重的处理任务与应用的其他部分分开。调用模型正是这类繁重任务。

整个流程分四部分。客户端发送 `POST /jobs`，立即收到 HTTP 202。API 把任务打包成消息，推入 `ai_jobs` 队列。worker 取出消息、调用模型并更新状态，客户端则轮询 `GET /jobs/{id}` 查看结果。

需要准备 Python 3、`pika` 库（RabbitMQ 官方教程使用的客户端），以及按官方说明安装、运行在 `localhost` 上的 RabbitMQ。下面的代码经过精简，只为说明思路：没有连接配置，没有重连处理，任务状态也只存在内存里。

## 第 1 步：重启后依然存在的队列

RabbitMQ 的 Work Queues 教程描述的正是这个问题：与其立即执行资源密集型任务并等待结果，不如把它打包成消息发到队列。要让消息在崩溃后保留下来，队列和消息都必须标记为持久化。

```python
import json, pika

conn = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
ch = conn.channel()
ch.queue_declare(queue='ai_jobs', durable=True)

def enqueue(job: dict):
    ch.basic_publish(
        exchange='',
        routing_key='ai_jobs',
        body=json.dumps(job),
        properties=pika.BasicProperties(
            delivery_mode=pika.DeliveryMode.Persistent),
    )
```

验证：发送几个任务，重启 RabbitMQ，看消息是否还在队列里。如果队列空了，说明两处之中漏掉了 `durable=True` 或 `delivery_mode`。

## 第 2 步：worker 在任务完成后才 ack

这一步是保护长任务的关键。如果 worker 在 ack 之前挂掉，RabbitMQ 会认为消息没有处理完，把它放回队列。要做到这一点，必须手动 ack，而且 ack 要放在最后一行，而不是第一行。

```python
ch.basic_qos(prefetch_count=1)

def handle(ch, method, props, body):
    job = json.loads(body)
    set_status(job['id'], 'Running')
    result = run_model(job)          # 调用 LLM，可能耗时数分钟
    set_status(job['id'], 'Succeeded', result=result)
    ch.basic_ack(delivery_tag=method.delivery_tag)

ch.basic_consume(queue='ai_jobs', on_message_callback=handle)
ch.start_consuming()
```

这个 handler 还没有捕获异常。如果 `run_model` 抛出错误，任务永远不会被标记为 Failed。本指南最后关于死信队列的一节会补上这部分。

`basic_qos(prefetch_count=1)` 这一行告诉 RabbitMQ，一次最多只给每个 worker 分配一条消息。设想有两个 worker，任务交替到来：总结一份合同要 10 分钟，给一封邮件分类要 10 秒。

如果不设 prefetch，任务严格轮流分发，所有 10 分钟的任务可能都落到同一个 worker 上，另一个却闲着。prefetch 设为 1 后，哪个 worker 先空闲，就由它领取下一个任务，队列便会按每个任务的实际耗时来均衡负载。

验证：让 `run_model` 休眠 60 秒，在第 30 秒杀掉 worker 再重新启动。任务应当从头再跑一遍。由此带来的要求是：`run_model` 必须能安全地多次执行，因为同一个任务可能被处理两次。

## 第 3 步：API 返回 202，不让客户端干等

Azure Architecture Center 中的 Async Request-Reply 模式讲的是面向客户端的这一侧。API 立即返回 HTTP 202（Accepted），确认已收到请求。响应中包含 `Location` 头，指向客户端轮询状态的 URL，还有 `Retry-After` 头，建议下次轮询前等待多久。

网络不稳定时，所有客户端都会重试。因此 Microsoft 建议使用 `Idempotency-Key`：后端收到已经见过的 key 时，返回已有的状态资源，而不是再往队列里推一个工作项。下面的示意代码不依赖任何框架，并拒绝所有不带 key 的请求：

```python
JOBS, KEYS = {}, {}   # 简化写法：生产环境请使用数据库

def post_jobs(request):
    key = request.headers.get('Idempotency-Key')
    if not key:
        return 400, {'error': '缺少 Idempotency-Key'}
    if key in KEYS:
        return accepted(KEYS[key])
    job_id = new_id()
    JOBS[job_id] = {'status': 'Pending', 'createdAt': now(),
                    'lastUpdatedAt': now()}
    KEYS[key] = job_id
    enqueue({'id': job_id, 'input': request.json,
             'correlationId': job_id})
    return accepted(job_id)

def accepted(job_id):
    return 202, {'Location': f'/jobs/{job_id}', 'Retry-After': '10'}
```

验证：用同一个 key 发送两次 POST。队列应当只多出一条消息，两次响应都指向同一个 `Location`。再发送一个不带该请求头的 POST：应返回 400，队列不变。

## 第 4 步：让客户端清楚知道任务进度的状态接口

`GET /jobs/{id}` 返回 Async Request-Reply 模式建议的字段：`status`（Pending、Running、Succeeded、Failed 或 Canceled）、`createdAt`、`lastUpdatedAt`、`percentComplete` 和 `error`。在演示中，这只需读取 `JOBS[job_id]`。

轮询并不是唯一的选择。Nordic APIs 和 Postman 都介绍过由服务器通过回调（例如 webhook）通知客户端的做法。比较合理的组合是：给客户的系统用 webhook，给需要手动查看的人用状态接口。

## 出错时，消息去哪儿？

Azure 把数据丢失列为异步架构面临的挑战之一。解决办法是把传输中的事件持久化存储，只有下一个组件 ack 之后才出队。第 1 步和第 2 步已经做到了这一点。剩下的问题是：任务真的失败了怎么办。

Azure 建议把失败的事件移入死信队列（DLQ），交由管理员检查。下面的精简版本替换第 2 步中的 handler，只用到前面已经出现过的 API。它用 `try` 包住 `run_model`。出错时，先记录 `Failed` 和 `error`，再把消息发布到持久化的 `ai_jobs_dlq` 队列，最后才 ack 原消息。

```python
ch.queue_declare(queue='ai_jobs_dlq', durable=True)

def handle(ch, method, props, body):
    job = json.loads(body)
    set_status(job['id'], 'Running')
    try:
        result = run_model(job)
        set_status(job['id'], 'Succeeded', result=result)
    except Exception as e:           # 简化写法：捕获所有类型的错误
        set_status(job['id'], 'Failed', error=str(e))
        ch.basic_publish(
            exchange='',
            routing_key='ai_jobs_dlq',
            body=body,
            properties=pika.BasicProperties(
                delivery_mode=pika.DeliveryMode.Persistent),
        )
    ch.basic_ack(delivery_tag=method.delivery_tag)
```

这是简化版本：任何错误，包括短暂的网络抖动，都会直接进入 DLQ。验证：让 `run_model` 对某个特定输入抛出错误，然后确认 `GET /jobs/{id}` 返回 `Failed`，`ai_jobs_dlq` 多了一条消息，`ai_jobs` 里已没有这个任务。

最后一块是关联 ID。Azure 建议给每个事件附上关联 ID，让每个消费者和日志系统都能把相关操作串成一条完整链路。演示中直接复用 `job_id`，在 API 和 worker 的每行日志里都打印出来。之后 grep 某个 ID，就能看到这个任务在系统中走过的完整路径。

## 四个最常见的错误

最常见的错误是消息一到就 ack，因为这样看起来更整洁。一旦 worker 中途挂掉，任务就会无声无息地丢失，因为 RabbitMQ 以为工作已经完成。

第二个错误是队列声明为 durable，却忘了把消息设为 persistent，或者反过来。要在重启后保留下来，两者缺一不可。

第三个错误是以为客户端不会重试，于是省掉 Idempotency-Key。对 AI 任务来说，每一次重复都意味着再付一次模型调用的钱，还可能产生与第一次相矛盾的第二个结果。

第四个错误是声明了 `percentComplete` 字段，worker 却从不更新。一个 10 分钟的任务在客户端看来九分钟都停在 0%，对方就会认定系统卡死了。如果任务能拆成多个步骤，比如每次处理文档的一页，就在每一步之后更新 `percentComplete` 和 `lastUpdatedAt`。

**要点:** 对于长时间运行的 AI 任务，在正确的时机 ack，比选对模型更重要。

## 在客户现场与简历上

如果客户抱怨“AI 老是卡住”，合理的做法是先搭好这套框架，再去调模型。先问清楚：最长的任务要跑多久，是谁在重试，以及凌晨 2 点 worker 重启时，正在运行的任务去了哪里。

阅读职位描述时，留意“异步处理”“消息队列”“幂等性”“可观测性”这类说法。它们提示你在面试中多问几句，而不是这份工作内容的确凿证据。简历上不要只写“用过 RabbitMQ”。

要写清楚：你设计了带 Idempotency-Key 的 202 API、手动 ack 加 prefetch 的 worker、DLQ 和关联 ID，并通过在任务中途杀掉 worker 做过测试。

模型还会换很多代。这里搭建的东西（持久化队列、在正确时机 ack、始终告诉客户端任务进行到哪一步的 API），在之后的每个项目里都依然适用。

**本周动手试试:**

- 按本指南的四个步骤搭建 ai_jobs 演示。然后在 worker 运行一个模拟 60 秒的任务时杀掉它，确认消息回到了队列。
- 用同一个 Idempotency-Key 发送两次相同的 POST，再发送一个不带 key 的 POST。队列应当只多出一条消息，不带 key 的请求应被拒绝。
- 为演示写一节 README，说明你如何处理消息丢失、重复重试和失败，然后把链接放到简历上。

## 信源

- [What is a Message Queue? (AWS)](https://aws.amazon.com/message-queue/)

- [RabbitMQ tutorial - Work Queues | RabbitMQ](https://www.rabbitmq.com/tutorials/tutorial-two-python)

- [Asynchronous Request-Reply Pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/async-request-reply)

- [Event-Driven Architecture Style - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/guide/architecture-styles/event-driven)

- [The Differences Between Synchronous and Asynchronous APIs](https://nordicapis.com/the-differences-between-synchronous-and-asynchronous-apis/)

- [Understanding asynchronous APIs](https://blog.postman.com/understanding-asynchronous-apis/)
