Files
deerflow-code/docs/线程创建与History等待慢-优化方案.md
T

18 KiB
Raw Blame History

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 适用条件

同时满足以下条件时执行:

  1. 线上 /history 当前需要跨 checkpoint_ns 返回最新 checkpoint;或者短期内不能发布代码来限定 namespace。
  2. 慢 thread 的执行计划出现 per-thread Sort、扫描候选行较多或执行时间明显高于限定 checkpoint_ns='' 的版本。
  3. 已确认目标表 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 上线观察

至少对比变更前后:

  • /history p50/p95/p99;
  • POST /threads 的 checkpoint_create p50/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 可评估的实现方向

按风险从低到高:

  1. 为只读 History 建立独立 saver/reader 实例,与 graph 写入 saver 使用同一个连接池但不同实例锁。
  2. 将 History 改为专用、只读、受支持的 PostgreSQL repository,明确复用 LangGraph schema 与序列化协议。
  3. 升级到确认支持 pool 并发且兼容当前 schema/serializer 的 checkpointer 版本。
  4. 维护受控 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:当天可做

  1. 用配套排查文档采集一轮完整证据。
  2. 确认 6 秒集中在 checkpoint_create 或 /history。
  3. 对慢 thread 跑两条 EXPLAIN。
  4. 如果跨 namespace 查询有 Sort/大量扫描,低峰在线创建 P0 索引。
  5. ANALYZE checkpoints,重跑 EXPLAIN。
  6. 对比变更前后 /history 与 checkpoint_create。

阶段 B:下一次应用发布

  1. 确认普通 history 的 namespace 语义并限定 checkpoint_ns=''。
  2. 先完整消费 alist,在 saver lock 释放后序列化响应。
  3. 增加 history fetch/serialize 分段计时。
  4. 调用 RunManager.cleanup(),限制内存 registry 增长。
  5. 补单元、集成和并发回归。

阶段 C:压测后实施

  1. 评估独立 history saver/reader 或兼容升级。
  2. 验证多 checkpoint 操作真实并发。
  3. 再根据新架构调整 pool 大小。
  4. 基于真实容量与保留期制定归档策略。

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 回归
[ ] 先发布代码并观察,再决定是否删除临时索引