1.3 · 系统架构总览（System Architecture Overview）

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

项目Cognee 章节1.3 状态全文译文模块系统架构、界面与交互、配置治理、存储与持久化

项目要点页2.5 参考项目项目章节目录Cognee DeepWiki 原始章节System Architecture Overview 上一章1.2 下一章2

源码线索

.env.template
README.md
assets/cognee_benefits.png
cognee/api/v1/add/add.py
cognee/api/v1/cognify/cognify.py
cognee/api/v1/config/config.py
cognee/base_config.py
cognee/context_global_variables.py
cognee/infrastructure/databases/graph/config.py
cognee/infrastructure/databases/graph/get_graph_engine.py

模块标签

系统架构
界面与交互
配置治理
存储与持久化
工作流与编排

中文译文

系统架构总览（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/1.3-system-architecture-overview

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

翻译模型：deepseek-chat

原文字符数：12851

项目：Cognee (cognee)

---

系统架构总览

目的与范围

本文档提供了 Cognee 系统设计的高层架构总览，重点介绍核心组件、数据流模式以及支撑知识引擎运行的多租户机制。内容涵盖主要子系统，包括用户界面、数据处理管线、三数据库架构以及可观测性特性。

Cognee 被设计为一个模块化知识引擎，它将原始数据转换为结构化的语义层，结合向量嵌入向量与关系图谱，以增强 AI 智能体的上下文和记忆能力。

来源： pyproject.toml:5-5、cognee/api/v1/add/add.py:115-126、cognee/api/v1/cognify/cognify.py:63-66

---

核心架构原则

Cognee 建立在三个基础原则之上：

三数据库设计

系统维护三种独立的数据库类型，每种类型针对特定的查询模式进行了优化：

数据库类型	用途	主要使用场景	默认提供者
向量数据库	语义相似性搜索	基于嵌入向量的检索	LanceDB
图数据库	关系遍历	实体连接、图谱查询	Kuzu
关系型数据库	元数据与用户管理	数据集追踪、认证	SQLite/PostgreSQL

这种分离使得每个数据库可以针对其特定的访问模式进行优化，同时通过 DataPoint 抽象层保持数据一致性。

来源： cognee/infrastructure/databases/vector/create_vector_engine.py:151-171、cognee/infrastructure/databases/graph/get_graph_engine.py:115-131、.env.template:120-134、.env.template:155-157

基于 ContextVar 的隔离

Cognee 使用 Python 的 contextvars 模块来实现每个请求、每个任务和每个线程的数据库配置。这使得多个并发操作可以使用不同的数据库实例，而不会产生全局状态冲突。工厂函数 get_graph_context_config() 和 get_vectordb_context_config()（在数据库引擎工厂内部调用）从活动上下文中检索这些覆盖配置。

来源： cognee/context_global_variables.py:25-27、cognee/infrastructure/databases/graph/get_graph_engine.py:107-112、cognee/context_global_variables.py:108-154

管线驱动的处理

所有数据转换都通过基于任务的管线系统进行。run_pipeline() 函数协调任务执行，包括分类、片段切分和图谱提取。Cognee 支持后台执行和增量加载，以高效管理资源密集型操作。

来源： cognee/api/v1/cognify/cognify.py:12-13、cognee/api/v1/cognify/cognify.py:82-89、cognee/api/v1/cognify/cognify.py:115-118

---

系统组件总览

组件架构与代码实体

graph TB
    subgraph "用户界面"
        CLI["cognee-cli<br/>(cognee.cli._cognee:main)"]
        FastAPI["FastAPI 服务器<br/>(cognee.api.v1.add:add)"]
        MCP["MCP 服务器<br/>(cognee-mcp)"]
    end

    subgraph "核心 API 函数"
        add["add()<br/>(cognee.api.v1.add)"]
        cognify["cognify()<br/>(cognee.api.v1.cognify)"]
        remember["remember()<br/>(cognee.remember)"]
    end

    subgraph "管线引擎"
        run_pipeline["run_pipeline()<br/>(cognee.modules.pipelines)"]
        Task["Task 类<br/>(cognee.modules.pipelines.tasks.task)"]
    end

    subgraph "任务实现"
        classify["classify_documents()"]
        chunking["TextChunker"]
        extract["extract_graph_and_summarize()"]
    end

    subgraph "存储工厂"
        create_vector["create_vector_engine()<br/>(cognee.infrastructure.databases.vector)"]
        create_graph["create_graph_engine()<br/>(cognee.infrastructure.databases.graph)"]
        get_relational["get_relational_engine()"]
    end

    subgraph "数据库适配器"
        PGVector["PGVectorAdapter"]
        Kuzu["KuzuAdapter"]
        Neo4j["Neo4jAdapter"]
        LanceDB["LanceDBAdapter"]
    end

    CLI --> remember
    FastAPI --> add
    MCP --> cognify

    remember --> add
    remember --> cognify

    cognify --> run_pipeline
    run_pipeline --> Task

    Task --> classify
    Task --> chunking
    Task --> extract

    extract --> create_vector
    extract --> create_graph

    create_vector --> PGVector
    create_vector --> LanceDB
    create_graph --> Kuzu
    create_graph --> Neo4j

