8.2 · Graph 实体与关系（Graph Entities and Relationships）

Graph 实体与关系（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/8.2-graph-entities-and-relationships

翻译时间：2026-05-27T08:45:21.032Z

翻译模型：deepseek-chat

原文字符数：13208

项目：Cognee (cognee)

---

图谱实体与关系

相关源文件

以下文件用于生成此 Wiki 页面：

• cognee/modules/graph/cognee_graph/CogneeAbstractGraph.py
• cognee/modules/graph/cognee_graph/CogneeGraph.py
• cognee/modules/graph/cognee_graph/CogneeGraphElements.py
• cognee/modules/graph/cognee_graph/__init__.py
• cognee/modules/graph/exceptions/__init__.py
• cognee/modules/graph/exceptions/exceptions.py
• cognee/modules/graph/methods/sanitize_relational_payload.py
• cognee/modules/graph/methods/upsert_edges.py
• cognee/modules/graph/methods/upsert_nodes.py
• cognee/modules/graph/models/Edge.py
• cognee/modules/graph/models/Node.py
• cognee/modules/graph/utils/get_graph_from_model.py
• cognee/modules/graph/utils/get_model_instance_from_graph.py
• cognee/modules/retrieval/utils/brute_force_triplet_search.py
• cognee/modules/retrieval/utils/node_edge_vector_search.py
• cognee/modules/users/methods/get_authenticated_user.py
• cognee/tasks/graph/extract_graph_and_summarize.py
• cognee/tasks/storage/add_data_points.py
• cognee/tasks/summarization/summarize_text.py
• cognee/tests/test_search_db.py
• cognee/tests/unit/api/v1/__init__.py
• cognee/tests/unit/api/v1/config/__init__.py
• cognee/tests/unit/api/v1/config/test_config_set_method.py
• cognee/tests/unit/modules/graph/cognee_graph_elements_test.py
• cognee/tests/unit/modules/graph/cognee_graph_test.py
• cognee/tests/unit/modules/graph/test_relational_upserts.py
• cognee/tests/unit/modules/retrieval/test_node_edge_vector_search.py
• cognee/tests/unit/modules/users/test_conditional_authentication.py
• examples/demos/simple_cognee_example.py

本文档介绍了 Cognee 的图谱表示系统，具体包括 Node、Edge 和 CogneeGraph 类，以及从 Pydantic 模型和持久化存储中提取这些结构的机制。这些类提供了 Python 原生的抽象层，用于在知识图谱从底层图数据库投影后对其进行操作。

架构总览

图谱系统由核心元素模型、用于内存操作的图谱容器以及用于模型提取和整合的工具函数组成。

图表：内存图谱类层次结构

classDiagram
    class CogneeAbstractGraph {
        <<abstract>>
        +add_node(node: Node) void
        +add_edge(edge: Edge) void
        +get_node(node_id: str) Node
        +get_edges(node_id: str) List~Edge~
        +project_graph_from_db(adapter: GraphDBInterface) void
    }

    class CogneeGraph {
        +Dict~str,Node~ nodes
        +List~Edge~ edges
        +Dict~str, List~Edge~~ edges_by_distance_key
        +bool directed
        +add_node(node: Node) void
        +add_edge(edge: Edge) void
        +get_node(node_id: str) Node
        +get_edges_from_node(node_id: str) List~Edge~
        +reset_distances(collection, query_count) void
    }

    class Node {
        +str id
        +Dict~str,Any~ attributes
        +List~Node~ skeleton_neighbours
        +List~Edge~ skeleton_edges
        +ndarray status
        +add_skeleton_neighbor(neighbor: Node) void
        +add_skeleton_edge(edge: Edge) void
        +is_node_alive_in_dimension(dimension: int) bool
    }

    class Edge {
        +Node node1
        +Node node2
        +Dict~str,Any~ attributes
        +bool directed
        +ndarray status
        +get_distance_key() str
        +update_distance_for_query(query_index, score) void
    }

    CogneeAbstractGraph <|-- CogneeGraph : implements
    CogneeGraph "1" *-- "many" Node : contains
    CogneeGraph "1" *-- "many" Edge : contains
    Edge "1" --> "2" Node : connects
    Node "1" --> "many" Edge : skeleton_edges
    Node "1" --> "many" Node : skeleton_neighbours

