数据模型与模式定义（中文译文）
原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/8-data-models-and-schemas
翻译时间：2026-05-27T08:45:14.900Z
翻译模型：deepseek-chat
原文字符数：10729
项目：Cognee (cognee)
---
数据模型与模式
相关源文件
以下文件用于生成此 Wiki 页面：
cognee/infrastructure/engine/models/DataPoint.pycognee/modules/chunking/models/DocumentChunk.pycognee/modules/engine/models/Entity.pycognee/modules/engine/models/EntityType.pycognee/modules/graph/utils/get_graph_from_model.pycognee/modules/graph/utils/get_model_instance_from_graph.pycognee/modules/pipelines/operations/run_tasks_base.pycognee/modules/pipelines/operations/run_tasks_with_telemetry.pycognee/modules/visualization/cognee_network_visualization.pycognee/shared/CodeGraphEntities.pycognee/tasks/graph/extract_graph_and_summarize.pycognee/tasks/storage/add_data_points.pycognee/tasks/summarization/models.pycognee/tasks/summarization/summarize_text.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/visualization/visualization_test.pyexamples/demos/simple_cognee_example.py
目的与范围
本文档记录了 Cognee 知识引擎中使用的核心数据模型和模式结构。它涵盖了基础的 DataPoint 模型、图实体表示、溯源追踪机制，以及模式在不同存储层（向量数据库、图数据库和关系型数据库）之间的转换方式。
有关配置数据库连接和选择提供者的信息，请参见数据库配置与选择。有关这些模型如何流经处理管线的详细信息，请参见管线任务与执行。有关自定义图模型定义，请参见自定义图模型。
---
DataPoint 基础模型
DataPoint 是 Cognee 中所有数据实体继承的基础 Pydantic 模型。它提供了一个标准化结构，用于表示知识图谱中的节点，并内置了版本控制、溯源追踪和元数据管理支持。
核心字段
classDiagram
class DataPoint {
+UUID id
+int created_at
+int updated_at
+bool ontology_valid
+int version
+int topological_rank
+MetaData metadata
+str type
+List belongs_to_set
+str source_pipeline
+str source_task
+str source_node_set
+str source_user
+str source_content_hash
+float feedback_weight
+get_embeddable_data()
+get_embeddable_properties()
+update_version()
+to_dict()
+from_dict()
}
class MetaData {
+str type
+list index_fields
+list identity_fields
}
DataPoint --> MetaData
标识与确定性
id：默认为uuid4()。如果在metadata中定义了identity_fields，则会通过这些字段的值使用_generate_identity_id()生成一个确定性的uuid5cognee/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中，用于生成确定性 IDcognee/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 实例流经管线时自动为其打上溯源元数据标记。这支持追踪数据血缘、归属关系以及按来源进行可视化。
溯源字段
graph LR
subgraph "溯源链"
Pipeline["source_pipeline<br/>（例如 'cognify_pipeline'）"]
Task["source_task<br/>（例如 'extract_graph_from_data'）"]
NodeSet["source_node_set<br/>（例如 'research_nodes'）"]
User["source_user<br/>（例如 'alice@example.com'）"]
Hash["source_content_hash<br/>（原始数据哈希值）"]
end
Pipeline --> Task
Task --> NodeSet
NodeSet --> User
User --> Hash
DataPoint["DataPoint 实例"] --> Pipeline
自动打标
溯源信息在管线执行期间通过 _stamp_provenance() 应用 cognee/modules/pipelines/operations/run_tasks_base.py:33-85。其过程如下：
- 递归遍历：对主要结果和嵌套的
DataPoint字段进行打标cognee/modules/pipelines/operations/run_tasks_base.py:73-84。 - 循环保护：使用
visited集合通过追踪对象 ID 来防止无限循环cognee/modules/pipelines/operations/run_tasks_base.py:46-49。 - 字段传播：
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 元数据，以构建知识图谱。
graph TD
subgraph "代码实体空间"
DP["DataPoint 模型实例"]
EXT["get_graph_from_model()"]
SM["_simple_model_for()"]
EM["Edge（模型）"]
end
subgraph "自然语言/图空间"
N1["节点（源）"]
N2["节点（目标）"]
REL["关系（边）"]
end
DP --> EXT
EXT --> SM
EXT --> EM
SM --> N1
SM --> N2
EM --> REL
N1 --> REL
REL --> N2
关键行为：
- 动态子类化：
_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
---
三元组嵌入模型
系统使用基于三元组的方法将语义链接表示为可嵌入的单元。这弥合了结构化图数据与向量搜索空间之间的差距。
graph TD
subgraph "代码实体空间：add_data_points.py"
NODES["List[DataPoint]"]
EDGES["List[tuple]"]
TRIP_GEN["_create_triplets_from_graph()"]
TRIP_MOD["Triplet（模型）"]
end
subgraph "向量空间"
IDX["index_data_points()"]
VEC["向量嵌入"]
end
NODES --> TRIP_GEN
EDGES --> TRIP_GEN
TRIP_GEN --> TRIP_MOD
TRIP_MOD --> IDX
IDX --> VEC
三元组通过 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
---
子页面
有关特定模型的更多技术细节，请参考以下内容：