agentic_huge_data_base / wiki
页面 Cognee · 8.1 核心数据模型·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 8.1

8.1 · 核心数据模型（Core Data Models）

记忆管道与知识图谱构建 · 本章是 Cognee DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Cognee 章节8.1 状态全文译文 模块图谱与关系、文档对象与元数据、测试、发布与运维、评测、反馈与人工复核
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Core Data Models 上一章8 下一章8.2
源码线索
  • cognee/infrastructure/engine/__init__.py
  • cognee/infrastructure/engine/models/DataPoint.py
  • cognee/infrastructure/engine/models/Edge.py
  • cognee/infrastructure/engine/models/FieldAnnotations.py
  • cognee/modules/chunking/models/DocumentChunk.py
  • cognee/modules/engine/models/Entity.py
  • cognee/modules/engine/models/EntityType.py
  • cognee/modules/pipelines/operations/run_tasks_base.py
  • cognee/modules/pipelines/operations/run_tasks_with_telemetry.py
  • cognee/modules/storage/utils/__init__.py
模块标签
  • 图谱与关系
  • 文档对象与元数据
  • 测试、发布与运维
  • 评测、反馈与人工复核
  • 入库与解析

中文译文

核心数据模型（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/8.1-core-data-models
翻译时间：2026-05-27T08:45:14.536Z
翻译模型：deepseek-chat
原文字符数：10707
项目：Cognee (cognee)

---

核心数据模型

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • cognee/infrastructure/engine/__init__.py
  • cognee/infrastructure/engine/models/DataPoint.py
  • cognee/infrastructure/engine/models/Edge.py
  • cognee/infrastructure/engine/models/FieldAnnotations.py
  • cognee/modules/chunking/models/DocumentChunk.py
  • cognee/modules/engine/models/Entity.py
  • cognee/modules/engine/models/EntityType.py
  • cognee/modules/pipelines/operations/run_tasks_base.py
  • cognee/modules/pipelines/operations/run_tasks_with_telemetry.py
  • cognee/modules/storage/utils/__init__.py
  • cognee/modules/visualization/cognee_network_visualization.py
  • cognee/shared/CodeGraphEntities.py
  • cognee/tasks/summarization/models.py
  • cognee/tests/test_edge_ingestion.py
  • cognee/tests/unit/modules/visualization/visualization_test.py
  • cognee/tests/utils/extract_entities.py
  • cognee/tests/utils/extract_relationships.py

本文档描述了 Cognee 架构中使用的基础数据模型。这些模型定义了数据在入库、处理、存储和检索系统中的结构。

概述

Cognee 的数据模型分为三层：

层级用途技术
基础模型所有数据实体的基类，包含元数据和版本控制Pydantic v2
关系模型用户数据、数据集和文件追踪SQLAlchemy ORM
领域模型专门化的知识结构（片段、摘要、实体）DataPoint 子类

所有模型根据持久化需求，继承自 Pydantic 的 BaseModel 或 SQLAlchemy 的 Base 类。

来源： cognee/infrastructure/engine/models/DataPoint.py:27-40, cognee/modules/data/models/Data.py:1

DataPoint：基础数据模型

DataPoint 类是 Cognee 中所有知识实体的基础模型。它扩展了 Pydantic 的 BaseModel，提供结构化数据校验、元数据支持和确定性标识。

DataPoint 类结构
classDiagram
    class DataPoint {
        +UUID id
        +int created_at
        +int updated_at
        +int version
        +str type
        +MetaData metadata
        +str source_pipeline
        +str source_task
        +str source_node_set
        +str source_user
        +str source_content_hash
        +float feedback_weight
        +float importance_weight
        +__init__(**data)
        +update_version()
        +get_embeddable_data()
    }

    class MetaData {
        <<TypedDict>>
        +str type
        +list[str] index_fields
        +list[str] identity_fields
    }

    DataPoint *-- MetaData

核心字段：

  • id: UUID - 唯一标识符。如果未提供，则通过 uuid4() 自动生成，或者如果定义了 identity 字段，则通过 uuid5() 确定性生成 cognee/infrastructure/engine/models/DataPoint.py:44-46, cognee/infrastructure/engine/models/DataPoint.py:71-76。
  • version: int - 递增的版本追踪（默认值：1）cognee/infrastructure/engine/models/DataPoint.py:52。
  • metadata: MetaData - 包含 index_fields（用于向量搜索）和 identity_fields（用于去重）cognee/infrastructure/engine/models/DataPoint.py:54。
  • type: str - 在初始化时自动设置为类名 cognee/infrastructure/engine/models/DataPoint.py:68。
  • feedback_weight: float - 用于根据用户交互调整检索相关性（默认值：0.5）cognee/infrastructure/engine/models/DataPoint.py:62。
  • importance_weight: float - 数据点的优先级分数（默认值：0.5）cognee/infrastructure/engine/models/DataPoint.py:63。

来源： cognee/infrastructure/engine/models/DataPoint.py:27-65

确定性标识与去重

Cognee 使用 uuid5 基于特定字段生成确定性 ID。这使得系统能够识别同一实体被多次入库的情况。

  • 标识生成： _generate_identity_id 方法将 identity_fields 中列出的字段值用管道符（|）连接，并使用 NAMESPACE_OID 进行哈希处理 cognee/infrastructure/engine/models/DataPoint.py:105-131。
  • 自动推导： 在子类字段上使用 Annotated[str, Dedup()] 会通过 __pydantic_init_subclass__ 自动将 identity_fields 填充到模型的元数据中 cognee/infrastructure/engine/models/DataPoint.py:134-162。