来源：cognee/modules/graph/cognee_graph/CogneeAbstractGraph.py:7-39、cognee/modules/graph/cognee_graph/CogneeGraph.py:18-39、cognee/modules/graph/cognee_graph/CogneeGraphElements.py:7-150

Node 类

Node 类表示知识图谱中的一个顶点。每个节点都有一个唯一标识符、一个属性字典，并维护与其邻居节点和连接边的双向引用。

Node 结构

属性	类型	描述
id	str	节点的唯一标识符
attributes	Dict[str, Any]	任意键值属性（名称、描述、类型等）
skeleton_neighbours	List[Node]	通过边直接连接的邻居节点
skeleton_edges	List[Edge]	连接到该节点的所有边
status	np.ndarray	用于维度过滤的多维存活/死亡状态

来源：cognee/modules/graph/cognee_graph/CogneeGraphElements.py:7-22

Node 初始化

节点使用必需的 ID 和可选的属性进行初始化。属性字典中会自动初始化一个值为 None 的 vector_distance 键。

node = Node(
    node_id="entity-123",
    attributes={"name": "Alice", "type": "Person"},
    dimension=1
)

来源：cognee/modules/graph/cognee_graph/CogneeGraphElements.py:24-41

Node 方法

方法	用途
add_skeleton_neighbor(neighbor: Node)	将邻居节点添加到邻接列表 cognee/modules/graph/cognee_graph/CogneeGraphElements.py:77-79
add_skeleton_edge(edge: Edge)	添加边并自动更新邻居节点 cognee/modules/graph/cognee_graph/CogneeGraphElements.py:85-91
reset_vector_distances(query_count, penalty)	将 vector_distance 属性重置为惩罚值列表 cognee/modules/graph/cognee_graph/CogneeGraphElements.py:57-58
is_node_alive_in_dimension(dimension)	检查节点在特定维度中是否活跃 cognee/modules/graph/cognee_graph/CogneeGraphElements.py:101-104

Edge 类

Edge 类表示两个节点之间的连接。边携带自己的属性，通常包括关系类型和元数据。

Edge 结构

属性	类型	描述
node1	Node	源节点
node2	Node	目标节点
attributes	Dict[str, Any]	边属性（关系类型、权重等）
directed	bool	边是否有方向（默认值：True）
status	np.ndarray	多维存活/死亡状态

来源：cognee/modules/graph/cognee_graph/CogneeGraphElements.py:134-149

边距离键

边实现了 get_distance_key() 方法，该方法从属性中检索 edge_type_id。CogneeGraph 使用此键将边分组以进行距离映射。

来源：cognee/modules/graph/cognee_graph/CogneeGraphElements.py:180-184

CogneeGraph 类

CogneeGraph 类是内存中图谱结构的主要容器。它管理节点和边的集合，并提供用于距离重置和图谱投影的方法。

基本图谱操作

通过 add_edge() 添加边时，图谱会自动根据关系文本生成 edge_type_id，并将该边注册到两个连接的节点中。

graph = CogneeGraph(directed=True)
graph.add_node(node_a)
graph.add_edge(Edge(node_a, node_b, attributes={"relationship_type": "KNOWS"}))

来源：cognee/modules/graph/cognee_graph/CogneeGraph.py:41-65

图谱提取与集成

Cognee 使用 get_graph_from_model 将 Pydantic DataPoint 实例转换为图谱结构（节点和边）。该函数会递归遍历模型字段。

图表：DataPoint 到图谱的提取

