7 · 配置系统（Configuration System）

配置系统

配置系统

相关源文件

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

• .env.template
• README.md
• assets/cognee_benefits.png
• 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/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/tests/unit/infrastructure/llm/test_get_llm_client.py

本文档介绍 Cognee 的配置系统，该系统管理所有组件（包括大语言模型（LLM）提供商、数据库连接、存储后端、安全策略和系统目录）的基于环境的设置。配置系统使用 Pydantic Settings 来加载、验证环境变量，并在整个应用中提供类型安全的访问。

有关特定数据库适配器及其配置的信息，请参见数据库配置与选择。有关大语言模型（LLM）提供商设置的详细信息，请参见大语言模型（LLM）提供商配置。有关安全相关设置，请参见安全配置。

配置架构

Cognee 的配置系统由专门的配置类组成，这些类继承自 Pydantic 的 BaseSettings。每个类管理一个特定领域（系统路径、大语言模型（LLM）设置、数据库连接），并自动从环境变量加载值。

配置依赖图

标题：配置系统数据流

配置流程：来自 .env 文件或系统环境的环境变量被加载到专门的配置类中。带有 @lru_cache 装饰器的工厂函数创建这些配置的单例实例。应用组件通过工厂函数消费这些配置。

来源： cognee/base_config.py:11-60, cognee/infrastructure/llm/config.py:15-88, cognee/infrastructure/databases/vector/config.py:11-37, cognee/infrastructure/databases/graph/config.py:20-67

配置类

BaseConfig

BaseConfig 类管理系统级目录和可观测性设置。它在 cognee/base_config.py:11-60 中定义。

关键属性：

• data_root_directory：用户数据文件的存储位置 cognee/base_config.py:12。
• system_root_directory：系统文件和数据库的存储位置 cognee/base_config.py:13。
• cache_root_directory：缓存存储位置 cognee/base_config.py:14。
• logs_root_directory：日志文件目录 cognee/base_config.py:15。
• monitoring_tool：可观测性提供商 cognee/base_config.py:16。

路径校验： validate_paths 校验器 cognee/base_config.py:18-41 确保所有目录路径都是绝对路径，并处理特殊的 S3 路径逻辑。当设置了 STORAGE_BACKEND=s3 但没有显式设置 CACHE_ROOT_DIRECTORY 时，它会自动配置 S3 缓存路径 cognee/base_config.py:23-30。

LLMConfig

LLMConfig 类管理大语言模型（LLM）提供商设置、结构化输出框架和速率限制。它在 cognee/infrastructure/llm/config.py:15-88 中定义。

BAML 配置： 当 structured_output_framework="baml" 时，model_post_init 方法 cognee/infrastructure/llm/config.py:127-152 会初始化 BAML 的 ClientRegistry。

VectorConfig

VectorConfig 类管理向量数据库连接设置。它在 cognee/infrastructure/databases/vector/config.py:11-37 中定义。

路径解析： validate_paths 方法 cognee/infrastructure/databases/vector/config.py:52-67 处理路径解析。如果未设置 vector_db_url，则默认为 {system_root_directory}/databases/cognee.lancedb cognee/infrastructure/databases/vector/config.py:65。

GraphConfig

GraphConfig 类管理图数据库设置。它在 cognee/infrastructure/databases/graph/config.py:20-67 中定义。

动态默认值： fill_derived 校验器 cognee/infrastructure/databases/graph/config.py:71-105 根据 graph_database_provider 动态设置 graph_filename 和 graph_file_path。如果未提供显式路径，则默认为 {system_root_directory}/databases/cognee_graph_{provider} cognee/infrastructure/databases/graph/config.py:89。

来源： cognee/base_config.py:11-60, cognee/infrastructure/llm/config.py:15-88, cognee/infrastructure/databases/vector/config.py:11-37, cognee/infrastructure/databases/graph/config.py:20-67

配置加载与缓存

Cognee 通过 functools.lru_cache 对配置对象使用单例模式。

标题：单例配置检索

引擎缓存：数据库引擎工厂函数使用 closing_lru_cache 来管理生命周期和资源清理。create_vector_engine cognee/infrastructure/databases/vector/create_vector_engine.py:150 和 create_graph_engine cognee/infrastructure/databases/graph/get_graph_engine.py:168 基于参数值进行缓存。这允许多个引擎实例（例如，每个数据集的数据库）共存，同时避免重复实例化。缓存大小由 DATABASE_MAX_LRU_CACHE_SIZE cognee/infrastructure/databases/graph/get_graph_engine.py:8 控制。

来源： cognee/base_config.py:71-73, cognee/infrastructure/databases/vector/config.py:92-107, cognee/infrastructure/databases/vector/create_vector_engine.py:150-162, cognee/infrastructure/databases/graph/get_graph_engine.py:168-180

全局状态与上下文管理

Cognee 通过 Python 的 contextvars 模块支持作用域数据库配置，这对多租户和多用户支持至关重要。

• vector_db_config ContextVar：保存当前异步任务的向量数据库设置 cognee/context_global_variables.py:25。
• graph_db_config ContextVar：保存当前异步任务的图数据库设置 cognee/context_global_variables.py:26。
• DatabaseContextManager：由 set_database_global_context_variables 使用的辅助类，用于在作用域内应用每个数据集和每个用户的配置 cognee/context_global_variables.py:108-150。

后端访问控制：系统检查 ENABLE_BACKEND_ACCESS_CONTROL cognee/context_global_variables.py:84 以确定是否应为每个数据集隔离数据库。如果启用，get_or_create_dataset_database cognee/infrastructure/databases/utils/get_or_create_dataset_database.py:64-82 会解析特定用户和数据集的连接信息。

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

运行时配置 API

用户可以使用 cognee.config 命名空间 cognee/api/v1/config/config.py:96-116 在运行时修改设置。这会更新底层的单例配置对象，无需更改环境变量。

• cognee.config.system_root_directory(path)：更新系统根目录，并将更改级联到关系型、图数据库和向量数据库路径 cognee/api/v1/config/config.py:119-145。
• cognee.config.set_llm_model(model)：更新活跃的大语言模型（LLM）模型 cognee/api/v1/config/config.py:109。

来源： cognee/api/v1/config/config.py:96-188

环境变量参考

有关所有可用环境变量的完整参考，请参见环境变量参考。关键类别包括：

• 大语言模型（LLM）与嵌入向量：LLM_API_KEY、LLM_PROVIDER、EMBEDDING_PROVIDER 等 .env.template:6-80
• 存储：STORAGE_BACKEND、STORAGE_BUCKET_NAME、DATA_ROOT_DIRECTORY .env.template:97-113
• 数据库：DB_PROVIDER、GRAPH_DATABASE_PROVIDER、VECTOR_DB_PROVIDER .env.template:25-34
• 安全：ENABLE_BACKEND_ACCESS_CONTROL cognee/context_global_variables.py:84（请参见安全配置）

来源： .env.template:1-184, cognee/context_global_variables.py:83-92