腾讯混元API不保证幂等性，需由业务方实现：客户端用x-idempotency-key标识请求，后端校验该键并拦截重复执行；数据库加唯一约束或Redis预占位校验状态；禁用SDK默认重试，手动控制重试逻辑。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在调用腾讯混元智能体执行关键业务操作（如下单、支付、提交表单）时，网络抖动或客户端异常可能导致请求重试，若后端未做幂等控制，同一笔数据会被多次写入数据库或触发重复动作。
确认API是否原生支持幂等性
混元OpenAI兼容接口本身【不自动保证幂等】，它只负责模型推理与响应生成，不介入业务层的数据提交逻辑。这意味着：你调用/v1/chat/completions发起一次请求，模型返回“已为您提交订单”，但这个“提交”动作实际由你的下游服务完成——混元并不执行该动作，也不感知其是否成功。
因此，幂等性必须由你自己的服务代码实现，不能依赖混元API本身。
在客户端侧添加唯一请求标识（x-idempotency-key）
第一步：每次发起智能体调用前，生成一个全局唯一、稳定且可追溯的字符串作为幂等键，例如使用UUID v4或基于时间戳+随机数+业务ID组合生成；
第二步：将该字符串通过HTTP Header传入，字段名为x-idempotency-key；
第三步：确保你调用的后端服务（非混元，而是你自己的API网关或业务接口）能识别并校验该Header——收到重复key时直接返回上次成功响应，不再执行业务逻辑。
注意：该Header需在所有重试请求中保持完全一致，否则无法生效；若使用SDK自动重试，请关闭其默认重试机制，改由你手动控制重试并复用原始key。
在业务逻辑层实现幂等写入
方法一：数据库唯一约束 + 忽略冲突
在订单表、日志表等关键表中，为业务单号（如order_no）、用户ID+时间窗口组合等字段添加唯一索引；插入前不查是否存在，直接INSERT → ON CONFLICT DO NOTHING（PostgreSQL）或 INSERT IGNORE（MySQL）；成功则写入，冲突则跳过。
方法二：Redis预占位 + 状态机校验
在执行核心操作前，先用SET key value EX 300 NX尝试设置一个带5分钟过期的Redis Key（key可为idempotent:{x-idempotency-key}）；若设置成功，继续执行业务；若失败（说明已存在），立即返回缓存中的结果或查询DB中对应记录状态。
这一步必须在智能体返回“准备提交”之后、真正调用支付/下单接口之前完成，否则无法拦截混元下游的重复动作。
禁用混元SDK的默认重试策略
如果你使用的是腾讯云官方Python SDK或OpenAI兼容SDK，默认可能开启3次HTTP重试；这会破坏你手动维护的幂等键一致性。
请显式关闭自动重试：在初始化OpenAI()客户端时，传入max_retries=0参数；
然后由你自己的代码捕获requests.exceptions.Timeout或httpx.ReadTimeout等异常，在捕获后判断是否允许重试——仅当未收到HTTP响应（即不确定是否已提交）时才重发，且严格复用原始x-idempotency-key。