flowchart LR
    subgraph "自然语言 / Pydantic 空间"
        DP["DataPoint 模型实例"]
        Fields["模型字段：<br/>name, description,<br/>belongs_to_set"]
    end

    subgraph "代码实体空间"
        Extract["get_graph_from_model()"]
        FieldData["_extract_field_data()"]
        EdgeProps["_create_edge_properties()"]
    end

    subgraph "图谱空间"
        Nodes["List[DataPoint]"]
        Edges["List[Tuple[src, tgt, rel, props]]"]
    end

    DP --> Extract
    Extract --> FieldData
    FieldData --> EdgeProps
    EdgeProps --> Edges
    Extract --> Nodes

来源：cognee/modules/graph/utils/get_graph_from_model.py:178-210、cognee/modules/graph/utils/get_graph_from_model.py:49-92

提取逻辑

1. 字段分类：分析字段以确定它们是常规属性还是关系（包含其他 DataPoint 对象）cognee/modules/graph/utils/get_graph_from_model.py:135-160。
2. 关系处理：如果字段包含 DataPoint 或 DataPoint 列表，则通过 _extract_field_data 创建一条边 cognee/modules/graph/utils/get_graph_from_model.py:49-73。
3. 元数据处理：如果在包含 DataPoint 的元组中找到了 Edge 元数据对象，则将其属性（如权重）合并到图谱边的属性中 cognee/modules/graph/utils/get_graph_from_model.py:95-116。

数据库存储与索引

图谱实体通过 add_data_points 任务进行持久化。该任务负责协调提取、去重和数据库插入。

图表：存储流程

flowchart TD
    subgraph "输入"
        DPs["List[DataPoint]"]
    end

    subgraph "处理"
        Extract["get_graph_from_model()"]
        Dedup["deduplicate_nodes_and_edges()"]
    end

    subgraph "存储"
        GE["graph_engine (add_nodes/add_edges)"]
        VE["vector_engine (index_data_points)"]
        Upsert["upsert_nodes/upsert_edges (Relational)"]
    end

    DPs --> Extract
    Extract --> Dedup
    Dedup --> GE
    Dedup --> VE
    Dedup --> Upsert

来源：cognee/tasks/storage/add_data_points.py:30-45、cognee/tasks/storage/add_data_points.py:62-78、cognee/tasks/storage/add_data_points.py:82-113

存储细节

• 图谱引擎：存储结构关系（三元组）。如果启用了混合写入，则使用 add_nodes_with_vectors cognee/tasks/storage/add_data_points.py:87-96。
• 向量引擎：为语义搜索索引节点和边的文本。如果启用了 embed_triplets，则包括从图谱结构创建的 Triplet 对象 cognee/tasks/storage/add_data_points.py:143-147。
• 关系引擎：通过 upsert_nodes 和 upsert_edges 跟踪每个图谱元素的元数据、所有权和来源 cognee/tasks/storage/add_data_points.py:98-112。

关键方法总结

组件	函数/方法	用途
提取	get_graph_from_model	将 Pydantic 模型转换为（节点，边）元组 cognee/modules/graph/utils/get_graph_from_model.py:178-183
编排	add_data_points	负责提取、去重和保存图谱数据的任务 cognee/tasks/storage/add_data_points.py:30-45
内存	project_graph_from_db	从数据库适配器加载图谱数据到 CogneeGraph cognee/modules/graph/cognee_graph/CogneeGraph.py:218-232
检索	get_memory_fragment	为检索上下文投影特定的子图谱 cognee/modules/retrieval/utils/brute_force_triplet_search.py:49-61

来源：cognee/modules/graph/utils/get_graph_from_model.py:178-210、cognee/tasks/storage/add_data_points.py:30-45、cognee/modules/graph/cognee_graph/CogneeGraph.py:218-232、cognee/modules/retrieval/utils/brute_force_triplet_search.py:49-116