#知识图谱架构设计与工程实施方案

本文档是 Negentropy 知识图谱模块的架构设计单一权威参考 (Single Source of Truth)，涵盖学术理论基础、行业框架分析、两阶段工程方案（PostgreSQL 阶段 → 终极阶段）以及价值量化体系。

• 系统全景架构：framework.md
• Knowledge 模块全景：035-the-knowledge-base.md
• Memory 模块设计：025-the-memory-system.md
• 数据库 Schema：schema/kg_schema_extension.sql
• 源码入口：
  • 策略基类：knowledge/graph/strategy.py
  • LLM 提取器：knowledge/graph/extractors.py
  • 图谱存储：knowledge/graph/repository.py
  • 图谱服务：knowledge/graph/service.py
  • 类型定义：knowledge/types.py
  • REST API（图谱子路由）：knowledge/api.py

#目录

1. 愿景与哲学基础
2. 学术理论基础
3. 行业框架全景分析
4. 当前实现现状 (Phase 1)
5. PostgreSQL 阶段深度设计
6. 终极阶段设计
7. 价值量化体系
8. 一核五翼集成架构
9. 实施路线图
10. 风险管理与边界控制
11. 参考文献
12. 变更日志

#1. 愿景与哲学基础

#1.1 结构化负熵：知识图谱的核心价值

Negentropy（熵减引擎）的命名源自薛定谔在《生命是什么》中提出的核心洞见——生命以负熵 (Negentropy) 为食^[12]。映射到知识系统，知识图谱是实现结构化负熵的核心机制：将散乱的文本信息转化为有序的实体-关系网络，从根本上对抗知识碎片化的熵增趋势。

知识图谱是 Hogan 等人所定义的"由实体（节点）及其相互关系（边）组成的图结构数据模型，用于集成、管理和从数据中提取价值"^[1]。在 Negentropy 的语境下，知识图谱是 Knowledge 模块^[10]的核心结构化组件，由内化系部 (InternalizationFaculty) 通过 update_knowledge_graph 工具触发构建——将感知系部获取的原始信息，经过实体提取、关系映射和图谱构建，形成可推理、可遍历、可量化的知识网络。

#1.2 超越向量检索

纯向量语义检索（如 Negentropy 现有的 pgvector HNSW）虽然在"找到相似内容"方面表现优异，但存在本质局限^[2]：

#1.3 知识图谱在五翼架构中的定位

#2. 学术理论基础

#2.1 知识图谱基本概念

知识图谱的核心数据模型可归纳为两大流派^[1]：

RDF（资源描述框架）：W3C 标准，以 (Subject, Predicate, Object) 三元组为原子单位，强调全局语义互操作性与形式化推理能力（OWL / RDFS）。

属性图 (Property Graph)：以节点和边为一等公民，节点和边均可附带任意属性。查询语言包括 Cypher (Neo4j)、GQL (ISO 标准)、openCypher (Apache AGE)。

Negentropy 选择属性图模型，理由：

1. Apache AGE 原生支持 openCypher，与 PostgreSQL 完全融合
2. 属性图的灵活 Schema 契合演进式设计原则
3. 边上的属性（weight, confidence, evidence）对检索质量至关重要

#2.2 知识图谱嵌入

知识图谱嵌入 (KGE) 将实体和关系映射到连续向量空间，支持链接预测和实体分类^[2]：

• TransE^[2]：基础翻译模型，$\mathbf{h} + \mathbf{r} \approx \mathbf{t}$，适合一对一关系但难以处理对称/多对多关系
• RotatE^[3]：在复数空间中将关系建模为旋转 $\mathbf{t} = \mathbf{h} \circ \mathbf{r}$（$\mathbf{r}_i = e^{i\theta_i}$），天然保持对称性、反对称性、逆关系和组合关系模式
• ComplEx / DistMult：基于双线性模型的语义匹配，适合复杂关系模式

在 Negentropy 中的应用场景：KGE 在终极阶段可用于实体链接预测（发现隐含关系）和图增强检索（embedding 距离作为补充排序信号）。当前阶段暂不需要 KGE，优先使用 LLM 直接提取。

#2.3 GraphRAG 范式

Microsoft GraphRAG^[4] 开创了结构化检索增强生成范式，核心流程：

1. 文本分割为 TextUnit → LLM 提取实体和关系 → 构建知识图谱
2. Leiden 算法进行分层社区检测^[15]
3. LLM 为每个社区生成自然语言摘要
4. 双模式检索：
   • Local Search：从查询实体出发做图遍历，聚合邻域上下文
   • Global Search：Map-Reduce 遍历社区摘要，适合全局性问题

LightRAG^[5] 提出了更高效的替代方案：

• 双层检索：Low-Level（实体 + 直接关系）+ High-Level（概念/主题级聚合）
• 增量更新：新文档通过 Union 操作合并到现有图谱（无需重建）
• 性能优势：比 GraphRAG 节省约 6000 倍 token 消耗，查询延迟降低约 33%

