fix(knowledge-graph): KG Build 管线七项级联缺陷端到端深度修复

[ThreeFish-AI]

背景

依据 2026-05-12 10:00–10:19 的一次完整 KG Build 日志（corpus 43bacd7e-...、20 chunks、~520s）端到端循证排查，结合 docs/knowledge-graph.md 理论梳理与 docs/issue.md（ISSUE-013/-020/-026/-077/-081 等历史沉淀），识别出 七项相互独立但级联放大 的缺陷。最终产物名义 entity_count=98 relation_count=152 status=completed，实际：

• PageRank importance_score 全 NULL（UPDATE SQL 报错）
• Leiden 三次降级失败（NetworkX 3.x dispatch wrapper 误用）
• Community Summary LLM 3 次重试全部失败（temperature=0.3 与 gpt-5 系列冲突）
• Embedding 上游 400 invalid prompts（本地 Gemini 翻译代理兼容缺陷）
• chunk_index 并发竞态致 3 并发同时 log chunk_index=1
• extracting 阶段 8 分钟内 build_run_updated entity_count=0 relation_count=0 静默
• 152 条关系最终落库仅 143 条，神秘丢失 9 条（relations_synced 计数虚高）

KG 名义构建成功，实际下游 GraphRAG / Global Search 几乎不可用。本 PR 一次性正交修复全部 7 项缺陷。

缺陷与修复对照

#	缺陷（日志证据）	文件:行	根因	修复
1	syntax error at or near \"uuid\"	graph_algorithms.py:142-160 / 368-384	PostgreSQL 不接受 FROM (VALUES …) AS v(col type, …) 内联类型声明	占位符级 CAST(:eid_n AS uuid) / CAST(:cid AS uuid) 显式转型
2	'leiden_communities' is not implemented by 'networkx' backend ×3	graph_algorithms.py:34-89 / 310-360	nx.community.leiden_communities 是 dispatch wrapper，不会派发到 leidenalg	新增 _run_leiden() 经由 igraph + leidenalg.find_partition 直连；首层失败一次性降级 Louvain
3	gpt-5 … don't support temperature=0.3 ×3	extractors.py::call_llm_with_retry + community_summarizer.py::_call_llm	call_llm_with_retry 既未读取 resolve_llm_config() 返回的 drop_params，也未全局设置	增可选 extra_kwargs: dict 参数、litellm.drop_params=True 幂等设置、_PROTECTED_KEYS 守卫；caller 透传 vendor 配置
4	litellm.BadRequestError: \"request body doesn't contain valid prompts\"	embedding.py:185-246	本地 Gemini 翻译代理 localhost:3392 对 :batchEmbedContents 兼容不全（环境侧）	新增 _build_embedding_failure_hint() 输出可诊断 hint（建议切换 openai embedding / 检查 NATIVE_GEMINI_BASE_URL）
5	3 并发 chunk 同时 chunk_index=1	service.py:605-656	chunks_processed + 1 并发非原子读	调度时 enumerate(batch) 注入 1-based 全局序号 i + offset + 1
6	extracting 阶段 entity_count=0 relation_count=0 持续 8 分钟	service.py::maybe_report_chunk_progress	节流路径仅更新 progress_percent，未累计落库	同步 len(all_entities) / len(all_relations) 并在 chunk_batch_progress 日志透出
7	relations_synced=152 但 edge_count=143，9 条静默丢失	entity_service.py::sync_relation + batch_sync_from_graph_build	端点缺失 / 重复三元组时 silent return，caller try: relations_synced += 1 把跳过当成功	sync_relation / sync_entity_from_knowledge 改返回 bool；caller 拆 relations_created / relations_skipped / relations_failed 三计数；端点缺失日志 debug → warning

工程纪律沉淀（跨上下文准则）

1. PostgreSQL UPDATE-FROM-VALUES 范式：批量 UPSERT/UPDATE 一律占位符级 CAST(:p AS type)，禁用 AS v(col type) 内联（asyncpg/psycopg3/pg-protocol bridge 多驱动行为不一致）
2. NetworkX 3.x dispatch wrapper 边界：调用 nx.community.* 前必须确认是否为 dispatch wrapper；Leiden / Modularity 算法一律走 igraph + leidenalg 直连
3. LiteLLM 入口 drop_params 强制兜底：所有 litellm.acompletion / aembedding 入口必须传 drop_params=True 或进程级开关；call_llm_with_retry 已统一注入
4. Silent return = silent data loss：服务层任何"幂等跳过"必须以返回值或专属计数器外露；调用方按返回值累加 success/skip/fail，禁用"未抛异常 = 成功"语义
5. Phase-level cumulative reporting：节流上报路径除 progress 外，业务计数必须同步落库

