OpenAI Responses API background 模式怎么轮询：queued、completed 与超时回收

长文档分析、代码审查和批量资料整理不一定适合让 HTTP 请求一直挂着。Responses API 的 background 模式可以先提交任务，再根据响应状态取回结果；真正容易出错的地方是把 queued 当成失败，或者轮询超时后又无条件创建第二个任务。

先把一次后台请求拆成四个动作

一个可靠的后台任务通常只有四步：创建、记录、轮询、收口。创建接口返回的响应标识要立刻写入任务表；后续查询都围绕这个标识展开，不要因为前端刷新或服务重启而重新创建同一份分析任务。

官方 API Reference 中，创建和读取响应是两个独立动作。数据控制说明还提到，后台模式为了支持查询会保留响应数据一段时间，因此需要把业务侧结果及时保存到自己的受控存储。

创建时只提交能重放的任务描述

提交后台任务前，先把业务输入整理成一个可追踪的任务对象。不要把只存在于浏览器内存里的上下文当作唯一输入，否则几分钟后拿到结果时，很难解释它到底分析了什么。

job = {
    "business_id": "review-20260823-1024",
    "prompt_version": "review-v3",
    "input_ref": "s3://safe-bucket/reviews/1024.txt",
    "state": "creating"
}

请求成功后，把返回的 response id 写回这条业务记录。关键不是把所有原文复制到日志里，而是保留输入引用、提示版本和模型配置，让任务能够复查和重试。

用显式状态机处理 queued 和 in_progress

后台任务刚创建时可能还在排队，随后进入处理中。轮询器应该把这两种状态都视为“继续等待”，而不是调用失败。

WAITING = {"queued", "in_progress"}

def next_action(status):
    if status in WAITING:
        return "poll_later"
    if status == "completed":
        return "save_result"
    if status in {"failed", "cancelled"}:
        return "record_terminal_error"
    return "inspect_unknown_status"

未知状态不要静默当成完成。先记录原始状态和响应标识，再让告警或人工检查决定下一步；过于激进的默认分支会把新状态误写成成功。

轮询间隔要和总时限一起设计

固定每 100 毫秒查询一次，看起来响应快，实际会制造很多无意义请求。更稳的做法是前几次短等待，随后逐步拉长间隔，并设置一个业务总时限。

def poll_plan(attempt):
    intervals = (2, 4, 8, 15, 30)
    return intervals[min(attempt, len(intervals) - 1)]

轮询超时有三种可能：任务仍在处理、读取接口暂时不可用、任务已经完成但本地没有及时读到。超时记录应保留最后一次状态和 response id，交给下一轮恢复；不要因为本地计时器到点，就直接创建一个新任务。

完成状态和结果保存必须有两个检查点

拿到 completed 后，先读取输出内容并做最小完整性检查，再写业务状态。检查内容至少包括输出非空、关联的 response id 一致，以及任务输入引用没有被替换。

def accept_response(response, job):
    if response["id"] != job["response_id"]:
        raise ValueError("response id mismatch")
    if response["status"] != "completed":
        raise ValueError("response is not completed")
    text = response.get("output_text", "")
    if not text.strip():
        raise ValueError("empty output")
    save_output(job["business_id"], text)
    mark_done(job["business_id"])

如果结果保存失败，业务状态应停留在“待收口”而不是“已完成”。下一次恢复任务时仍按 response id 读取，不会让空结果占住成功位置。

取消和失败不要共用一个重试按钮

用户主动取消，通常不应自动重试；服务端失败则要结合错误类型判断是否可重试；读取暂时失败，只需要继续查询原 response。把三种情况都绑定到“再次创建”，最容易产生重复计费和重复结果。

• cancelled：保存取消来源和操作人，停止后续轮询。
• failed：保存错误类型，只有明确可恢复时才安排重试。
• 读取超时：不改变原任务状态，延迟后继续读取。
• 未知状态：暂停自动收口，保留原始响应等待人工确认。

用固定样本验收重复、超时和重启场景

本地测试不要只覆盖一次成功返回。至少准备四组样本：短任务快速完成、长任务经历 queued、读取接口暂时失败、服务在保存 response id 后重启。每组都检查最终任务数、重复结果数和人工介入数。

• 同一个业务任务只能关联一个活动 response id。
• 轮询器重启后可以从任务表恢复，不需要重新创建请求。
• 超时样本最终仍能通过原 response id 收口。
• 失败和取消都能保留原因，且不会被误记为成功。

指标可以分成三组：平均等待时间和长尾等待时间，状态查询次数和接口错误率，重复创建数和空结果数。只看平均延迟会漏掉少量长期排队任务，只有把长尾和重复任务一起看，才能判断轮询策略是否合适。

常见问题

queued 状态是不是表示请求失败？

不是。它表示任务还在等待处理，轮询器应保留 response id 并按间隔继续读取，只有最终失败状态才进入失败处理。

轮询超时后要不要重新创建任务？

不要直接重建。先用原 response id 再读一次并检查业务任务记录；只有确认原任务已经终止且业务允许重试时，才创建新任务。

为什么完成状态已经写入，结果表却是空的？

通常是状态更新和结果保存没有形成清晰的先后关系。先核对 response id 和输出非空，再保存正文，最后更新业务完成状态。

后台模式适合所有请求吗？

不适合强交互、用户正在等待即时反馈的短请求。它更适合耗时较长、可以异步通知、并且有可靠任务表的工作流。

上线前的收口清单

检查创建记录是否先于轮询；response id 是否贯穿日志、任务表和结果表；queued 与 in_progress 是否都能继续等待；超时是否不会重复创建；完成结果是否先保存再改状态；取消、失败和未知状态是否各自有处理路径。把这几项放进发布前验收，后台任务才不会从“请求挂住”变成“重复跑了两遍”。