#2.4 时态知识图谱

Graphiti/Zep^[6] 提出了面向 AI Agent 的双时态知识图谱架构：

• 三层级结构：Episode 子图（原始输入）→ Semantic Entity 子图（提取实体/关系）→ Community 子图（聚类摘要）
• 双时态模型：
  • 事件时间线 (T)：事实在真实世界的有效时间 (t_valid, t_invalid)
  • 事务时间线 (T')：事实被系统记录的时间 (t_make, t_expire)
• 矛盾处理：新信息与旧事实冲突时，系统自动设置 t_invalid 使旧边失效
• 性能基准：Deep Memory Retrieval 准确率 94.8%（vs MemGPT 93.4%），延迟降低 ~90%

与 Negentropy Memory 模块的互补：Memory 模块使用 Ebbinghaus 遗忘曲线^[8]管理情景记忆（完整公式：retention_score = min(1.0, e^{-λt} × (1 + ln(1+n)) / 5.0)，详见 025-the-memory-system.md），知识图谱提供结构化语义记忆——两者分别对应人类认知的海马体（短期/情景）与新皮层（长期/结构化）。

#2.5 倒数排名融合

Cormack 等人提出的 Reciprocal Rank Fusion (RRF)^[7] 为多信号融合提供了无需参数调优的稳健方案：

$RRF(d) = \sum_{r \in R} \frac{1}{k + rank_r(d)}$

其中 $k$ 为平滑常数（Negentropy 默认 $k=60$，配置于 SearchConfig.rrf_k）。RRF 的核心优势是对分数尺度不敏感，无论语义分数范围是 [0,1] 还是图分数范围是 [0,5]，排名融合都能产生稳健结果。Negentropy 的知识检索已在 L0 阶段支持 RRF 模式（见 035-the-knowledge-base.md §5.2），知识图谱的混合检索将进一步扩展 RRF 的信号来源。

#3. 行业框架全景分析

#3.1 Cognee：ECL 管道与 PostgreSQL 原生支持

Cognee 是面向 AI Agent 的知识引擎，采用 ECL (Extract-Cognify-Load) 管道架构^[13]：

• Extract：从任意格式文档提取结构化数据
• Cognify：LLM 驱动的实体/关系提取 + 去重 + Schema 推断
• Load：三层存储（图数据库 + 向量数据库 + 关系数据库）

关键特性：

• PostgreSQL 原生支持（关系存储）+ pgvector（向量存储）
• 图存储支持 Neo4j / KuzuDB / FalkorDB / NetworkX
• 异步操作全栈、可插拔 LLM 提供商
• Local-first 无强制云依赖

与 Negentropy 的契合点：Cognee 的 ECL 管道天然映射到 Negentropy 的"感知 → 内化"管道；三层存储模型与 Negentropy 的 PostgreSQL + pgvector + Apache AGE 完全对齐。

#3.2 Graphiti/Zep：双时态与记忆级 KG

Graphiti 是 Zep 开源的时态知识图谱引擎^[6]：

• 三层级图结构：Episode（原始输入）→ Semantic Entity（实体/关系）→ Community（聚类摘要）
• 三级实体解析：精确匹配 → 模糊相似度 → LLM 推理
• 实时增量更新：无需批量重计算
• 混合检索：语义嵌入 + BM25 关键词 + 图遍历

与 Negentropy 的契合点：双时态模型与 Memory 模块的遗忘曲线形成互补；实体解析策略可增强现有 LLMEntityExtractor 的去重能力。

#3.3 Microsoft GraphRAG：社区检测与层级摘要

GraphRAG 由 Microsoft Research 提出^[4]：

• Leiden 社区检测^[15]：基于模块度优化的分层聚类
• 层级摘要：每个社区由 LLM 生成自然语言总结
• Map-Reduce 全局搜索：遍历社区摘要回答全局性问题
• 技术无关知识模型：通过抽象层适配多种存储后端

与 Negentropy 的契合点：社区摘要天然服务于坐照系部的"二阶思维"——从实体关系中浮现宏观洞察。

#3.4 LightRAG：高效双层检索

LightRAG 以极简主义实现高效 GraphRAG^[5]：

• 双层检索：Low-Level（具体实体和直接关系）+ High-Level（概念/主题聚合）
• 增量更新：通过 Union 操作合并新图谱（无需全量重建）
• 可插拔存储：JSON / PostgreSQL / Neo4j / MongoDB / Redis

性能对比：

与 Negentropy 的契合点：LightRAG 的成本效率模型非常适合初期部署；PostgreSQL 原生支持降低集成门槛。

#3.5 Apache AGE：PostgreSQL 原生图扩展

Apache AGE 为 PostgreSQL 提供属性图能力^[11]：

• openCypher 查询语言：通过 cypher() 函数在 SQL 中执行图查询
• 零额外基础设施：作为 PostgreSQL 扩展安装，复用现有连接池、事务、备份
• 混合查询：SQL + Cypher 在同一事务中执行
• agtype 数据类型：存储图节点和边的属性

#3.6 框架决策矩阵

#3.7 复用策略

遵循 AGENTS.md 复用驱动 (Composition over Construction) 原则：

#3.7 可采纳的架构模式精炼

基于对 Cognee、Graphiti、Neo4j GDS 的深度调研，提炼出以下可直接采纳的架构模式：

Cognee ECL 管道模式：Extract-Cognify-Load 三层解耦架构^[13]。Extract 层负责文档解析与分块（对应 Negentropy 的感知系部），Cognify 层负责 LLM 提取、实体去重与 Schema 推断（对应 GraphService + LLM 提取器），Load 层负责三层存储（图 + 向量 + 关系，对应 PostgreSQL + pgvector + AGE）。核心启示：管道的每一层应是可独立替换的策略，通过接口解耦。

Graphiti 双时态模型^[14]：关系同时携带 valid_from/valid_to（事实有效时间）和 created_at/expired_at（系统记录时间）两组时态字段。事实时间用于回答"这段关系何时成立"，系统时间用于回答"系统何时知道这段关系"。Deep Memory Retrieval（DMR）准确率达 94.8%，关键在于三级实体解析（精确匹配 → 嵌入相似度 > 0.92 → LLM 推理）。Negentropy 可在 Phase 3 在 KgRelation 的 first_observed_at/last_observed_at 基础上扩展双时态字段。

Neo4j GDS 算法库^[6]：提供 50+ 图算法（PageRank、Louvain、Node2Vec 等）。Negentropy 当前采用 PostgreSQL 单一技术栈，图算法通过 Python networkx 实现而非数据库内计算。迁移阈值：图规模 >100K 实体 / 频繁 4+ 跳查询 / 需要 50+ GDS 算法时，评估迁移到 Neo4j。 | 向量检索 | ✅ pgvector HNSW (已有) | RRF 融合图分数 |

#4. 当前实现现状 (Phase 1)

#4.1 已完成交付物

Phase 1 基础能力增强已于 2026-02 完成，主要交付物：

#4.2 当前架构

#4.3 实体与关系类型

实体类型 (8 种)：

class KgEntityType(Enum):
    PERSON = "person"            # 人物
    ORGANIZATION = "organization" # 组织/公司
    LOCATION = "location"        # 地点
    EVENT = "event"              # 事件
    CONCEPT = "concept"          # 概念/术语
    PRODUCT = "product"          # 产品
    DOCUMENT = "document"        # 文档（注：当前 LLM 提取 Prompt 未包含此类型，将归入 OTHER）
    OTHER = "other"              # 其他

关系类型 (13 种，含 Phase 5 新增 CUSTOM)：

class KgRelationType(Enum):
    # 组织关系
    WORKS_FOR = "WORKS_FOR"        # 就职于
    PART_OF = "PART_OF"            # 隶属于
    LOCATED_IN = "LOCATED_IN"      # 位于
    # 语义关系
    RELATED_TO = "RELATED_TO"      # 相关
    SIMILAR_TO = "SIMILAR_TO"      # 相似
    DERIVED_FROM = "DERIVED_FROM"  # 衍生自
    # 因果关系
    CAUSES = "CAUSES"              # 导致
    PRECEDES = "PRECEDES"          # 先于
    FOLLOWS = "FOLLOWS"            # 后于
    # 引用关系
    MENTIONS = "MENTIONS"          # 提及
    CREATED_BY = "CREATED_BY"      # 创建者
    # 共现关系（回退）
    CO_OCCURS = "CO_OCCURS"        # 共现
    # 开放关系（Phase 5 E1 新增）
    CUSTOM = "CUSTOM"              # 用户自定义关系类型

#4.4 数据流

#4.5 API 端点

#4.6 诚实评估：当前限制

基于代码事实的审视，Phase 1 存在以下待改进之处：

1. JSONB 关系存储：AgeGraphRepository 中部分关系通过 knowledge.metadata 的 JSONB 字段存储，尚未完全迁移到 Apache AGE 原生图边。这限制了真正的 Cypher 图遍历能力。

2. 简化路径查询：find_path() 方法为简化实现，未使用 AGE 的 shortestPath() Cypher 函数。

3. 简化邻居遍历：SQL 函数 kg_neighbors() 使用递归 CTE 近似，而非真正的 AGE Cypher 多跳遍历。真正的 Cypher 遍历函数 kg_cypher_neighbors() 已定义但需要应用层配合。

4. 无图算法：PageRank（kg_entity_importance() 为简化度中心性近似）、社区检测均未实现。

5. 无时态建模：关系无时间维度，无法追踪事实有效期。

6. 无 GraphRAG：混合检索 kg_hybrid_search() 采用语义分数 + 图度分数线性加权，尚未实现社区级检索或双层检索。

#5. PostgreSQL 阶段深度设计

#5.1 设计原则

#5.2 增强图存储：JSONB → AGE 原生图边

目标：将关系存储从 knowledge.metadata JSONB 完全迁移到 Apache AGE 原生图边，释放 Cypher 遍历能力。

迁移策略（双读兼容）：

关键实现细节：

1. AgeGraphRepository.create_relations() 改为调用 kg_create_relation() SQL 函数（已在 Schema 的 Cypher 辅助函数部分定义）
2. Session 预热：每个数据库连接需执行 LOAD 'age'; SET search_path = ag_catalog, "$user", public;
3. 实体 ID 映射：维护 knowledge.id ↔ AGE vertex id 的双向映射

#5.3 图算法层

#5.3.1 PageRank

当前 kg_entity_importance() 为简化度中心性（ln(1 + 入度 + 出度)）。需升级为迭代式 PageRank：

PostgreSQL 迭代式 PageRank 设计：

-- 迭代 PageRank (阻尼因子 d=0.85, 最大迭代 max_iter=20)
CREATE OR REPLACE FUNCTION kg_pagerank(
    p_corpus_id UUID,
    p_damping FLOAT DEFAULT 0.85,
    p_max_iter INTEGER DEFAULT 20,
    p_tolerance FLOAT DEFAULT 1e-6
)
RETURNS TABLE (entity_id UUID, rank FLOAT)
AS $$
WITH RECURSIVE pagerank AS (
    -- 初始化: 均匀分布
    SELECT id AS entity_id, 1.0 / COUNT(*) OVER() AS rank, 0 AS iter
    FROM knowledge WHERE corpus_id = p_corpus_id AND entity_type IS NOT NULL

    UNION ALL

    -- 迭代: PR(v) = (1-d)/N + d * Σ PR(u)/out_degree(u)
    SELECT ... -- 完整实现参见 Phase 2 交付
)
SELECT entity_id, rank FROM pagerank
WHERE iter = (SELECT MAX(iter) FROM pagerank);
$$ LANGUAGE SQL;

备选方案：若迭代 CTE 性能不佳（预期在 >10K 实体时出现瓶颈），可在 Python 服务层使用 networkx.pagerank() 计算后写回数据库。

#5.3.2 社区检测 (Leiden / Louvain)

采用 Python 服务层 + igraph + leidenalg 实现 Leiden（Traag et al., 2019^[15]，保证社区内部连通性），networkx.community.louvain_communities 兜底。关键工程纪律：NetworkX 3.x 的 nx.community.leiden_communities 是 dispatch wrapper，不会自动派发到 leidenalg backend — 调用时反而抛 NotImplementedError: 'leiden_communities' is not implemented by 'networkx' backend（参 issue.md ISSUE-082）。必须经由 igraph.Graph + leidenalg.find_partition 直连。

# graph_algorithms.py（实际实现）
def _run_leiden(G_undirected, *, resolution: float, seed: int) -> list[set[str]]:
    import igraph as ig
    import leidenalg
    nodes = list(G_undirected.nodes())
    node_to_idx = {n: i for i, n in enumerate(nodes)}
    edges, weights = [], []
    for u, v, data in G_undirected.edges(data=True):
        edges.append((node_to_idx[u], node_to_idx[v]))
        weights.append(float(data.get("weight") or 1.0))
    g = ig.Graph(n=len(nodes), edges=edges, directed=False)
    if weights:
        g.es["weight"] = weights
    partition = leidenalg.find_partition(
        g, leidenalg.RBConfigurationVertexPartition,
        weights="weight" if weights else None,
        resolution_parameter=resolution, seed=seed,
    )
    return [{nodes[i] for i in cluster} for cluster in partition]

存储设计：社区 ID 持久化到 kg_entities.community_id（一等公民列）；多层级摘要落 kg_community_summaries（GraphRAG Global Search 依赖）。批量 UPDATE 采用占位符级 CAST(:eid_n AS uuid) 显式类型转换 — 禁用 FROM (VALUES …) AS v(col type) 内联类型声明（PostgreSQL 不接受，会抛 syntax error at or near "uuid"，参 ISSUE-082）。

-- 正确范式（PageRank / 社区检测 UPDATE 共用）
UPDATE negentropy.kg_entities e
SET community_id = v.cid
FROM (VALUES
    (CAST(:eid_0 AS uuid), :cid_0),
    (CAST(:eid_1 AS uuid), :cid_1)
) AS v(eid, cid)
WHERE e.id = v.eid AND e.corpus_id = CAST(:corpus_id AS uuid);

#5.3.3 最短路径

升级当前桩实现，使用 AGE 原生 Cypher shortestPath()：

-- 使用 AGE Cypher 的最短路径查询
SELECT * FROM cypher('negentropy_kg', $$
    MATCH path = shortestPath(
        (a:Entity {id: $source_id})-[*..5]-(b:Entity {id: $target_id})
    )
    RETURN nodes(path) as nodes,
           relationships(path) as rels,
           length(path) as distance
$$, params => '...');

#5.3.4 Personalized PageRank 与多跳推理（Phase 4 G4 已落地）

理论锚点：Page et al. (1999) PageRank 通过偏置 teleport 向量实现"以查询为中心"的相关性传播；HippoRAG (Gutiérrez et al., NeurIPS'24) 在多跳问答上证明 PPR + 命名实体抽取 优于密集检索 ~20%。

计算入口：graph_algorithms.compute_personalized_pagerank(db, corpus_id, seed_entities, alpha=0.85)：

• 复用 export_graph_to_networkx；将 seed 归一化（去 entity: 前缀 + 过滤不在图中的）
• personalization 字典：valid seeds 平均分配权重 1/N，其余节点 0
• nx.PowerIterationFailedConvergence 时降级为"种子节点 1.0、其余 0"，与 PageRank 失败降级互补
• 不写库（不污染 kg_entities.importance_score），分数仅用于本次 multi_hop_reason 调用

Provenance 证据链：graph/provenance.py::ProvenanceBuilder 对 PPR top-K 反向追溯：

• 单次递归 CTE BFS 在 kg_relations 上找出 target → 任意 seed 的最短无向路径（默认 max_chain_depth=5）
• 沿路径逐跳 JOIN kg_relations 获取 relation_type + evidence_text + weight，组装 EvidenceEdge 列表
• 单一职责：仅产出"展示用"路径；时态版本由 repository.find_path(as_of=...) 承担，避免循环依赖

API：POST /base/{cid}/graph/multi_hop_reason：

• 入参：{query, seed_entities[], top_k=10, max_hops=3}；seed_entities 留空时按规则从 query 提取（英文大写词、引号括起的中英短语）
• seed → entity_id 解析：UUID 直接用；否则按 kg_entities.name ILIKE 等值/前缀模糊匹配（按 confidence DESC 取首条）
• 出参：{seeds, answer_entities, evidence_chain[], latency_ms}；evidence_chain 按 PPR 降序

Migration 0025：kg_query_provenance 审计表（query/seeds/top_entities/evidence_chain/latency 留痕），用于后续抽样质检与训练数据生成。

降级路径：seeds 提取为空 → 直接返回空 evidence_chain（不抛错）；seed 全部不在图中 → PPR 返回空字典，UI 显式提示"未发现可达路径"。

#5.4 混合检索增强

目标：构建 Vector + Graph + RRF 三层融合检索管道。

RRF 多信号融合：

RRF_score(d) = 1/(k + rank_semantic(d)) + 1/(k + rank_graph(d))

• rank_semantic：pgvector 余弦相似度排名
• rank_graph：基于实体度中心性 + 邻域丰富度的排名
• Phase 3 增加 rank_community：基于社区重要性的排名

配置扩展：在现有 GraphSearchMode 类型中增加检索模式。当前定义为 Literal 类型别名：

# 当前定义 (types.py) — 已含 global 模式用于 Global Search
GraphSearchMode = Literal["semantic", "graph", "hybrid", "global"]

#5.5 实体/关系类型扩展

可扩展分类设计：

当前 8 种实体类型和 12 种关系类型覆盖了通用场景。为支持领域特定需求（如法律、医疗、代码），设计可扩展的分类机制：

1. 用户自定义类型：通过 corpus.config JSONB 字段配置 custom_entity_types 和 custom_relation_types
2. 类型继承：自定义类型可标注父类型（如 DISEASE → CONCEPT），确保向后兼容
3. 提取指导：自定义类型附带示例文本，供 LLM 提取时参考

时态属性预备：

为终极阶段的时态建模做准备，在关系属性中预留时间字段：

-- 关系属性扩展（在 AGE 边属性中）
{
    "type": "WORKS_FOR",
    "confidence": 0.95,
    "evidence": "...",
    "valid_from": "2024-01-01",  -- 事实生效时间 (Phase 3)
    "valid_to": null,             -- 事实失效时间 (Phase 3)
    "created_at": "2026-04-08"   -- 系统录入时间
}

#5.2.4 前端可视化层（Cytoscape.js + fCoSE）

理论锚点：Force-directed layout 起源于 Fruchterman & Reingold (1991)；fCoSE (Dogrusoz et al., 2009) 是当前对大规模属性图最优的快速复合 spring embedder。

节点编码：

• 颜色：community_id != null 时按社区配色（Tableau 10 色盲友好），否则按实体类型（person/organization/...）
• 尺寸：18-46px 线性映射 PageRank importance_score，零值兜底为 22px
• 选中态：橙色边框 + 非邻域淡化（opacity=0.15）

fCoSE 默认参数：

性能基准（Chrome 134 / M1）：100-500 节点初始布局 < 2s；5000+ 节点建议服务端 limit=500 截断（默认值），UI 显式提示"已按 importance 截断（双击节点展开邻居）"。

交互范式：

• 滚轮缩放（wheelSensitivity=0.2，避免误触猛缩）
• 拖拽画布平移
• 单击节点 → 高亮 1-hop 邻域 + 父组件展示详情
• 双击节点 → 调用 GET /base/{cid}/graph/subgraph?center=ID&radius=1&limit=50 增量加载
• 点击空白 → 取消选中

渲染引擎切换：保留 d3-force 实现作为兼容回退（顶部 toolbar Cytoscape | d3-force 切换）。

#5.6 数据模型演进

索引优化计划：

性能目标：

#6. 终极阶段设计

#6.1 GraphRAG 实现

以 Microsoft GraphRAG^[4] 为蓝本，结合 LightRAG^[5] 的效率优化：

关键设计决策：

1. 社区检测算法：从 Phase 2 的 Louvain 升级为 Leiden^[15]，Leiden 在保证社区连通性方面更优
2. 社区摘要存储：kg_community_summaries 表，字段包含 community_id, level, summary_text, embedding, entity_count
3. 增量更新策略：新实体加入后仅重新计算受影响社区的摘要（参考 LightRAG^[5] 的 Union 策略）

#6.1.4 Global Search Map-Reduce 流水线（Phase 4 G1 已落地）

模块：graph/global_search.py 引入 GlobalSearchService，与 community_summarizer.py 正交分工 —— 后者负责生成与 embedding 落库，前者负责 query-focused 检索 + Map-Reduce。

流水线：

关键设计：

• Selection（候选筛选）：用 query embedding 在 kg_community_summaries.embedding 上做 cosine 排序，避免对全部摘要做 LLM 调用；若 embedding 列尚未填充（旧数据），降级为按 entity_count DESC 排序，相似度兜底为 0。
• Map 限流：asyncio.Semaphore(5)（默认）防止触达 LLM rate-limit；单 LLM 失败返回空字符串，evidence 列表自动剔除（不阻塞整体）。
• Reduce 预算控制：partial answers 截断为前 20 条防止 token 预算溢出。
• 摘要陈旧检测：每次查询末尾对比 kg_entities.MAX(updated_at) > kg_community_summaries.MIN(updated_at)；若 dirty，response 中 summaries_dirty=true，UI 显式提示用户重跑摘要流程。
• Embedding 写入路径：CommunitySummarizer(embedding_fn=...) 在持久化时同步写 embedding；调用方未注入 embedding_fn 时降级为不写（与 G3 backfill 同向兼容）。

#6.2 时态知识图谱

以 Graphiti^[6] 为蓝本的双时态模型设计：

双时态字段设计：

-- AGE 边属性扩展
{
    "type": "WORKS_FOR",
    "confidence": 0.95,
    -- 事件时间线 (Timeline T): 真实世界事实有效期
    "valid_from": "2024-01-15T00:00:00Z",
    "valid_to": null,  -- null 表示当前有效
    -- 事务时间线 (Timeline T'): 系统记录时间
    "created_at": "2026-04-08T10:30:00Z",
    "expired_at": null, -- null 表示当前记录
    -- 溯源
    "source_episode_id": "uuid-of-source-chunk",
    "evidence": "Sam Altman is the CEO of OpenAI."
}

矛盾检测：当新提取的关系与现有关系冲突时（同一 source-target 对、同一 relation_type 但不同属性），系统自动触发矛盾解决流程：

1. LLM 判断是"更新"还是"矛盾"
2. 若为"更新"：旧边设置 valid_to = now，新边 valid_from = now
3. 若为"矛盾"：两边共存，标记 contradiction_flag = true，等待人工审核

#6.2.3 as-of 查询接口与时间轴（Phase 4 G3 已落地）

单一事实源：所有需要按 valid_from / valid_to 过滤的查询都通过模块级 helper _temporal_where_clause(rel_alias) 构造谓词片段，绑定参数固定为 :as_of。这避免了在 find_neighbors / find_path / hybrid_search / get_graph 中重复散落 4 处时态 SQL，从源头消除"时态语义跨方法漂移"风险。

API 入口：所有图谱读路径接受可选 as_of 参数（ISO-8601）：

索引：迁移 0024_kg_temporal_index_and_summary_embedding.py 给 kg_relations 增加部分索引

CREATE INDEX ix_kg_relations_valid_active
  ON negentropy.kg_relations(corpus_id)
  WHERE valid_to IS NULL AND is_active = true;

加速默认"当前时刻"查询；同时一次性 UPDATE kg_relations SET valid_from = created_at WHERE valid_from IS NULL 让历史关系视为从写入时刻起即生效。

缓存：_graph_cache 的 key 维度从 f"graph:{corpus_id}" 升级为 f"graph:{corpus_id}|as_of={iso}"，as_of=None 显式落入 as_of=now 分桶，确保不同时刻快照不会脏读。invalidate(prefix="graph:{corpus_id}") 仍按前缀匹配清空所有 as_of 变体，无需逐 key 清理。

前端 UI：TimeTravelSlider.tsx 拉取 /graph/timeline 渲染密度直方图 + range slider；用户拖动至历史桶即将 ISO 时刻通过 onChange 回调透传至顶层 as_of 状态，所有面板（图谱、邻居、路径、搜索）共享同一时刻。徽标 as_of: YYYY-MM-DD 在每个面板顶部显式提示当前快照。

#6.3 增量图更新

参考 LightRAG^[5] 的增量更新策略：

实体解析的三层策略（参考 Graphiti^[6]）：

1. 精确匹配：label 完全一致 + 同 corpus_id
2. 模糊匹配：SHA256 哈希前缀匹配（llm_extractors.py 中已有 _generate_entity_id() 使用 SHA256）
3. LLM 语义匹配：当模糊匹配置信度不足时，调用 LLM 判断两个实体是否指代同一对象

#6.4 高级检索模式

双层检索（启发自 LightRAG^[5]）：

多跳推理链：

Query: "A 公司的技术对 B 行业有什么影响？"

1. 实体匹配: A公司 (ORGANIZATION)
2. 1-hop: A公司 --CREATED_BY--> 产品X (PRODUCT)
3. 2-hop: 产品X --RELATED_TO--> B行业 (CONCEPT)
4. 关系路径: A公司 → [CREATED_BY] → 产品X → [RELATED_TO] → B行业
5. 上下文聚合: 产品X 的描述 + A公司与产品X的关系证据 + 产品X与B行业的关系证据
6. LLM 生成: 基于结构化上下文的推理回答

#6.5 Neo4j 评估标准

Apache AGE 的边界在于：

迁移路径：

1. 导出 AGE 图数据为 CSV（COPY (SELECT * FROM cypher(...)) TO ...）
2. Neo4j Admin Import 批量加载
3. 维护 PostgreSQL ↔ Neo4j 的实体 ID 映射
4. 混合部署：PostgreSQL（关系数据 + 向量）+ Neo4j（图遍历 + 算法）

#6.6 Cognee 适配器策略

遵循现有 Strategy Pattern（graph.py 中的 EntityExtractor / RelationExtractor ABC）：

class CogneeAdapter:
    """Cognee ECL Pipeline 适配器

    将 Cognee 的 Extract-Cognify-Load 管道映射到
    Negentropy 的 GraphService 接口。

    遵循 Adapter Pattern [9]。
    """

    async def extract_and_cognify(
        self, corpus_id: UUID, chunks: List[str]
    ) -> KnowledgeGraphPayload:
        """调用 Cognee API 执行实体提取和图构建"""
        # 1. cognee.add(chunks)
        # 2. cognee.cognify()
        # 3. 转换为 KnowledgeGraphPayload (GraphNode[] + GraphEdge[])
        ...

#7. 价值量化体系

#7.1 价值维度

#7.2 测量基础设施

自动化评估管道：

A/B 测试框架：

#7.3 KG 健康指标

实体质量：

图结构健康：

构建管道健康：

#7.4 ROI 计算框架

成本模型：

收益模型：

盈亏平衡点：当 corpus_size > ~500 chunks 且 daily_queries > ~50 时，KG 投入通常在 2-3 个月内回本。

#8. 一核五翼集成架构

#8.1 知识图谱与五翼的交互

#8.2 跨模块协同

#KG × Memory 协同

协同场景：当用户询问"上次我们讨论的那个项目的技术架构"时：

1. Memory 模块通过时间衰减检索最近的讨论情景
2. 从情景中提取"项目名"等实体
3. KG 模块通过实体邻域扩展获取完整技术架构
4. 两者融合提供完整上下文

#KG × Contemplation 协同

坐照系部的"二阶思维"需要宏观洞察——这正是知识图谱社区检测的核心价值：

• 社区摘要 → 领域全景理解（"AI Agent 领域有哪些主要技术流派？"）
• 实体重要性 (PageRank) → 优先关注核心概念
• 关系路径 → 因果推理链（"A 导致 B，B 导致 C，因此 A 间接影响 C"）

#8.3 Pipeline 集成点

#9. 实施路线图

#9.1 时间线总览

#9.2 Phase 2: PostgreSQL 深度集成 (2-4 月)

里程碑：

• M2.1: JSONB → AGE 迁移完成，Cypher 遍历上线
• M2.2: PageRank + 社区检测就绪，支持实体重要性排序
• M2.3: RRF 混合检索上线，价值基线已建立

#9.3 Phase 3: GraphRAG 与高级能力 (4-8 月)

里程碑：

• M3.1: GraphRAG 双层检索上线（Local + Global Search）
• M3.2: 时态关系与增量更新就绪
• M3.3: Neo4j 评估完成，输出迁移决策报告

#9.4 Phase 4: 终极成熟 (8-12 月)

#10. 风险管理与边界控制

#10.1 风险矩阵

#10.2 回滚策略

#10.3 边缘情况处理

#11. 参考文献

[1] A. Hogan, E. Blomqvist, M. Cochez, C. d'Amato, G. de Melo, C. Gutierrez, S. Kirrane, J. E. Labra Gayo, R. Navigli, S. Neumaier, A. Ngonga Ngomo, A. Polleres, S. M. Rashid, A. Rula, L. Schmelzeisen, J. Sequeda, S. Staab, and A. Zimmermann, "Knowledge graphs," ACM Comput. Surv., vol. 54, no. 4, art. 71, Jul. 2021.

[2] S. Ji, S. Pan, E. Cambria, P. Marttinen, and P. S. Yu, "A survey on knowledge graphs: Representation, acquisition, and applications," IEEE Trans. Neural Netw. Learn. Syst., vol. 33, no. 2, pp. 494–514, Feb. 2022.

[3] Z. Sun, Z.-H. Deng, J.-Y. Nie, and J. Tang, "RotatE: Knowledge graph embedding by relational rotation in complex space," in Proc. 7th Int. Conf. Learn. Representations (ICLR), 2019.

[4] D. Edge, H. Trinh, N. Cheng, J. Bradley, A. Chao, A. Mody, S. Truitt, and J. Larson, "From local to global: A graph RAG approach to query-focused summarization," arXiv preprint arXiv:2404.16130, 2024.

[5] Z. Guo, L. Liang, G. Long, C. Lu, H. Xiong, J. Shan, and D. Han, "LightRAG: Simple and fast retrieval-augmented generation," arXiv preprint arXiv:2410.05779, 2024.

[6] P. Tripathi, D. Sullivan, A. Levy, P. Katz, and L. Luo, "Zep: A temporal knowledge graph architecture for agent memory," arXiv preprint arXiv:2501.13956, 2025.

[7] G. V. Cormack, C. L. A. Clarke, and S. Buettcher, "Reciprocal rank fusion outperforms Condorcet and individual rank learning methods," in Proc. SIGIR, pp. 758–759, 2009.

[8] H. Ebbinghaus, "Memory: A contribution to experimental psychology," Teachers College, Columbia University, 1885/1913.

[9] E. Gamma, R. Helm, R. Johnson, and J. Vlissides, "Design Patterns: Elements of Reusable Object-Oriented Software," Addison-Wesley, 1994.

[10] M. Fowler, "Patterns of Enterprise Application Architecture," Addison-Wesley, 2002.

[11] Apache Software Foundation, "Apache AGE: A graph extension for PostgreSQL," 2024. [Online]. Available: https://age.apache.org/

[12] E. Schrödinger, "What is Life? The Physical Aspect of the Living Cell," Cambridge University Press, 1944.

[13] Cognee AI, "Cognee: AI memory engine documentation," 2025. [Online]. Available: https://docs.cognee.ai/

[14] R. Abdalkareem, O. Nourry, S. Wehaibi, S. Mujahid, and E. Shihab, "Application of knowledge graph in software engineering field: A systematic literature review," Inf. Softw. Technol., vol. 162, pp. 107030, Oct. 2023.

[15] V. A. Traag, L. Waltman, and N. J. van Eck, "From Louvain to Leiden: Guaranteeing well-connected communities," Sci. Rep., vol. 9, art. 5233, 2019.

[16] M. T. Nygard, Release It!: Design and Deploy Production-Ready Software, 2nd ed. Pragmatic Bookshelf, 2018.

[17] M. Kleppmann, Designing Data-Intensive Applications: The Big Ideas Behind Reliable, Scalable, and Maintainable Systems. O'Reilly Media, 2017.

[18] C. Majors, L. Fout, and G. Larkby-Lahet, Observability Engineering: Achieving Production Excellence. O'Reilly Media, 2022.

[19] M. Farber, F. Bartscherer, C. Menne, and A. Rettinger, "Linked data quality of DBpedia, Freebase, OpenCyc, Wikidata, and YAGO," Semantic Web, vol. 9, no. 1, pp. 77–129, 2018.

[20] I. P. Fellegi and A. B. Sunter, "A theory for record linkage," J. Amer. Statist. Assoc., vol. 64, no. 328, pp. 1183–1210, 1969.

[21] P. Christen, Data Matching: Concepts and Techniques for Record Linkage, Entity Resolution, and Duplicate Detection. Springer, 2012.

[22] S. Mudgal, H. Li, T. Rekatsinas, A. Doan, Y. Park, G. Krishnan, R. Deep, E. Arcaute, and V. Raghavendra, "Deep learning for entity matching: A design space exploration," in Proc. ACM SIGMOD, pp. 19–34, 2018.

[23] X. L. Dong, E. Gabrilovich, G. Heitz, W. Horn, N. Lao, K. Murphy, T. Strohmann, S. Sun, and W. Zhang, "Knowledge vault: A web-scale approach to probabilistic knowledge fusion," in Proc. 20th ACM SIGKDD, pp. 601–610, 2014.

[24] A. S. Tanenbaum and M. Van Steen, Distributed Systems: Principles and Paradigms, 3rd ed. Pearson, 2017.

#12. 变更日志

文档维护：本文档与代码同步演进。架构变更时需同步更新对应章节，保持代码事实与文档描述的一致性。变更遵循 AGENTS.md 中的 Verification Before Done 定式。