18 KiB
Thread 创建慢与回答结束后 History 等待:优化方案
日期:2026-10-22 配套文档:完整排查手册
1. 优化目标与结论
目标:
- 降低
POST /api/threads的checkpoint_create延迟; - 降低 SSE 结束后
/history的延迟; - 避免慢 history 长时间占用全局 saver 锁并阻塞其他 thread;
- 处理 RunManager 内存 registry 持续增长;
- 保留对话 checkpoint 和历史记录,不通过直接删数据解决问题。
建议分四层实施:
| 优先级 | 动作 | 是否重启 | 风险 |
|---|---|---|---|
| P0 | 基于 EXPLAIN 在线补建 history 组合索引 | 否 | 低;增加少量写放大和磁盘占用 |
| P1 | History 明确主 namespace,缩短 alist 持锁范围并补计时 | 是 | 中;需要 history/subgraph 回归 |
| P1 | 修复 RunManager.cleanup() 未调用 |
是 | 低到中;需要重连/终态回归 |
| P2 | 让 PG saver 真正支持并发读写,或拆出独立 history reader | 是 | 中到高;需要并发与一致性测试 |
| P3 | 根据 dead tuples、I/O 和保留策略做维护/归档 | 视操作而定 | 中到高 |
最快的低风险止血方案是:先确认跨 namespace History 执行计划确实有 Sort,然后在线创建 (thread_id, checkpoint_id DESC) 索引。该索引只能缩短 SQL 和持锁时间,不能消除 saver 实例级串行。
2. P0:在线补建 History 组合索引
2.1 适用条件
同时满足以下条件时执行:
- 线上
/history当前需要跨checkpoint_ns返回最新 checkpoint;或者短期内不能发布代码来限定 namespace。 - 慢 thread 的执行计划出现 per-thread Sort、扫描候选行较多或执行时间明显高于限定
checkpoint_ns=''的版本。 - 已确认目标表 schema;以下示例假设是
public。
如果每个 thread 只有极少 checkpoint,EXPLAIN 已是亚毫秒级且无明显扫描/Sort,建索引不会解决应用层 saver lock 排队,应直接转向 P1/P2。
2.2 建索引前检查
SELECT current_database(), current_schema(), current_schemas(true);
SELECT
schemaname,
tablename,
indexname,
indexdef
FROM pg_indexes
WHERE tablename = 'checkpoints'
ORDER BY indexname;
确认没有等价的 (thread_id, checkpoint_id) 索引。已有单列 checkpoints_thread_id_idx(thread_id) 不等价:它可以过滤 thread,但不能直接提供跨 namespace 的 checkpoint_id 顺序。
保存变更前基线:
EXPLAIN (ANALYZE, BUFFERS, SETTINGS)
SELECT checkpoint_id, checkpoint_ns
FROM public.checkpoints
WHERE thread_id = '<THREAD_ID>'
ORDER BY checkpoint_id DESC
LIMIT 1;
2.3 在线创建
CREATE INDEX CONCURRENTLY 必须作为独立语句执行,不能放在显式事务块中。确认数据库客户端没有自动把整段脚本包在一个事务里。
SET lock_timeout = '5s';
SET statement_timeout = '0';
CREATE INDEX CONCURRENTLY IF NOT EXISTS
checkpoints_thread_checkpoint_id_desc_idx
ON public.checkpoints (thread_id, checkpoint_id DESC);
RESET lock_timeout;
RESET statement_timeout;
然后更新统计:
ANALYZE public.checkpoints;
不要把 checkpoint 或 metadata JSONB 加进 INCLUDE;它们较大,会显著扩大索引且不能解决此排序问题。
2.4 验证索引有效
SELECT
i.relname AS index_name,
x.indisvalid,
x.indisready,
pg_size_pretty(pg_relation_size(i.oid)) AS index_size,
pg_get_indexdef(i.oid) AS indexdef
FROM pg_class t
JOIN pg_index x ON x.indrelid = t.oid
JOIN pg_class i ON i.oid = x.indexrelid
JOIN pg_namespace n ON n.oid = t.relnamespace
WHERE n.nspname = 'public'
AND t.relname = 'checkpoints'
AND i.relname = 'checkpoints_thread_checkpoint_id_desc_idx';
必须看到:
indisvalid = true
indisready = true
重跑执行计划:
EXPLAIN (ANALYZE, BUFFERS, SETTINGS)
SELECT checkpoint_id, checkpoint_ns
FROM public.checkpoints
WHERE thread_id = '<THREAD_ID>'
ORDER BY checkpoint_id DESC
LIMIT 1;
预期:
- 使用
checkpoints_thread_checkpoint_id_desc_idx; - 不再出现额外 Sort;
- 扫描行数接近 1;
- buffer read 和实际执行时间明显下降。
2.5 上线观察
至少对比变更前后:
/historyp50/p95/p99;POST /threads的checkpoint_createp50/p95/p99;- checkpoint INSERT/UPSERT 的平均与最大耗时;
- 新索引大小;
pg_stat_user_indexes.idx_scan;- checkpoint 写入吞吐与 WAL/磁盘增长。
索引使用统计:
SELECT
schemaname,
relname,
indexrelname,
idx_scan,
idx_tup_read,
idx_tup_fetch
FROM pg_stat_user_indexes
WHERE relname = 'checkpoints'
ORDER BY indexrelname;
2.6 回滚
如果索引导致不可接受的写放大、磁盘占用,或代码发布后已经不再需要跨 namespace 查询,可在线删除:
DROP INDEX CONCURRENTLY IF EXISTS
public.checkpoints_thread_checkpoint_id_desc_idx;
同样不要放在显式事务块内。
如果在线创建被中断,先查询 indisvalid/indisready。若留下 invalid 索引,低峰执行上面的 DROP INDEX CONCURRENTLY 后再重新创建,不要假设 IF NOT EXISTS 会修复 invalid 索引。
3. P1:让普通 History 明确查询主 namespace
3.1 为什么这是长期更优方案
普通聊天主图状态使用:
checkpoint_ns = ''
checkpoints 现有主键:
(thread_id, checkpoint_ns, checkpoint_id)
如果 History 的业务语义就是“普通聊天主图历史”,限定 checkpoint_ns='' 后,PostgreSQL 可以直接利用现有主键倒序取最新 checkpoint:
WHERE thread_id = $1
AND checkpoint_ns = ''
ORDER BY checkpoint_id DESC
LIMIT 1
这样不需要为同一访问模式长期维护额外索引,也避免误把 subgraph namespace 中较新的 checkpoint 当作主聊天最新状态。
3.2 建议代码改动
当前:
config: dict[str, Any] = {"configurable": {"thread_id": thread_id}}
建议:
config: dict[str, Any] = {
"configurable": {
"thread_id": thread_id,
"checkpoint_ns": "",
}
}
位置:
offline-backend-20260512/backend/app/gateway/routers/threads.py:1886
3.3 发布前必须验证
- 普通 lead agent 首轮和多轮历史恢复;
- 自定义 agent 历史恢复;
- subagent/subgraph 事件不应错误覆盖主图历史;
- interrupt/HITL 恢复;
- checkpoint
before分页; - 页面刷新、重新打开会话、断流重连;
fetchStateHistory: { limit: 1 }返回的 messages、title、thread_data 正确。
如果某些 API 消费者明确要求跨 namespace 历史,不要直接全局改变语义。可以为普通聊天与诊断/调试接口拆分不同路径。
3.4 与 P0 索引的关系
- 紧急止血可以先建 P0 索引,再发布 namespace 修复。
- namespace 修复稳定运行一段时间后,通过
pg_stat_user_indexes确认 P0 索引已不再需要,再在线删除。 - 不要在代码上线同一时刻立刻删索引,保留可快速回退窗口。
4. P1:缩短 /history 持有 saver lock 的时间
4.1 当前问题
当前 route 在下面的 async for 内处理并序列化每个 checkpoint:
async for checkpoint_tuple in checkpointer.alist(config, limit=body.limit):
# 读取 checkpoint
# 序列化 messages
# 构造 HistoryEntry
PostgreSQL saver 的 alist() 在 _cursor() context 内 fetchall 后逐条 yield。调用方在处理 yielded tuple 时,generator 尚未退出,因此 saver lock 可能覆盖业务层消息序列化时间。
4.2 低风险 quick win
先完整、快速消费 bounded 结果,让 generator 退出并释放 saver cursor/lock,再在锁外做响应序列化:
checkpoint_tuples = [
item
async for item in checkpointer.alist(config, limit=body.limit)
]
for checkpoint_tuple in checkpoint_tuples:
# 原来的 HistoryEntry/messages 序列化逻辑
当前普通前端请求 limit=1,额外内存可以忽略。接口模型允许更大 limit 时,仍需保留现有上限并测试大 checkpoint payload。
该改动不会解除 saver 内部对 SQL/反序列化的串行,但能避免 route 的 Python 序列化继续占着 saver lock。
4.3 同时增加 History 分段计时
建议记录无内容的阶段指标:
history_checkpoint_fetch_ms
history_serialize_ms
history_total_ms
thread_id(清洗后)
limit
checkpointer 类型
这样可以区分:
- saver lock + SQL + checkpoint load;
- Gateway 消息序列化;
- route 外的鉴权/代理等待。
不要在日志中记录消息正文、checkpoint JSON、数据库 URL 或 token。
5. P1:修复 RunManager 内存 registry 增长
5.1 当前问题
RunManager.cleanup() 已存在:
packages/harness/deerflow/runtime/runs/manager.py:318-324
但 worker finally 当前只调:
asyncio.create_task(bridge.cleanup(run_id, delay=60))
这只删除 stream bridge 中的流缓存,不删除 RunManager._runs。因此一个进程运行越久,create_or_reject() 在 manager lock 内扫描的对象越多。
5.2 建议改动
在 run 已完成、终态已持久化并发布 SSE end 后,调度 run registry 清理:
asyncio.create_task(bridge.cleanup(run_id, delay=60))
asyncio.create_task(run_manager.cleanup(run_id, delay=300))
延迟值可以结合重连窗口调整,但不要无限保留。
5.3 必须验证
- 完成后 60 秒内 SSE join/reconnect 行为不变;
- 内存记录删除后,
GET run能从持久化 store fallback; - 已完成 run 的 join 能返回干净终态,而不是 404;
- cancel/rollback 与正在运行的任务不会被提前删除;
- 管理员并发监控只展示真实 active run;
- 进程内
_runs数量在稳定负载下有上限,不随总历史永久增长。
这项修复与数据库 runs 保留策略无关,不会删除持久化历史记录。
6. P2:解除单 saver 实例的全局串行
6.1 不能采用的“优化”
仅提高:
DEER_FLOW_PG_POOL_MAX
不会解决问题,因为 saver 在 pool checkout 前先获取实例锁。连接池容量只有在多个可并发 saver 操作真正进入 checkout 时才有意义。
6.2 可评估的实现方向
按风险从低到高:
- 为只读 History 建立独立 saver/reader 实例,与 graph 写入 saver 使用同一个连接池但不同实例锁。
- 将 History 改为专用、只读、受支持的 PostgreSQL repository,明确复用 LangGraph schema 与序列化协议。
- 升级到确认支持 pool 并发且兼容当前 schema/serializer 的 checkpointer 版本。
- 维护受控 patch,使 pool 场景不再用一个实例锁包住所有连接,但必须保留单连接/pipeline 模式所需的互斥。
不要直接删除第三方 saver 的 lock。该 lock 还保护单连接、pipeline、cursor 和 setup 等行为,粗暴移除可能造成事务/cursor 并发错误。
6.3 并发回归要求
至少覆盖:
- 一个慢 history 与一个新 thread
aput并发; - history 与 graph
aput_writes并发; - 20 个不同 thread 同时读/写;
- 同一个 thread 的顺序和 checkpoint parent 关系;
- PostgreSQL 重启、断开连接、pool 替换坏连接;
- cancellation 不泄漏 cursor/connection/lock;
- setup migration 只安全执行一次或可幂等执行;
- 回答正文、最终 state 和历史 reopen 一致。
现有回归入口:
offline-backend-20260512/backend/packages/harness/tests/test_thread_operation_timing.py
7. 前端结束态优化
7.1 当前行为
SDK 将结束后的 history refresh 放在 stream 的成功收尾内等待,因此 /history 延迟会直接延长 thread.isLoading。
30 秒 control/history timeout 只是防止永久挂死,不是性能优化。
7.2 可选方向
如果后端已经保证 SSE 最终 state 足够完整,可以评估:
- SSE
end到达后立即结束输入区 loading; /history改为后台刷新;- 刷新失败不丢弃已经流式到达的答案;
- 后台 history 成功后再校准 checkpoint id、title、thread_data 和 messages。
不要只把 fetchStateHistory 改成 false。当前 onFinish(state, runMeta) 依赖最终 state,直接关闭会改变回调语义,并可能影响标题、消息状态、listener 和断流恢复。
发布前至少验证:
- 最后一条 assistant message 不闪退、不重复;
- 首轮 thread id 和 URL 更新正确;
- interrupt/HITL 与 resume 正确;
- 页面刷新能从 checkpoint 恢复;
- SSE 丢失终态时仍能通过后台 history 校准;
- 用户不会在后端 run 尚未真正结束时误发下一轮。
因此前端解耦建议放在数据库索引、namespace 和 saver 持锁优化之后。
8. runs 表的针对性优化
8.1 先确认实际索引
当前 ORM 声明包括:
runs_pkey(run_id)
ix_runs_thread_status(thread_id, status)
ix_runs_created_user_status(created_at, user_id, status)
ix_runs_user_created(user_id, created_at)
ix_runs_thread_created(thread_id, created_at)
ix_runs_created_assistant_user(created_at, assistant_id, user_id)
ix_runs_created_model_user(created_at, model_name, user_id)
生产库是否实际存在必须用 pg_indexes 验证。
8.2 不要为普通 INSERT/PK UPDATE 盲目加索引
普通 run 创建是 INSERT,结束是 WHERE run_id = ? 的 UPDATE。已有主键时,额外索引不会让这两个操作更快,反而增加每次 INSERT/UPDATE 的索引维护成本。
只有某个明确查询的 EXPLAIN 证明缺索引时才补建。例如:
-
WHERE thread_id=? ORDER BY created_at DESC LIMIT 100缺少(thread_id, created_at); -
pending 恢复查询成为已确认慢点时,才评估 partial index:
CREATE INDEX CONCURRENTLY IF NOT EXISTS ix_runs_pending_created ON public.runs (created_at) WHERE status = 'pending';
该 partial index不在普通 /threads 或 /history 路径上,不能作为本次问题的默认修复。
8.3 维护与膨胀
只有 pg_stat_user_tables 显示 runs/checkpoint 表死元组高、autovacuum 长期未运行时,才安排:
VACUUM (ANALYZE) public.runs;
VACUUM (ANALYZE) public.checkpoints;
VACUUM (ANALYZE) public.checkpoint_blobs;
VACUUM (ANALYZE) public.checkpoint_writes;
普通 VACUUM (ANALYZE) 与 VACUUM FULL 不同,但仍会产生 I/O,应低峰执行并监控。不要在线直接使用 VACUUM FULL。
autovacuum 参数应根据写入速率、表大小、死元组和数据库资源制定,不在没有现场指标时给所有表套固定值。
9. 数据保留和归档
归档不是本次 6 秒问题的第一优先级。确有长期容量压力时,另行设计:
- 明确保留期限与可恢复 SLA;
- 只归档真正终态且超过保留期的 thread;
checkpoints、checkpoint_blobs、checkpoint_writes必须按同一批 thread 完整处理;- 停止相关 writer 或使用经过验证的一致性流程;
- 先 dry-run,导出候选 thread,备份并演练恢复;
- 同库 archive schema 不一定立即回收磁盘;
- 旧会话入口与正文恢复策略要一起设计。
不要只删除 checkpoints 主表而留下 blob/write,也不要只按全局时间无视仍活跃 thread。
10. 建议实施顺序
阶段 A:当天可做
- 用配套排查文档采集一轮完整证据。
- 确认 6 秒集中在
checkpoint_create或/history。 - 对慢 thread 跑两条 EXPLAIN。
- 如果跨 namespace 查询有 Sort/大量扫描,低峰在线创建 P0 索引。
ANALYZE checkpoints,重跑 EXPLAIN。- 对比变更前后
/history与checkpoint_create。
阶段 B:下一次应用发布
- 确认普通 history 的 namespace 语义并限定
checkpoint_ns=''。 - 先完整消费
alist,在 saver lock 释放后序列化响应。 - 增加 history fetch/serialize 分段计时。
- 调用
RunManager.cleanup(),限制内存 registry 增长。 - 补单元、集成和并发回归。
阶段 C:压测后实施
- 评估独立 history saver/reader 或兼容升级。
- 验证多 checkpoint 操作真实并发。
- 再根据新架构调整 pool 大小。
- 基于真实容量与保留期制定归档策略。
11. 验收标准
不要只看一次“变快了”,至少记录一段稳定流量下的分位数。
| 指标 | 验收方式 |
|---|---|
/threads 总耗时 |
浏览器/APM p50、p95、p99 |
checkpoint_create |
Server-Timing/日志 p50、p95、p99 |
/history 总耗时 |
Gateway/APM p50、p95、p99 |
| History SQL | pg_stat_statements mean/max,EXPLAIN 实际时间 |
| saver 排队 | 应用分段计时中 lock/fetch 与 serialize 分离后观察 |
| 正确性 | 首轮、多轮、刷新、重连、interrupt、subagent 历史一致 |
| 资源 | PG CPU、I/O、WAL、连接数、新索引大小 |
| 内存 registry | _runs 数量不再随累计历史永久增长 |
成功信号:
- History 计划使用目标组合索引,或限定 namespace 后使用现有主键;
/history不再出现秒级长尾;- 同期 history 不再让新 thread 的
checkpoint_create出现同等长尾; - 回答正文结束到 UI 可再次输入之间的间隔显著下降;
- 对话刷新、历史恢复和重连行为无回归。
如果 History SQL 已稳定在毫秒级,但 checkpoint_create 仍有秒级长尾,应停止继续堆索引,转向 saver 实例锁和事件循环排队的 P1/P2 优化。
12. 变更与回滚清单
[ ] 保存部署 commit、配置和指标基线
[ ] 保存目标 thread 的 EXPLAIN
[ ] 核对 schema 和现有等价索引
[ ] CREATE INDEX CONCURRENTLY(不在事务中)
[ ] 检查 indisvalid/indisready
[ ] ANALYZE checkpoints
[ ] 重跑 EXPLAIN
[ ] 观察 API、PG、WAL、磁盘指标
[ ] 准备 DROP INDEX CONCURRENTLY 回滚语句
[ ] 代码变更补 history/subgraph/reconnect 回归
[ ] 先发布代码并观察,再决定是否删除临时索引