agentic_huge_data_base / wiki
页面 Cognee · 8 数据模型与模式定义·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 8

8 · 数据模型与模式定义（Data Models and Schemas）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节8 状态全文译文 模块图谱与关系、文档对象与元数据、测试、发布与运维、检索、召回与索引
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Data Models and Schemas 上一章7.3 下一章8.1
源码线索
  • cognee/infrastructure/engine/models/DataPoint.py
  • cognee/modules/chunking/models/DocumentChunk.py
  • cognee/modules/engine/models/Entity.py
  • cognee/modules/engine/models/EntityType.py
  • cognee/modules/graph/utils/get_graph_from_model.py
  • cognee/modules/graph/utils/get_model_instance_from_graph.py
  • cognee/modules/pipelines/operations/run_tasks_base.py
  • cognee/modules/pipelines/operations/run_tasks_with_telemetry.py
  • cognee/modules/visualization/cognee_network_visualization.py
  • cognee/shared/CodeGraphEntities.py
模块标签
  • 图谱与关系
  • 文档对象与元数据
  • 测试、发布与运维
  • 检索、召回与索引
  • 入库与解析

章节正文

数据模型与模式定义

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/8-data-models-and-schemas

数据模型与模式

相关源文件

本章引用的主要源码文件：

  • cognee/infrastructure/engine/models/DataPoint.py
  • cognee/modules/chunking/models/DocumentChunk.py
  • cognee/modules/engine/models/Entity.py
  • cognee/modules/engine/models/EntityType.py
  • cognee/modules/graph/utils/get_graph_from_model.py
  • cognee/modules/graph/utils/get_model_instance_from_graph.py
  • cognee/modules/pipelines/operations/run_tasks_base.py
  • cognee/modules/pipelines/operations/run_tasks_with_telemetry.py
  • cognee/modules/visualization/cognee_network_visualization.py
  • cognee/shared/CodeGraphEntities.py
  • cognee/tasks/graph/extract_graph_and_summarize.py
  • cognee/tasks/storage/add_data_points.py
  • cognee/tasks/summarization/models.py
  • cognee/tasks/summarization/summarize_text.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/visualization/visualization_test.py
  • examples/demos/simple_cognee_example.py

目的与范围

本文档记录了 Cognee 知识引擎中使用的核心数据模型和模式结构。它涵盖了基础的 DataPoint 模型、图实体表示、溯源追踪机制，以及模式在不同存储层（向量数据库、图数据库和关系型数据库）之间的转换方式。

有关配置数据库连接和选择提供者的信息，请参见数据库配置与选择。有关这些模型如何流经处理管线的详细信息，请参见管线任务与执行。有关自定义图模型定义，请参见自定义图模型。

DataPoint 基础模型

DataPoint 是 Cognee 中所有数据实体继承的基础 Pydantic 模型。它提供了一个标准化结构，用于表示知识图谱中的节点，并内置了版本控制、溯源追踪和元数据管理支持。

核心字段
Cognee · 核心字段 · 图 1
Cognee · 核心字段 · 图 1

标识与确定性

  • id：默认为 uuid4()。如果在 metadata 中定义了 identity_fields，则会通过这些字段的值使用 _generate_identity_id() 生成一个确定性的 uuid5 cognee/infrastructure/engine/models/DataPoint.py:105-131。
  • created_at / updated_at：创建和修改时设置的 Unix 时间戳（毫秒级）cognee/infrastructure/engine/models/DataPoint.py:45-50。

字段注解 Cognee 使用 Annotated 标记来自动推导元数据：

  • _Embeddable()：将字段添加到 index_fields 中，用于向量搜索 cognee/infrastructure/engine/models/DataPoint.py:153-154。
  • _Dedup()：将字段添加到 identity_fields 中，用于生成确定性 ID cognee/infrastructure/engine/models/DataPoint.py:155-156。

来源：cognee/infrastructure/engine/models/DataPoint.py:27-162，cognee/infrastructure/engine/models/FieldAnnotations.py:1-15

溯源与血缘追踪

Cognee 会在所有 DataPoint 实例流经管线时自动为其打上溯源元数据标记。这支持追踪数据血缘、归属关系以及按来源进行可视化。

溯源字段
Cognee · 溯源字段 · 图 2
Cognee · 溯源字段 · 图 2
自动打标

