文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯云数据库 AI 服务>Memory 应用指南>开发者参考>Python>原子记忆>search_atomic — 语义检索原子记忆

search_atomic — 语义检索原子记忆

最近更新时间：2026-05-26 21:12:00

我的收藏

本页目录：

接口介绍

在原子记忆中做语义检索。传入检索文本，并按需附加预过滤条件，即可拿到按相关度排序的 Top-K 命中结果：
检索文本：通过 query 传入要匹配的内容（必填）。
返回数量：通过 limit 指定 Top-K 上限，不传时默认返回 5 条。
预过滤窗：通过 type 限定记忆类型，time_start / time_end 按 updated_at 限定时间窗，用于召回前缩小检索范围。
项
值
HTTP 方法与路径
POST /v2/atomic/search
HTTP 文档
函数签名
search_atomic(query, *, limit=None, type=None, time_start=None, time_end=None)
说明：
检索为 Top-K 召回语义，不提供offset/total，单次返回不超过limit条。每项额外回带score字段，按score 倒序排列；score 跨请求不保证可比。

使用示例

# 全局检索 Top-5
result = client.search_atomic(query="用户旅行偏好")

# 仅在 persona 类型中检索
result = client.search_atomic(
    query="用户旅行偏好",
    limit=10,
    type="persona",
)

for item in result["data"]["items"]:
    print(f"[{item['score']:.3f}] {item['content']}")
说明：
client 实例的构造方式参见 新建客户端；异步调用时将方法前加 await 即可。

请求参数

参数名
类型
必填
默认值
描述说明
query
str
是
-
检索文本 / 关键词。用户输入的查询语句，系统将基于此文本在记忆库中进行语义匹配。
limit
int
否
5
最大返回结果数（Top-K）。
说明：
若不传或传 None，服务端默认返回相关性最高的 5 条记忆记录。
type
str
否
-
原子记忆类型过滤器。传入后仅在指定类型的记忆中进行检索；不传则在所有记忆中全局检索。可选值包括：
"episodic"：事实类记忆（如用户说过的经历、发生过的事）。
"persona"：偏好类记忆（如用户的习惯、人设、喜好）。
"instruction"：指令类记忆（如用户对 AI 下达的长期行为规范）。
time_start
str
否
-
更新时间筛选起点（包含该时刻）。
筛选依据：基于记忆的最后更新时间（updated_at）。
格式要求：ISO 8601 格式，例如："2026-05-25T10:00:00Z"。
time_end
str
否
-
更新时间筛选终点（包含该时刻）。
格式要求：ISO 8601 格式。
与 time_start 配合组成闭区间时间窗，用于限定检索该时间段内更新过的记忆。

返回信息

返回字典包含按相关度排序的命中项列表与请求追踪 ID：
{
  "data": {
    "items": [
      {
        "id": "atom-aaaa",
        "type": "persona",
        "content": "用户偏好关西线路",
        "created_at": "2026-05-22T14:30:00+08:00",
        "updated_at": "2026-05-22T14:30:00+08:00",
        "score": 0.872
      }
    ]
  },
  "trace_id": "tr-xxxxxxxx-xxxxxxxx"
}
字段名
类型
说明
data.items
List[Dict]
命中的原子记忆列表。
排序规则：列表内的条目默认已**按相关性评分（score）由高到低（倒序）**排列。
数据结构：每条记忆包含以下完整字段：
id (str): 原子记忆的唯一主键 ID。
type (str): 记忆类型（例如 "persona" 代表用户画像/偏好标签）。
content (str): 命中的原子记忆具体文本内容。
created_at (str): 该条记忆的首次创建时间戳（ISO 8601 格式）。
updated_at (str): 该条记忆的最后修改时间戳（ISO 8601 格式）。
score (float): 语义相关性置信度评分。仅在当前检索请求内有效，跨请求（不同 Query 之间）不可直接对比。
trace_id
str
请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致，方便前后端协同定位向量召回质量或请求链路异常。

错误处理

错误码
触发场景
处理建议
400
query 为空、limit 越界、type 取值非法。
请校验入参后重试。
500
服务端错误。
记录 trace_id 后重试或上报。

中国站