腾讯云数据库 AI 服务 update_atomic — 按 id 更新原子记忆

一、接口介绍

·目标定位：通过 id 指定目标原子记忆主键（必填）。

·正文更新：通过 content 传入更新后的原子记忆正文全量值（必填，整体覆盖旧内容）。

·背景更新：通过 background 传入更新后的上下文背景信息（可选）。None（即不传）表示本次不更新背景；显式传入空串 "" 则代表清空背景。

项	值
HTTP 方法与路径	POST /v2/atomic/update
HTTP 文档	按 id 更新原子记忆
函数签名	update_atomic(id, content, *, background=None)

注意：说明：

注意：原子记忆不提供手动写入接口——原子记忆由系统自动沉淀产生，本接口仅用于在已沉淀原子记忆上做内容订正，不支持"按 id 不存在则创建"的 upsert 语义。若 id 不属于当前调用上下文，统一返回业务错误码 404。

二、使用示例

# 仅更新正文result = client.update_atomic( id="atom-aaaa", content="用户偏好关西线路（已更新）",)# 同时更新正文和背景result = client.update_atomic( id="atom-aaaa", content="用户偏好关西线路（已更新）", background="2026 年 5 月对话补充",)# 清空背景result = client.update_atomic( id="atom-aaaa", content="用户偏好关西线路（已更新）", background="",)

注意：说明：

注意：client 实例的构造方式参见新建客户端；异步调用时将方法前加 await 即可。

三、请求参数

参数名	类型	必填	描述说明
id	str	是	目标原子记忆 ID。需要修改的记忆片段的唯一主键标识。
content	str	是	新的记忆正文（全量覆盖）。传入更新后的完整文本。注意：该操作为全量更新，会直接覆盖原有的记忆内容。
background	str	否	新的上下文背景信息。用于调整该记忆产生的背景或补充说明。为了防止误操作，其传值规则如下：不更新：传 None（或不传该字段），系统将保留原背景不变。清空：显式传入空字符串 ""，系统将彻底清除原背景。

四、返回信息

返回字典包含被更新主键、最新时间戳与请求追踪 ID：

{ "id": "atom-aaaa", "updated_at": "2026-05-22T14:30:00+08:00", "trace_id": "tr-xxxxxxxx-xxxxxxxx"}

字段名	类型	说明
id	str	新创建或被操作的原子记忆主键 ID。系统生成的唯一标识符（格式如 "atom-xxxx"），后续对该条记忆的更新、删除或查询操作都需要传入此 ID。
updated_at	str	最后修改时间戳。采用 ISO 8601 标准格式（例如 "2026-05-22T14:30:00+08:00"）。代表该条原子记忆在服务端写入成功并正式生效的最新时间。
trace_id	str	请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致，常用于审计高频写操作或排查数据入库异常。

五、错误处理

错误码	触发场景	处理建议
400	id 或 content 为空。	请校验入参后重试。
404	id 不存在或不属于当前调用上下文。	请校验目标合法性。
500	服务端错误。	记录 trace_id 后重试或上报。