refactor(knowledge-graph): KG Build API 改为 fire-and-forget 模式,后台异步执行构建 - #508
Merged
Merged
Conversation
- 将 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>
This was referenced May 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
build-runs/latest获取进度,API 同步等待造成不必要的资源占用与超时风险。核心变更
GraphService.build_graph拆分为_init_build_run(<1s 快速创建 build run 记录 + 注册取消信号)与_execute_build(后台执行全量构建管线);原build_graph保留为向后兼容 wrapper(init + execute 顺序调用)_init_build_run获取 run_id 后立即返回status="running";实际构建由asyncio.create_task在后台执行,通过_KG_BUILD_BG_TASKS强引用集合防止 GC 回收LONG_TASK_PROXY_TIMEOUT_MS(15min)降至DEFAULT_PROXY_TIMEOUT_MS(30s),仅需覆盖 init 阶段max(1, total_chunks // 200)+ 5s 时间兜底(原固定 5 chunks / 10s)chunk_processing_started/chunk_processing_completed)及 timeout warning 日志,增强可观测性风险与回滚
_execute_build内部已覆盖 DB 终态写入(含双重 fallback),极端情况由看门狗(fix(watchdog): 看门狗定时任务增加 KG Build Runs 卡死状态收敛 (#502) #502)兜底收敛git revert本提交即可,向后兼容 wrapperbuild_graph不影响其他调用方验证证据
_execute_build内部逻辑,现有测试覆盖不变running→ 轮询进度正常推进至终态影响范围
knowledge/api.py、knowledge/graph/service.pyNext Best Action
_init_build_run当前为 private 方法,可考虑提升为 public 接口以改善 API 层调用封装