Skip to content

refactor(knowledge-graph): KG Build API 改为 fire-and-forget 模式,后台异步执行构建 - #508

Merged
ThreeFish-AI merged 1 commit into
feature/1.x.xfrom
ThreeFish-AI/copenhagen-v2
May 11, 2026
Merged

refactor(knowledge-graph): KG Build API 改为 fire-and-forget 模式,后台异步执行构建#508
ThreeFish-AI merged 1 commit into
feature/1.x.xfrom
ThreeFish-AI/copenhagen-v2

Conversation

@ThreeFish-AI

Copy link
Copy Markdown
Owner

背景

核心变更

  • service.py:将 GraphService.build_graph 拆分为 _init_build_run(<1s 快速创建 build run 记录 + 注册取消信号)与 _execute_build(后台执行全量构建管线);原 build_graph 保留为向后兼容 wrapper(init + execute 顺序调用)
  • api.py:API 层同步 await _init_build_run 获取 run_id 后立即返回 status="running";实际构建由 asyncio.create_task 在后台执行,通过 _KG_BUILD_BG_TASKS 强引用集合防止 GC 回收
  • route.ts:BFF 代理超时从 LONG_TASK_PROXY_TIMEOUT_MS(15min)降至 DEFAULT_PROXY_TIMEOUT_MS(30s),仅需覆盖 init 阶段
  • 进度上报改为自适应节流:max(1, total_chunks // 200) + 5s 时间兜底(原固定 5 chunks / 10s)
  • 新增 chunk 级 debug 日志(chunk_processing_started / chunk_processing_completed)及 timeout warning 日志,增强可观测性

风险与回滚

验证证据

  • 单元测试:ruff lint/format + ESLint 通过
  • 集成测试:fire-and-forget 不改变 _execute_build 内部逻辑,现有测试覆盖不变
  • E2E/Workflow:需浏览器验证:触发 KG Build → API 即刻返回 running → 轮询进度正常推进至终态

影响范围

  • 前端:无变更(前端已为轮询模式)
  • 后端:knowledge/api.pyknowledge/graph/service.py
  • GitHub Actions / 文档:无

Next Best Action

  • 验证:在 staging 环境触发一次完整 KG Build,确认 API 响应 < 1s 且后台构建正常完成
  • 可选优化:_init_build_run 当前为 private 方法,可考虑提升为 public 接口以改善 API 层调用封装

- 将 GraphService.build_graph 拆分为 _init_build_run(同步创建 run 记录)+ _execute_build(后台执行构建),保留 build_graph 作为向后兼容 wrapper
- API 层即刻返回 run_id + status="running",实际构建由 asyncio.Task 后台执行
- BFF 超时从 LONG_TASK_PROXY_TIMEOUT_MS(15min) 降至 DEFAULT_PROXY_TIMEOUT_MS(30s),覆盖 init 阶段即可
- 进度上报改为自适应节流(total_chunks // 200 + 5s 时间兜底),优化大/小 corpus 上报频率
- 新增 chunk 级 debug 日志(start/completed/timeout),增强可观测性

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>
@ThreeFish-AI
ThreeFish-AI merged commit 729e815 into feature/1.x.x May 11, 2026
13 checks passed
@ThreeFish-AI
ThreeFish-AI deleted the ThreeFish-AI/copenhagen-v2 branch May 11, 2026 10:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant