OpenAI API 怎样为请求设置幂等键

调用 OpenAI API 时，客户端可能在请求已经到达服务端后才因为超时断开连接。此时直接重新生成一个键并重发，业务层就无法判断这是原提交的重试，还是一次全新的提交。幂等键的做法是：为一次业务提交生成一个稳定的 Idempotency-Key，在网络不确定时复用它重试。

官方地址：https://developers.openai.com/api/reference/overview

幂等键只应绑定“一次业务提交”。同一次提交重试时复用相同的键、会话 ID 和请求体；用户再次发起新提交时必须生成新键。具体端点是否支持该语义，要以对应 API 文档为准。

• 提交去重：Idempotency-Key 让服务端有机会识别同一提交的重复发送。
• 请求追踪：X-Client-Request-Id 用于关联客户端日志，服务端还会返回 x-request-id。
• 重试边界：同键重试必须保持业务语义不变；改了消息、会话或业务对象，就应当视为新提交。

幂等键到底解决哪一种重复请求

先看最容易被忽略的场景：客户端发出请求后等待响应，连接在响应返回前超时。客户端不知道服务端是否已经接收并处理了这次提交。如果重试时使用完全新的键，服务端可能把两次请求都当成两个提交；如果无论什么请求都复用一个固定键，又会把不同业务请求错误地绑定在一起。

正确的边界是“业务提交级别”：一条待发送消息、一个待创建的会话事件或一次明确的写入动作生成一个键，并把键和请求体摘要、session_id、本地业务单号一起保存。重试只复用这一组上下文，不重新生成随机键。

用请求头或 SDK 参数传入幂等键

官方 Agents API 的 Sessions Events 文档给出了直接的请求头写法。下面的 curl 只展示请求结构，变量值由调用方在自己的服务端生成；不要把 API key 放进浏览器或提交到代码仓库。

# 同一业务提交只生成一次键，超时重试时继续使用它
submission_key="your-stable-submission-key"

# session_id、消息体和幂等键共同标识这一次提交
curl "https://api.openai.com/v1/agents/sessions/$session_id/events" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Idempotency-Key: $submission_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "agent.session.input.message",
      "input": [{
        "role": "user",
        "content": [{"type": "input_text", "text": "请整理今天的待办事项"}]
      }]
    }]
  }'

如果使用官方 Python SDK，文档示例对应的参数名是 idempotency_key。关键不是把字符串写在哪里，而是让生成键、保存键和发送请求属于同一个业务生命周期。

from uuid import uuid4
from openai import OpenAI

client = OpenAI()

# 一次新的业务提交生成一次键，并先保存到本地任务记录
submission_key = str(uuid4())
session_id = "sess_业务会话标识"
message = "请整理今天的待办事项"

# 将同一个键传给本次提交；发生网络不确定时复用它
response = client.beta.agents.sessions.events.create(
    session_id,
    idempotency_key=submission_key,
    events=[{
        "type": "agent.session.input.message",
        "input": [{
            "role": "user",
            "content": [{"type": "input_text", "text": message}],
        }],
    }],
)

# 保存本地提交键与响应标识，方便后续重试和排障关联
print({"submission_key": submission_key, "response": response})

这段代码的重点是 submission_key 在请求前就已经确定，并且可以落到任务表或消息表中。不要把每次调用函数都生成新 UUID，否则连接超时后的第二次调用就失去了幂等关系。

重试时哪些值必须保持不变

重试不是“再调用一次同样的函数”这么简单。对一次尚未确定结果的提交，至少要保持三个上下文一致：session_id、事件消息体和 Idempotency-Key。如果只复用键却换了消息体，调用方会得到一个语义冲突的请求；如果只复用消息体却换了键，服务端又可能把它当成新提交。

def send_with_same_submission(client, session_id, events, submission_key):
    # 重试路径只接收已经持久化的三件套，不在函数内部重新生成键
    return client.beta.agents.sessions.events.create(
        session_id,
        idempotency_key=submission_key,
        events=events,
    )


# 第一次发送前生成并保存 submission_key
events = [{
    "type": "agent.session.input.message",
    "input": [{
        "role": "user",
        "content": [{"type": "input_text", "text": "生成月度摘要"}],
    }],
}]
submission_key = "同一业务提交的持久化键"

# 网络超时后的恢复动作仍使用原 session、原 events 和原 key
response = send_with_same_submission(
    client, session_id, events, submission_key
)

实际项目还应给重试次数、总等待时间和可重试错误设上限。鉴权失败、参数错误或业务内容已经改变时，不要机械重试；对无法确定是否已接收的网络错误，才进入“复用原提交上下文”的恢复路径。

别把幂等键和请求追踪 ID 混在一起

OpenAI API Reference 还介绍了两类请求标识：客户端可以通过 X-Client-Request-Id 传入自己的关联 ID，服务端会返回 x-request-id。它们解决的是日志排障和请求关联，不等同于提交去重键。

因此本地记录最好至少保存业务提交 ID、Idempotency-Key、session_id、请求体版本和每次响应中的 x-request-id。这样既能判断“是不是同一次提交”，也能在服务端支持时根据响应标识排查“这一请求走到哪里”。

端点支持范围与上线注意事项

不要把 Idempotency-Key 当成所有 OpenAI API 端点都会自动处理的通用业务字段。文章示例依据官方 Agents Sessions Events 文档；接入其他端点时，应先查看该端点的请求头、SDK 参数和错误说明。如果文档没有承诺幂等语义，就不能仅凭加了一个请求头而宣称已经实现服务端去重。

上线前可以把下面四条写进发送模块的接口约定：

1. 一次新的业务提交只生成一个键，并在真正发请求前保存。
2. 网络超时或响应丢失时，复用原键、原会话和原消息体。
3. 用户再次点击“重新生成”或修改了内容时，创建新提交并生成新键。
4. 日志中同时记录本地提交 ID、幂等键和响应请求 ID，但避免记录 API key 与敏感正文。

常见问题

幂等键可以用固定字符串吗？

不建议。固定字符串会把不同业务提交错误地压到同一键下。应使用足够唯一、可持久化的提交键，并让它的生命周期覆盖可能发生的重试窗口。

重试时只保留 Idempotency-Key 可以吗？

不够。至少要保留官方文档要求的会话和消息上下文；在本地还应记录业务提交 ID 与请求体版本，避免同键重试时悄悄换了业务内容。

X-Client-Request-Id 能替代幂等键吗？

不能直接替代。前者面向客户端日志关联，后者面向一次提交的幂等语义；两者可以同时记录，但职责不同。

总结一下：幂等键的核心不是“给每个 HTTP 请求加一个随机字符串”，而是把一次业务提交的请求体、会话和重试策略绑定起来。先确认端点支持，再保存原键并在不确定结果时复用，才能真正降低重复提交风险。