腾讯云数据库 AI 服务 search_conversation — 语义检索原始对话消息

一、接口介绍

·检索文本：通过 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-5result = client.search_conversation(query="日本旅游")# 在指定会话内检索 Top-10result = 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 后重试或上报。