Go 接 Responses API background mode：轮询异步任务、状态与数据保留边界

线上报告生成这类接口最容易踩的坑，就是把动辄要跑好几分钟的模型请求当成普通短查询来处理：Go 服务这边一直占着连接不放，网关先一步超时断开了，后台模型任务反倒还在继续跑。Responses API 的 background mode 刚好适配这类长任务，把整个流程拆成「提交一次、拿到响应 ID、后续查询状态」的逻辑，但它本身不是消息队列，也不会自动帮你完成业务侧的重试、权限校验和结果落库。

先把“长请求”改成两段式流程

假设后台有个「根据本周工单自动生成复盘报告」的功能。用户点击生成按钮后，前端不用一直等到模型把全文写完，只要提示“任务已受理”，后续每隔几秒查询一次本地业务任务表就行。

这里要把两个 ID 区分开：业务侧的 task_id 负责让用户定位找回自己的任务，OpenAI 返回的 response_id 负责后续查询模型任务进度。不要直接把后者直接传给浏览器当业务凭证，也不要默认它是永久有效的。

官方对 background mode 的定位就是处理耗时可能达到数分钟的复杂任务，调用方既可以轮询对象状态，也可以用流式事件同步任务进度。对绝大多数用 Go 写的后台管理系统来说，先从轮询方案入手更容易落地：接口逻辑简单，任务状态全链路可审计，就算中间网关超时也不会打断已经提交的模型任务。

Go 请求体只放必要的异步开关

下面用标准库 net/http 演示最小化提交代码。示例里特意把 API 密钥放在环境变量中，生产环境建议从密钥服务或者容器注入，不要直接硬编码写进配置文件。

type createResponseRequest struct {
    Model     string `json:"model"`
    Input     string `json:"input"`
    Background bool   `json:"background"`
    Store     bool   `json:"store"`
}

type responseObject struct {
    ID     string `json:"id"`
    Status string `json:"status"`
    Error  *struct {
        Message string `json:"message"`
    } `json:"error"`
}

func submitBackground(ctx context.Context, apiKey string) (responseObject, error) {
    body := createResponseRequest{
        Model: "o3",
        Input: "根据工单摘要生成一份内部复盘报告，保留事实和风险项。",
        Background: true,
        Store: true,
    }
    raw, err := json.Marshal(body)
    if err != nil {
        return responseObject{}, err
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        "https://api.openai.com/v1/responses", bytes.NewReader(raw))
    if err != nil {
        return responseObject{}, err
    }
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return responseObject{}, err
    }
    defer resp.Body.Close()
    if resp.StatusCode = 300 {
        return responseObject{}, fmt.Errorf("submit status: %s", resp.Status)
    }

    var out responseObject
    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
        return responseObject{}, err
    }
    if out.ID == "" {
        return responseObject{}, errors.New("missing response id")
    }
    return out, nil
}

这里的核心不是把请求体写得有多复杂，而是要第一时间存好返回的 id。提交接口返回成功只能代表异步任务对象创建成功，不能直接判定报告已经生成。如果提交返回 429、401 或者 5xx 这类错误，要结合响应头和业务幂等键做对应处理，不能用户多点一次按钮就无条件创建第二个重复任务。

轮询时先看状态，再读取输出

轮询接口全程用同一个 response ID 调用就行。建议给每个业务任务设置明确的超时截止时间，比如最多等8分钟；轮询间隔从2秒起步，逐步拉长到8秒，避免任务高峰期瞬间发起大量无意义的查询压到上游接口。