来源： cognee/api/v1/add/add.py:92-114、cognee/api/v1/cognify/cognify.py:43-59、cognee/infrastructure/databases/graph/get_graph_engine.py:115-131、cognee/infrastructure/databases/vector/create_vector_engine.py:48-59、README.md:129-158

用户界面

Cognee 提供了多个主要界面，它们都路由到相同的核心逻辑：

Python API - 通过 cognee.add()、cognee.cognify()、cognee.search() 以及高级记忆操作 cognee.remember() / cognee.recall() 进行直接函数调用。
CLI - 在 cognee.cli._cognee:main 中定义的 cognee-cli 命令行工具。
REST API - 基于 FastAPI 的端点，用于管理数据集、执行认知化操作和运行搜索。
MCP 服务器 - 用于 AI 助手集成（Claude、Cursor）的模型上下文协议服务器。

来源： README.md:129-158、README.md:160-173、pyproject.toml:204-204、cognee/api/v1/add/add.py:92-114

数据处理层

管线引擎使用 Task 抽象和 run_pipeline() 编排器。cognify 工作流中的关键处理步骤包括：

文档分类：识别文档类型和结构，以确定最佳处理路径。
文本片段切分：使用 TextChunker 等策略将内容分解为语义上有意义的片段。
图谱构建：提取实体和关系，构建带有相关嵌入向量的语义知识图谱。

来源： cognee/api/v1/cognify/cognify.py:82-89、cognee/api/v1/cognify/cognify.py:104-111、cognee/api/v1/cognify/cognify.py:22-26

存储层

工厂函数根据配置创建数据库适配器：

create_vector_engine() - 返回 VectorDBInterface 的实现。支持 LanceDB、PGVector 和 ChromaDB 等提供者。它还支持 pghybrid 模式，用于统一的关系型/向量存储。
create_graph_engine() - 返回 GraphDBInterface 的实现。支持 Kuzu（默认）、Neo4j 和基于 Postgres 的图谱存储。
get_relational_engine() - 提供基于 SQLAlchemy 的引擎，用于管理用户、数据集和持久化元数据。

来源： cognee/infrastructure/databases/vector/create_vector_engine.py:151-171、cognee/infrastructure/databases/graph/get_graph_engine.py:115-131、cognee/infrastructure/databases/vector/create_vector_engine.py:79-96

---

数据流架构

端到端处理流程

graph LR
    subgraph "1. 入库"
        raw["原始数据（文本/文件/URL）"]
        add["add() 任务"]
    end

    subgraph "2. 管线编排"
        run_p["run_pipeline()"]
        tasks["Cognify 任务"]
    end

    subgraph "3. 上下文与隔离"
        cv["ContextVars"]
        db_cm["DatabaseContextManager"]
    end

    subgraph "4. 存储适配器"
        VDB["向量数据库引擎"]
        GDB["图数据库引擎"]
        RDB["关系型引擎"]
    end

    raw --> add
    add --> RDB
    add --> run_p
    run_p --> tasks
    tasks --> cv
    cv --> db_cm
    db_cm --> VDB
    db_cm --> GDB

来源： cognee/api/v1/add/add.py:115-150、cognee/api/v1/cognify/cognify.py:82-89、cognee/context_global_variables.py:108-154

后端访问控制

Cognee 通过为每个数据集/用户组合创建独立的数据库实例来实现多用户隔离。这由 DatabaseContextManager 管理，它：

通过 dataset_queue 确保数据集槽位可用。
解析数据集特定的连接信息。
设置 vector_db_config 和 graph_db_config 的 ContextVars，使其指向隔离的存储。

来源： cognee/context_global_variables.py:83-92、cognee/context_global_variables.py:108-154、cognee/context_global_variables.py:136-154

---

配置系统

配置层级

Cognee 使用 Pydantic 设置配合环境变量覆盖来管理其复杂的基础设施：

BaseConfig - 全局设置，包括 data_root_directory 和 system_root_directory。
GraphConfig - 图数据库专用配置，确定 graph_database_provider（默认为 "ladybug/kuzu"）并解析文件路径。
VectorConfig - 管理向量数据库提供者、URL 和用于数据集隔离的处理器。
LLM/嵌入向量配置 - 配置 API 密钥、模型和提供者（OpenAI、Anthropic 等），用于处理操作。

来源： cognee/api/v1/config/config.py:119-145、cognee/infrastructure/databases/graph/config.py:45-60、cognee/infrastructure/databases/vector/config.py:22-42、.env.template:14-34

---

总结

Cognee 的架构以三数据库设计为核心，通过基于 ContextVar 的隔离层进行管理。这使得系统能够在不同数据库提供者之间保持灵活性，同时确保其基于任务的管线中的每个操作都是隔离且安全的。该系统弥合了原始数据入库与结构化 AI 记忆之间的差距，为智能体提供了强大的语义层。

来源： cognee/context_global_variables.py:108-154、cognee/api/v1/cognify/cognify.py:82-89、cognee/infrastructure/databases/vector/create_vector_engine.py:151-171