12.2 · 多数据库设置教程（Multi-Database Setup Tutorial）

多数据库设置教程

多数据库设置教程

相关源文件

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

• 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/modules/users/models/DatasetDatabase.py
• cognee/root_dir.py
• cognee/shared/lru_cache.py
• cognee/tests/test_chromadb.py
• cognee/tests/test_data/Quantum_computers.txt
• cognee/tests/test_kuzu.py
• cognee/tests/test_lancedb.py
• cognee/tests/test_library.py
• cognee/tests/test_neo4j.py
• cognee/tests/test_pgvector.py

本教程将指导您在 Cognee 中配置和部署不同的数据库后端。该系统采用三数据库架构，向量数据库、图数据库和关系数据库协同工作，用于存储知识图谱、嵌入向量和元数据。

范围：本页面涵盖支持的数据库后端的实际设置和配置。有关数据库适配器的详细 API 文档，请参阅向量数据库适配器、图数据库适配器和关系数据库适配器。有关完整的环境变量参考，请参阅环境变量参考。

理解三数据库架构

Cognee 同时使用三种专门的数据库类型：

每种数据库类型都有多个提供方选项。默认提供方（LanceDB、Ladybug/Kuzu、SQLite）基于文件存储，无需外部服务，非常适合本地开发。

配置通过 Pydantic 设置类加载：

• 向量：VectorConfig 位于 cognee/infrastructure/databases/vector/config.py:11-90
• 图：GraphConfig 位于 cognee/infrastructure/databases/graph/config.py:20-138
• 关系：BaseConfig 位于 cognee/base_config.py:11-70

数据库适配器架构

数据库创建的工厂模式

来源：cognee/infrastructure/databases/vector/config.py:11-90、cognee/infrastructure/databases/graph/config.py:20-138、cognee/base_config.py:11-70、cognee/infrastructure/databases/vector/create_vector_engine.py:48-109、cognee/infrastructure/databases/graph/get_graph_engine.py:115-168

本地开发设置（默认配置）

默认配置无需任何外部服务。所有数据库均基于文件存储，并保存在 BaseConfig 管理的目录中。

默认配置

创建一个包含最小配置的 .env 文件：

# 必需：大语言模型（LLM）API 密钥
LLM_API_KEY="your_openai_api_key"

# 可选：自定义存储位置（未设置时使用默认值）
# DATA_ROOT_DIRECTORY="/path/to/your/data"
# SYSTEM_ROOT_DIRECTORY="/path/to/your/system"

默认路径由 BaseConfig 计算得出 cognee/base_config.py:11-41：

• DATA_ROOT_DIRECTORY：.data_storage（用于用户数据文件）cognee/base_config.py:12-12
• SYSTEM_ROOT_DIRECTORY：.cognee_system（用于数据库和系统文件）cognee/base_config.py:13-13

系统会自动使用：

• 向量：LanceDB，位于 {SYSTEM_ROOT_DIRECTORY}/databases/cognee.lancedb cognee/infrastructure/databases/vector/config.py:62-65
• 图：Ladybug（基于 Kuzu），位于 {SYSTEM_ROOT_DIRECTORY}/databases/cognee_graph_ladybug cognee/infrastructure/databases/graph/config.py:85-103
• 关系：SQLite，位于 {SYSTEM_ROOT_DIRECTORY}/cognee_db.db

验证

import asyncio
import cognee

async def verify_setup():
    # 这将初始化所有三个数据库
    await cognee.add("Test data")
    await cognee.cognify()

    from cognee.infrastructure.databases.vector import get_vector_engine
    from cognee.infrastructure.databases.graph import get_graph_engine

    vector_engine = get_vector_engine()
    # 对于 LanceDB，url 是文件路径
    print(f"向量数据库 URL：{vector_engine.url}")

    graph_engine = await get_graph_engine()
    # 初始化后检查图是否为空
    is_empty = await graph_engine.is_empty()
    print(f"图数据库是否为空：{is_empty}")

asyncio.run(verify_setup())

来源：cognee/base_config.py:11-73、cognee/infrastructure/databases/vector/config.py:53-67、cognee/infrastructure/databases/graph/config.py:71-105、cognee/tests/test_kuzu.py:54-60

PostgreSQL 设置（关系数据库 + PGVector）

PostgreSQL 可以同时作为关系数据库和向量数据库（通过 pgvector 扩展）。Cognee 还支持一种称为 pghybrid 的"统一提供方"模式，该模式使用 Postgres 处理所有三种存储类型（关系、向量和图）。

PGVector 配置

# .env
LLM_API_KEY="your_api_key"

