agentic_huge_data_base / wiki
页面 Cognee · 1.3 系统架构总览·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 1.3

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

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

项目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

系统架构总览

相关源文件

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

  • .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
  • cognee/infrastructure/databases/utils/get_or_create_dataset_database.py
  • cognee/infrastructure/databases/vector/config.py
  • cognee/infrastructure/databases/vector/create_vector_engine.py
  • cognee/infrastructure/databases/vector/get_vector_engine.py
  • cognee/infrastructure/llm/config.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.py
  • cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py
  • cognee/modules/data/models/Data.py
  • cognee/modules/pipelines/operations/pipeline.py
  • cognee/modules/pipelines/operations/run_tasks.py
  • cognee/modules/settings/__init__.py
  • cognee/modules/settings/get_settings.py
  • cognee/modules/settings/save_llm_config.py
  • cognee/modules/settings/save_vector_db_config.py
  • cognee/modules/users/models/DatasetDatabase.py
  • cognee/root_dir.py
  • cognee/shared/lru_cache.py
  • cognee/tasks/ingestion/ingest_data.py
  • cognee/tasks/ingestion/save_data_item_to_storage.py
  • cognee/tests/unit/infrastructure/llm/test_get_llm_client.py
  • poetry.lock
  • pyproject.toml
  • uv.lock

目的与范围

本文档提供了 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

系统组件总览

组件架构与代码实体
Cognee · 组件架构与代码实体 · 图 1
Cognee · 组件架构与代码实体 · 图 1

来源： 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 提供了多个主要界面，它们都路由到相同的核心逻辑：

  1. Python API - 通过 cognee.add()、cognee.cognify()、cognee.search() 以及高级记忆操作 cognee.remember() / cognee.recall() 进行直接函数调用。
  2. CLI - 在 cognee.cli._cognee:main 中定义的 cognee-cli 命令行工具。
  3. REST API - 基于 FastAPI 的端点，用于管理数据集、执行认知化操作和运行搜索。
  4. 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

数据流架构

端到端处理流程
Cognee · 端到端处理流程 · 图 2
Cognee · 端到端处理流程 · 图 2

来源： 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 设置配合环境变量覆盖来管理其复杂的基础设施：

  1. BaseConfig - 全局设置，包括 data_root_directory 和 system_root_directory。
  2. GraphConfig - 图数据库专用配置，确定 graph_database_provider（默认为 "ladybug/kuzu"）并解析文件路径。
  3. VectorConfig - 管理向量数据库提供者、URL 和用于数据集隔离的处理器。
  4. 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