溯源信息在管线执行期间通过 _stamp_provenance() 应用 cognee/modules/pipelines/operations/run_tasks_base.py:33-85。其过程如下：

  1. 递归遍历：对主要结果和嵌套的 DataPoint 字段进行打标 cognee/modules/pipelines/operations/run_tasks_base.py:73-84。
  2. 循环保护：使用 visited 集合通过追踪对象 ID 来防止无限循环 cognee/modules/pipelines/operations/run_tasks_base.py:46-49。
  3. 字段传播：source_node_set 和 source_content_hash 从输入参数中提取，并传播到所有输出数据点 cognee/modules/pipelines/operations/run_tasks_base.py:159-180。

来源：cognee/modules/pipelines/operations/run_tasks_base.py:33-180，cognee/modules/pipelines/operations/run_pipeline.py:1-25

图实体模型

知识使用结构化的 Pydantic 模型表示，这些模型通过提取工具转换为图节点和边。

模型到图的提取

系统使用 get_graph_from_model.py 将 DataPoint 层次结构投影到图结构中。该工具遍历模型字段，识别嵌套的 DataPoint 实例或 Edge 元数据，以构建知识图谱。

Cognee · 模型到图的提取 · 图 3
Cognee · 模型到图的提取 · 图 3

关键行为：

  • 动态子类化：_simple_model_for 创建带记忆功能的 Pydantic 子类，以处理特定的节点形状，同时避免内存泄漏 cognee/modules/graph/utils/get_graph_from_model.py:28-46。
  • 边元数据：关系可以通过 Edge 模型包含权重和自定义属性 cognee/modules/graph/utils/get_graph_from_model.py:95-116。
  • 重构：get_model_instance_from_graph 执行逆操作，从扁平化的图节点和边重新组装完整的 Pydantic 模型层次结构 cognee/modules/graph/utils/get_model_instance_from_graph.py:68-132。

来源：cognee/modules/graph/utils/get_graph_from_model.py:1-183，cognee/modules/graph/utils/get_model_instance_from_graph.py:9-132，cognee/infrastructure/engine/models/Edge.py:1-25

三元组嵌入模型

系统使用基于三元组的方法将语义链接表示为可嵌入的单元。这弥合了结构化图数据与向量搜索空间之间的差距。

Cognee · 三元组嵌入模型 · 图 4
Cognee · 三元组嵌入模型 · 图 4

三元组通过 brute_force_triplet_search.py 进行处理以用于搜索。它将源节点、关系和目标节点格式化为人类可读的字符串，用于向量嵌入。这使得系统能够执行"关系感知"搜索，查询可以匹配整个图边的语义上下文 cognee/tasks/storage/add_data_points.py:184-205。

来源：cognee/tasks/storage/add_data_points.py:143-205，cognee/modules/engine/models/Triplet.py:1-15

关系型模式

Cognee 使用关系型数据库来管理系统状态、用户数据和文档元数据。

模型用途
User存储用户身份、电子邮件和用于多租户的 tenant_id cognee/modules/users/models.py:1-15。
Data已入库文件的元数据（名称、扩展名、content_hash）cognee/modules/data/models/Data.py:1-20。
DocumentChunk表示文本片段，包含大小、索引和与父文档的关系 cognee/modules/chunking/models/DocumentChunk.py:10-38。
TextSummary封装由大语言模型（LLM）生成的 DocumentChunk 实例摘要 cognee/tasks/summarization/models.py:9-25。
Entity核心图节点模型，包含名称、类型和描述 cognee/modules/engine/models/Entity.py:7-13。

来源：cognee/modules/data/models/Data.py:1-20，cognee/modules/chunking/models/DocumentChunk.py:10-38，cognee/tasks/summarization/models.py:9-54，cognee/modules/engine/models/Entity.py:7-13

子页面

有关特定模型的更多技术细节，请参考以下内容：

  • 核心数据模型 — 详细的 DataPoint 生命周期、元数据索引和 Pydantic 配置。
  • 图实体与关系 — Node 和 Edge 实现、来自数据库适配器的图投影以及遍历逻辑。
  • 三元组嵌入模型 — 图边如何转换为可向量搜索的三元组，并在检索过程中进行评分。
  • 关系型模式 — 通过 SQLAlchemy 进行用户、租户和数据集管理的 SQL 模式。