详见 docs/issue.md ISSUE-082 与 docs/knowledge-graph.md 5.3 节方法学补丁。

改动文件清单

源码（6）：

• apps/negentropy/src/negentropy/knowledge/graph/graph_algorithms.py（PageRank SQL + Leiden）
• apps/negentropy/src/negentropy/knowledge/graph/extractors.py（call_llm_with_retry + drop_params）
• apps/negentropy/src/negentropy/knowledge/graph/community_summarizer.py（extra_kwargs 透传）
• apps/negentropy/src/negentropy/knowledge/graph/service.py（chunk_index 预分配 + 累计计数上报）
• apps/negentropy/src/negentropy/knowledge/graph/entity_service.py（sync_relation bool 返回 + 三计数拆分）
• apps/negentropy/src/negentropy/knowledge/ingestion/embedding.py（actionable hint）

依赖（1）：apps/negentropy/pyproject.toml 追加 igraph>=0.11（+ uv.lock 同步）

测试（3）：

• 新增 tests/unit_tests/knowledge/test_kg_build_pipeline_fixes.py（9 条 UT，每项缺陷独立锁定契约）
• 升级 test_kg_entity_service_unit.py / test_graph_entity_service.py 三条原 "silent assertion of bug" 用例（之前把跳过当成功，现校正为 relations_synced=0 + relations_skipped=N 真值）

文档（2）：docs/issue.md（ISSUE-082）+ docs/knowledge-graph.md（5.3 方法学补丁）

测试与质量

• ✅ uv run pytest tests/unit_tests：1466 通过（1 个 pre-existing test_extraction_llm_plan 失败与本次无关，git stash 验证）
• ✅ 9 条新 UT 全绿，包括：PageRank SQL 含 CAST(:eid AS uuid) / 反向断言 v(eid uuid 不再出现；Leiden 经 leidenalg 直连而非 NetworkX dispatch；drop_params 全局幂等 + _PROTECTED_KEYS 不被覆盖；Embedding hint 已知模式触发 / 未知模式空返回；sync_relation 端点命中返回 True / 缺失返回 False
• ✅ uv run ruff check：全绿（含 pre-commit hook 自动 format 后再校验）

验证范围说明

本次以确定性单元测试完整锁定 7 项修复契约。未进行浏览器端到端实机验证 —— 本地后端 / UI / Gemini Proxy 当前未在 dev 环境启动。如需 E2E 验证，参 docs/agents/browser-validation.md 与计划文件中 7 个观察点（A-G）执行：

• 观察点 A（fix(knowledge,memory): 第二轮审查改进 — 接入批量 embedding、统一 schema 引用、注册 FactS… #5/Ng/263e agents #6）：构建期 UI 计数随 chunk 完成单调增长 + 3 并发 chunk_index 互不重复
• 观察点 B（Feature/1.0.0 #1）：SELECT importance_score FROM kg_entities WHERE corpus_id=... ORDER BY 1 DESC 返回非 NULL Top-10
• 观察点 C（Feature/1.0.0 #2）：日志含 community_level_completed level=0/1/2 community_count>1
• 观察点 D（Feature/1.0.0 #3）：日志无 community_summary_exhausted；kg_community_summaries 多条非空摘要
• 观察点 E（fix(knowledge,memory): 全面审查与改进 Knowledge Base & Memory 模块 #4）：embedding 失败时日志携带 hint= 字段；摘要可降级落库（embedding NULL）
• 观察点 F（Feature/1.0.0 theme #7）：kg_first_class_sync relations_synced=N relations_skipped=M 与 graph_loaded edge_count 数值闭环一致
• 观察点 G：前端 KgBuildProgressPill SSE 终态自卸；轮询自然停止

Test plan

• uv run pytest tests/unit_tests/knowledge 全绿（678 通过，含 9 条新增）
• uv run pytest tests/unit_tests 全量 1466 通过
• uv run ruff check 全绿
• pre-commit hook（ruff lint / ruff format）通过
• 浏览器端到端（需 reviewer 在本地或 staging 启动完整 stack 后按观察点 A-G 验证）

🤖 Generated with Claude Code, CodeX, Gemini