图谱实体与关系
图谱实体与关系
相关源文件
本章引用的主要源码文件：
cognee/modules/graph/cognee_graph/CogneeAbstractGraph.pycognee/modules/graph/cognee_graph/CogneeGraph.pycognee/modules/graph/cognee_graph/CogneeGraphElements.pycognee/modules/graph/cognee_graph/__init__.pycognee/modules/graph/exceptions/__init__.pycognee/modules/graph/exceptions/exceptions.pycognee/modules/graph/methods/sanitize_relational_payload.pycognee/modules/graph/methods/upsert_edges.pycognee/modules/graph/methods/upsert_nodes.pycognee/modules/graph/models/Edge.pycognee/modules/graph/models/Node.pycognee/modules/graph/utils/get_graph_from_model.pycognee/modules/graph/utils/get_model_instance_from_graph.pycognee/modules/retrieval/utils/brute_force_triplet_search.pycognee/modules/retrieval/utils/node_edge_vector_search.pycognee/modules/users/methods/get_authenticated_user.pycognee/tasks/graph/extract_graph_and_summarize.pycognee/tasks/storage/add_data_points.pycognee/tasks/summarization/summarize_text.pycognee/tests/test_search_db.pycognee/tests/unit/api/v1/__init__.pycognee/tests/unit/api/v1/config/__init__.pycognee/tests/unit/api/v1/config/test_config_set_method.pycognee/tests/unit/modules/graph/cognee_graph_elements_test.pycognee/tests/unit/modules/graph/cognee_graph_test.pycognee/tests/unit/modules/graph/test_relational_upserts.pycognee/tests/unit/modules/retrieval/test_node_edge_vector_search.pycognee/tests/unit/modules/users/test_conditional_authentication.pyexamples/demos/simple_cognee_example.py
本文档介绍了 Cognee 的图谱表示系统，具体包括 Node、Edge 和 CogneeGraph 类，以及从 Pydantic 模型和持久化存储中提取这些结构的机制。这些类提供了 Python 原生的抽象层，用于在知识图谱从底层图数据库投影后对其进行操作。
架构总览
图谱系统由核心元素模型、用于内存操作的图谱容器以及用于模型提取和整合的工具函数组成。
图表：内存图谱类层次结构
来源：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 到图谱的提取
来源：cognee/modules/graph/utils/get_graph_from_model.py:178-210、cognee/modules/graph/utils/get_graph_from_model.py:49-92
提取逻辑
- 字段分类：分析字段以确定它们是常规属性还是关系（包含其他
DataPoint对象）cognee/modules/graph/utils/get_graph_from_model.py:135-160。 - 关系处理：如果字段包含
DataPoint或DataPoint列表，则通过_extract_field_data创建一条边cognee/modules/graph/utils/get_graph_from_model.py:49-73。 - 元数据处理：如果在包含
DataPoint的元组中找到了Edge元数据对象，则将其属性（如权重）合并到图谱边的属性中cognee/modules/graph/utils/get_graph_from_model.py:95-116。
数据库存储与索引
图谱实体通过 add_data_points 任务进行持久化。该任务负责协调提取、去重和数据库插入。
图表：存储流程
来源：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_vectorscognee/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