腾讯云数据库 AI 服务 query_conversation — 查询原始对话消息

一、接口介绍

·分页控制：通过 limit 指定单页条数、offset 指定起始偏移；不传时按服务端默认值 limit=20、offset=0 返回第一页。

·筛选条件：通过 session_id 限定会话，time_start / time_end 限定时间窗（含端点）。三者均可选，全部缺省时等价于不加筛选，仅按分页返回。

项	值
HTTP 方法与路径	POST /v2/conversation/query
HTTP 文档	查询原始对话消息
函数签名	query_conversation(*, session_id=None, limit=None, offset=None, time_start=None, time_end=None)说明：当你将可选参数设置为 None（空）时，SDK 在发送请求前会自动过滤掉这些参数，不会将它们发送给服务器。

二、使用示例

# 查询某会话的最近 20 条消息result = client.query_conversation(session_id="sess-trip-202604")for msg in result["data"]["messages"]: print(f"[{msg['role']}] {msg['content']}")# 翻页：第 21~40 条result = client.query_conversation( session_id="sess-trip-202604", limit=20, offset=20,)# 按时间窗筛选result = client.query_conversation( time_start="2026-05-01T00:00:00+08:00", time_end="2026-05-31T23:59:59+08:00",)

注意：说明：

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

三、请求参数

参数名	类型	必填	默认值	描述说明
session_id	str	否	–	会话 ID。传入后仅返回该特定会话下的历史消息；若不传或传 None，则默认查询所有会话。
limit	int	否	20	单页返回的条数。限制：最大支持 100 条。注意：若传 None，服务端将自动采用默认值 20。
offset	int	否	0	分页起始偏移量。表示跳过前多少条数据（常用于传统分页）。
time_start	str	否	–	时间筛选起点（包含该时刻）。格式要求：需符合 ISO 8601 标准。例如："2026-05-25T10:00:00Z" 或 "2026-05-25T18:00:00+08:00"。
time_end	str	否	–	时间筛选终点（包含该时刻）。与 time_start 配合组成闭区间时间窗。格式要求：需符合 ISO 8601 标准。

四、返回信息

返回字典包含命中的消息列表、命中总数与请求追踪 ID：

{ "data": { "messages": [ { "id": "msg-aaaa", "role": "user", "content": "我打算 5 月去日本…", "timestamp": "2026-05-22T14:30:00+08:00" } ], "total": 1 }, "trace_id": "tr-xxxxxxxx-xxxxxxxx"}

字段名	类型	说明
data.messages	List[Dict]	历史消息列表。排序规则：列表内的消息默认按时间先后顺序排列。数据结构：每条消息包含以下完整字段：id (str): 消息的唯一主键 ID。role (str): 发送者角色，可选值为 "user"、"assistant" 或 "system"。content (str): 消息的具体文本内容。timestamp (str): 消息产生的时间戳（ISO 8601 格式）。
data.total	int	满足筛选条件的消息总条数。注意：该值为全量数据总数，完全不受当前请求中 limit（单页条数）和 offset（偏移量）的分页限制。应用场景：前端可直接利用该数值来计算并渲染传统的分页组件（如：总页数 = total / limit）。
trace_id	str	请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致，方便前后端协同定位请求问题。

五、错误处理

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