来源： cognee/infrastructure/engine/models/DataPoint.py:105-162

溯源追踪

Cognee 通过溯源字段追踪每个 DataPoint 的来源。这些字段在管线执行期间通过管线编排器中的 _stamp_provenance 函数进行填充。

字段描述
source_pipeline生成数据的管线名称 cognee/infrastructure/engine/models/DataPoint.py:57。
source_task创建对象的特定任务/函数名称 cognee/infrastructure/engine/models/DataPoint.py:58。
source_node_set用于对节点进行分组的标签（通常是数据集名称）cognee/infrastructure/engine/models/DataPoint.py:59。
source_user发起流程的用户的电子邮件或 ID cognee/infrastructure/engine/models/DataPoint.py:60。
source_content_hash原始源文档的哈希值 cognee/infrastructure/engine/models/DataPoint.py:61。

来源： cognee/infrastructure/engine/models/DataPoint.py:57-61, cognee/modules/pipelines/operations/run_tasks_base.py:33-84

生命周期与数据流

管线中的溯源标记

当 Task 在管线中执行时，Cognee 会递归地为所有生成的 DataPoint 对象标记溯源信息。这确保了即使是嵌套对象也携带其创建上下文。_stamp_provenance 中的 visited 集合可以防止重复处理和图中的无限循环 cognee/modules/pipelines/operations/run_tasks_base.py:46-49。

sequenceDiagram
    participant Orchestrator as "run_tasks_base.py"
    participant Task as "Task.execute()"
    participant Stamp as "_stamp_provenance()"
    participant DP as "DataPoint 实例"

    Orchestrator->>Task: "execute(args)"
    Task-->>Orchestrator: "yield result_data"
    Orchestrator->>Stamp: "传递 result_data, pipe_name, task_name"
    loop "对 result 中的每个 DataPoint"
        Stamp->>DP: "设置 source_pipeline"
        Stamp->>DP: "设置 source_task"
        Stamp->>DP: "设置 source_user"
        Stamp->>DP: "设置 source_node_set"
        Stamp->>Stamp: "递归处理 model_fields"
    end

来源： cognee/modules/pipelines/operations/run_tasks_base.py:166-180, cognee/modules/pipelines/operations/run_tasks_base.py:33-84

DataPoint 到可视化

溯源数据直接用于可视化层，对知识图谱进行颜色编码。cognee_network_visualization 函数会为这些字段生成确定性颜色映射，以提供可视化谱系 cognee/modules/visualization/cognee_network_visualization.py:11-19。

graph TD
    subgraph "自然语言空间"
        User["用户身份"]
        TaskName["任务上下文"]
    end

    subgraph "代码实体空间"
        CV["cognee_network_visualization.py"]
        PC["_generate_provenance_colors()"]
        DP["DataPoint.source_user"]
        DT["DataPoint.source_task"]
    end

    User --> DP
    TaskName --> DT
    DP --> CV
    DT --> CV
    CV --> PC
    PC -->|"确定性十六进制颜色"| Result["图节点颜色"]

来源： cognee/modules/visualization/cognee_network_visualization.py:85-88, cognee/tests/unit/modules/visualization/visualization_test.py:79-91

领域特定模型

知识图谱与语义实体

Cognee 提供了专门化的语义知识表示模型，所有模型都继承自 DataPoint。

  • Entity： 表示一个真实世界的对象或概念，包含 name、description 和可选的 EntityType cognee/modules/engine/models/Entity.py:7-13。
  • DocumentChunk： 表示文本的一个片段，包含 chunk_index、chunk_size 以及所属的源 Document cognee/modules/chunking/models/DocumentChunk.py:10-38。
  • TextSummary： 从 DocumentChunk 派生出的摘要，包含摘要文本 cognee/tasks/summarization/models.py:9-25。
代码工程模型

对于代码分析，Cognee 使用专门化的模型来表示编程结构：

  • CodeFile： 表示一个源文件，包含 language、source_code 以及与函数/类的关系 cognee/shared/CodeGraphEntities.py:35-44。
  • FunctionDefinition / ClassDefinition： 捕获特定的代码块，包含 start_point 和 end_point 坐标 cognee/shared/CodeGraphEntities.py:17-32。

来源： cognee/modules/engine/models/Entity.py:7-13, cognee/modules/chunking/models/DocumentChunk.py:10-38, cognee/shared/CodeGraphEntities.py:1-62

关系模型与上下文

虽然 DataPoint 模型用于知识图谱和向量搜索，但标准的 SQLAlchemy 模型和上下文对象负责处理系统状态。

  • User： 表示系统用户，为 source_user 溯源提供 user_label（电子邮件或 ID）cognee/modules/pipelines/operations/run_tasks_base.py:161。
  • PipelineContext： 存储活动管线运行的状态，包括 _provenance_visited 集合，以确保跨多个任务的一致标记 cognee/modules/pipelines/operations/run_tasks_base.py:164。

来源： cognee/modules/pipelines/operations/run_tasks_base.py:123-129, cognee/modules/pipelines/operations/run_tasks_base.py:164