# 关系数据库
DB_PROVIDER="postgres"
DB_NAME="cognee_db"
DB_HOST="127.0.0.1"
DB_PORT="5432"
DB_USERNAME="cognee"
DB_PASSWORD="cognee"

# 向量数据库（使用 PGVector 扩展）
VECTOR_DB_PROVIDER="pgvector"

混合 Postgres 设置（pghybrid）

设置 USE_UNIFIED_PROVIDER="pghybrid" 会指示 Cognee 使用 Postgres 同时处理图和向量存储，并使用与关系引擎相同的连接信息。

• 图：使用 PostgresAdapter cognee/infrastructure/databases/graph/get_graph_engine.py:159-166
• 向量：使用 PGVectorAdapter cognee/infrastructure/databases/vector/create_vector_engine.py:78-96

来源：cognee/infrastructure/databases/vector/create_vector_engine.py:78-96、cognee/infrastructure/databases/graph/get_graph_engine.py:159-166、cognee/tests/test_pgvector.py:71-90

Neo4j 和 Ladybug 设置

Neo4j 设置

Neo4j 替代基于文件的 Ladybug/Kuzu 数据库，用于知识图谱存储。

配置：

# .env
GRAPH_DATABASE_PROVIDER="neo4j"
GRAPH_DATABASE_URL="bolt://localhost:7687"
GRAPH_DATABASE_USERNAME="neo4j"
GRAPH_DATABASE_PASSWORD="password"

_GraphEngineHandle 会跟踪引擎状态，并在引擎发生变化时重新运行幂等的模式设置 cognee/infrastructure/databases/graph/get_graph_engine.py:56-78。

Ladybug（Kuzu）调优

Cognee 使用 Ladybug 作为 Kuzu 的默认图处理器。您可以通过环境变量调整性能：

# .env
KUZU_NUM_THREADS=4
KUZU_BUFFER_POOL_SIZE=1073741824 # 1GB
KUZU_MAX_DB_SIZE=10737418240 # 10GB

这些映射在 GraphConfig 中定义 cognee/infrastructure/databases/graph/config.py:62-65。

来源：cognee/infrastructure/databases/graph/get_graph_engine.py:56-112、cognee/infrastructure/databases/graph/config.py:62-65、cognee/tests/test_neo4j.py:15-31

多用户和后端访问控制

Cognee 支持多用户隔离，通过为不同的数据集或用户创建独立的数据库实例来实现。这由 ENABLE_BACKEND_ACCESS_CONTROL 控制 cognee/context_global_variables.py:83-92。

多用户支持的要求

并非所有提供方都支持多用户隔离。系统会在 multi_user_support_possible() 中检查兼容性 cognee/context_global_variables.py:34-80。

• 支持的向量数据库：lancedb、pgvector、falkor cognee/context_global_variables.py:95-95
• 支持的图数据库：ladybug、kuzu、falkor、postgres cognee/context_global_variables.py:96-96

配置上下文

数据库配置使用 ContextVar 进行作用域限定，以允许不同的异步任务使用不同的数据库实例 cognee/context_global_variables.py:23-27。

from cognee.context_global_variables import set_database_global_context_variables

async with set_database_global_context_variables(dataset_id, user_id):
    # 在此代码块内，get_graph_engine() 和 get_vector_engine()
    # 将返回连接到该特定数据集数据库的适配器。
    await cognee.cognify()

DatabaseContextManager 负责处理这些连接信息的延迟解析 cognee/context_global_variables.py:108-150。

来源：cognee/context_global_variables.py:23-150、cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:64-121

故障排除和维护

清理数据

要干净地切换数据库提供方，通常需要清理现有数据以避免模式不匹配。

import cognee

# 删除用户数据文件
await cognee.prune.prune_data()

# 删除系统数据库（关系、向量、图）
await cognee.prune.prune_system(metadata=True)

验证删除

如 test_library.py 所示，您可以验证数据库是否已正确删除：

from cognee.infrastructure.databases.relational import get_relational_engine

# 对于 SQLite，文件应该不再存在
db_path = get_relational_engine().db_path
assert not os.path.exists(db_path)

来源：cognee/tests/test_library.py:131-155、cognee/tests/test_pgvector.py:14-51

配置流程示意图

此图展示了从自然语言环境设置到管理它们的特定代码实体的转换过程。

来源：cognee/infrastructure/databases/graph/config.py:20-60、cognee/infrastructure/databases/vector/config.py:11-36、cognee/infrastructure/databases/graph/get_graph_engine.py:115-168、cognee/infrastructure/databases/vector/create_vector_engine.py:48-109、cognee/context_global_variables.py:108-150