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

search_conversation — 语义检索原始对话消息

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

我的收藏

本页目录：

接口介绍

在原始对话消息中做语义检索。传入检索文本，并按需附加预过滤条件，即可拿到按相关度排序的 Top-K 命中结果：
检索文本：通过 query 传入要匹配的内容（必填）。
返回数量：通过 limit 指定 Top-K 上限，不传时默认返回 5 条。
预过滤窗：通过 session_id 限定会话，time_start / time_end 限定时间窗（含端点），用于召回前缩小检索范围。
项
值
HTTP 方法与路径
POST /v2/conversation/search
HTTP 文档
函数签名
search_conversation(query, *, limit=None, session_id=None, time_start=None, time_end=None)
说明：
本函数采用语义搜索（向量检索）机制进行相关性召回。其核心运行行为如下：
分页与数量限制：本接口为全量 Top-K 检索，不提供传统的分页功能（无 offset 与 total 字段）。单次返回的结果总数不会超过指定的 limit 值。
相关性评分（Score）：返回的每个结果项中均会包含一个 score（置信度评分）字段，且所有结果已默认按 score 从高到低（相关性由强到弱）进行倒序排列。
评分有效范围（重要）：score 仅代表本次请求内部各结果之间的相对相关度。由于不同请求的检索上下文不同，跨请求、跨 Query 的 score 绝对值不可放在一起直接对比。

使用示例

# 全局检索 Top-5
result = client.search_conversation(query="日本旅游")

# 在指定会话内检索 Top-10
result = client.search_conversation(
    query="关西线路",
    limit=10,
    session_id="sess-trip-202604",
)

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

请求参数

参数名
类型
必填
默认值
描述说明
query
str
是
-
检索文本 / 关键词。用户输入的查询语句，系统将基于此文本进行语义匹配或关键词检索。
长度限制：[1, 2048]，即上限 2 KB。
limit
int
否
5
最大返回结果数（Top-K）。取值范围：[1, 100]。
说明：
若不传或传 None，服务端默认返回相关性最高的 5 条记录。
session_id
str
否
-
会话限定过滤器。传入特定会话 ID 后，检索范围将仅局限于该会话内的关联内容；不传则在全量数据中检索。
time_start
str
否
-
时间窗起点（包含该时刻）。
格式要求：ISO 8601 格式，例如："2026-05-25T10:00:00Z"。
作用：用于过滤该时间点之后产生的数据。
time_end
str
否
-
时间窗终点（包含该时刻）。
格式要求：ISO 8601 格式。
与 time_start 配合可锁定一个历史时间段进行精确检索。

返回信息

返回字典包含按相关度排序的命中项列表与请求追踪 ID：
{
  "data": {
    "messages": [
      {
        "id": "msg-aaaa",
        "role": "user",
        "content": "我打算 5 月去日本...",
        "timestamp": "2026-05-22T14:30:00+08:00",
        "score": 0.872
      }
    ]
  },
  "trace_id": "tr-xxxxxxxx-xxxxxxxx"
}
字段名
类型
说明
data.messages
List[Dict]
命中的消息列表。
排序规则：列表内的消息默认按相关性评分（score）由高到低（倒序）排列。
数据结构：每条消息包含以下完整字段：
id (str): 消息的唯一主键 ID。
role (str): 发送者角色，可选值为 "user"、"assistant" 或 "system"。
content (str): 命中的消息具体文本内容。
timestamp (str): 消息产生的 ISO 8601 格式时间戳。
score (float): 语义相关性置信度评分。仅在当前检索请求内有效，跨请求不可直接对比。
trace_id
str
请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致。

错误处理

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

中国站