func waitForResponse(ctx context.Context, apiKey, responseID string) (responseObject, error) {
    delay := 2 * time.Second
    deadline := time.NewTimer(8 * time.Minute)
    defer deadline.Stop()

    for {
        current, err := getResponse(ctx, apiKey, responseID)
        if err != nil {
            return responseObject{}, err
        }
        switch current.Status {
        case "completed":
            return current, nil
        case "failed", "cancelled", "incomplete":
            if current.Error != nil {
                return responseObject{}, fmt.Errorf("response %s: %s", current.Status, current.Error.Message)
            }
            return responseObject{}, fmt.Errorf("response %s", current.Status)
        case "queued", "in_progress":
            // 继续等待；业务表中同步写入最近一次状态。
        default:
            return responseObject{}, fmt.Errorf("unknown response status: %s", current.Status)
        }

        timer := time.NewTimer(delay)
        select {
        case 

实际项目里的 getResponse 只需要做 GET 请求、鉴权和 JSON 解码逻辑，最好把服务端返回的 status 原样写入 ai_tasks.last_status。这样用户端展示的是“排队中”“处理中”还是“生成失败”都清晰明了，运维排查问题的时候也能直接看到任务卡在哪一步。

completed 之后还要核对结果和业务归属

状态变成 completed 之后，再去读取 output 字段的内容。读完输出不代表可以直接展示给用户，报告生成这类场景至少要做几层校验：response ID 是否归属于当前业务任务、输出内容是否为空、模型返回的拒答或者错误结构有没有被正常处理。

一套实用的落库字段参考如下：

task_id          varchar(64)   -- 业务任务号
response_id      varchar(128)  -- Responses API 返回的 ID
request_id       varchar(128)  -- 响应头中的请求追踪号
last_status      varchar(32)
result_text      mediumtext
fail_reason      varchar(255)
deadline_at      datetime
finished_at      datetime

消费最终结果的时候要用数据库条件更新逻辑，比如只允许 queued 或者 in_progress 状态的任务流转成 completed。这样定时补偿任务和用户手动刷新同时触发的时候，只有一个流程能把最终报告写入数据库，避免出现多份重复数据。

后台模式和数据保留不是一回事

background=true 解决的是连接时长和任务状态同步的问题，不直接等同于隐私合规策略。官方数据控制说明里提到，Responses API 的后台模式会把响应数据暂存一段时间支撑轮询，文档标注的时长大约是10分钟；这个临时存储和普通请求的存储设置、项目级的数据控制开关是互相独立的两套逻辑。

如果输入内容里包含客户工单、手机号或者内部故障细节，要先做内容最小化处理：删掉不需要的个人敏感字段，单独维护业务任务和模型响应的关联关系，确认组织是否已经开启 Zero Data Retention 策略，以及当前规则是否允许使用后台模式。不要仅凭 store=false 就给业务方承诺“完全不会留存任何内容”。

常见问题：超时、重复任务和状态误判

提交接口超时，任务到底有没有创建？

网络超时不能直接断定服务端没有收到请求。要给业务任务绑定独立的幂等键，记录本地提交时间，后续链路可查询时再根据 response ID 或者业务侧状态做补偿核对。没有做幂等设计的情况下，自动重试很容易生成两份完全重复的报告。

轮询拿到 200，为什么页面还是不能展示？

HTTP 200 只代表查询接口本身正常返回，真正决定任务结果的是返回 JSON 里的 status 字段。queued 和 in_progress 都属于还在等待的状态，failed 和 cancelled 要展示可重试或者引导人工处理的提示，只有 completed 状态下才能进入 output 解析流程。

超过截止时间要不要一直查？

不需要。到达预设的业务截止时间后，直接把任务标记为“待补偿”，停止前端侧的轮询；后台的补偿调度器可以用更长的间隔再试查一次。要是报告已经生成，补偿器负责把结果落库；如果多次查询还是失败，就保留错误原因和 request ID 留作后续排查。

小结：把模型调用当作可观测任务

Go 接入 Responses API background mode 的核心逻辑只有三步：提交请求时拿到 response ID，按状态机规则做轮询，任务完成后核对 output 结果再落库。真正决定线上系统稳定性的，是业务任务号、幂等键、截止时间、状态机逻辑和数据保留规则这些细节。把这些边界补全之后，模型长任务就不会再绑架用户的请求连接，也不会因为一次200响应就被误判为已经执行完成。