环境变量参考
环境变量参考
相关源文件
本章引用的主要源码文件：
.env.template.github/actions/cognee_setup/action.yml.github/workflows/basic_tests.yml.github/workflows/db_examples_tests.yml.github/workflows/e2e_tests.yml.github/workflows/examples_tests.yml.github/workflows/graph_db_tests.yml.github/workflows/relational_db_migration_tests.yml.github/workflows/reusable_notebook.yml.github/workflows/search_db_tests.yml.github/workflows/test_s3_file_storage.yml.github/workflows/vector_db_tests.yml.github/workflows/weighted_edges_tests.ymlREADME.mdassets/cognee_benefits.pngcognee/api/v1/config/config.pycognee/infrastructure/llm/config.pycognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/bedrock/adapter.pycognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.pycognee/modules/settings/__init__.pycognee/modules/settings/get_settings.pycognee/modules/settings/save_llm_config.pycognee/modules/settings/save_vector_db_config.pycognee/tests/unit/infrastructure/llm/test_get_llm_client.py
本文档提供了 Cognee 识别的所有环境变量的完整参考。这些变量控制系统行为，包括大语言模型（LLM）提供商选择、数据库配置、存储后端、安全策略和可观测性设置。所有配置均通过 Pydantic 设置类加载，这些类从 .env 文件和系统环境变量中读取。
有关安全相关配置的信息，请参见安全配置。有关存储后端设置和配置，请参见存储配置。有关选择和切换数据库提供商的指导，请参见数据库配置与选择。
配置系统架构
配置系统采用分层设计，专用配置类（LLMConfig、GraphConfig、VectorConfig、RelationalConfig）通过 Pydantic 的 BaseSettings 从环境变量加载设置。BaseConfig 类建立了根目录和可观测性设置，其他配置会引用这些设置。
配置依赖与流程
下图展示了环境变量如何被摄入到 Pydantic 模型中，然后分发到功能适配器。
标题：配置数据流
来源： cognee/infrastructure/llm/config.py:15-87, cognee/api/v1/config/config.py:4-14, cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:8-12
配置加载与优先级
配置值使用 Pydantic 的 BaseSettings 加载，优先级如下（从高到低）：
- 系统环境变量 - 直接的操作系统环境变量。
.env文件 - 项目根目录下的.env文件。- 默认值 - 配置类中硬编码的默认值。
Cognee 在 Python API（cognee/api/v1/config/config.py）中提供了一个 config 命名空间，用于运行时覆盖，可以修改这些单例设置对象而无需更改环境变量 cognee/api/v1/config/config.py:96-116。
来源： cognee/infrastructure/llm/config.py:88, cognee/api/v1/config/config.py:18-38
大语言模型（LLM）配置变量
这些变量配置大语言模型（LLM）提供商和结构化输出框架。Cognee 通过 LLMProvider 枚举支持多个提供商，包括 OPENAI、ANTHROPIC、GEMINI、MISTRAL、AZURE、BEDROCK、OLLAMA 和 LLAMA_CPP cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:70-92。
主要大语言模型（LLM）设置
| 变量 | 默认值 | 描述 | 配置类 |
|---|---|---|---|
LLM_API_KEY | None | 大语言模型（LLM）提供商认证的 API 密钥 | LLMConfig.llm_api_key |
LLM_MODEL | "openai/gpt-5-mini" | 带提供商前缀的模型标识符 | LLMConfig.llm_model |
LLM_PROVIDER | "openai" | 提供商标识符：openai、anthropic、ollama 等 | LLMConfig.llm_provider |
LLM_ENDPOINT | "" | 自定义 API 端点 URL | LLMConfig.llm_endpoint |
LLM_TEMPERATURE | 0.0 | 模型的采样温度 | LLMConfig.llm_temperature |
LLM_ARGS | None | 用于补全调用的额外参数的 JSON 字符串 | LLMConfig.llm_args |
STRUCTURED_OUTPUT_FRAMEWORK | "instructor" | 结构化数据框架："instructor" 或 "baml" | LLMConfig.structured_output_framework |
BAML 特定设置
仅在 STRUCTURED_OUTPUT_FRAMEWORK="baml" 时使用。这需要 baml 额外依赖 cognee/infrastructure/llm/config.py:130-134。
| 变量 | 默认值 | 描述 |
|---|---|---|
BAML_LLM_PROVIDER | "openai" | BAML 提供商标识符 |
BAML_LLM_MODEL | "gpt-5-mini" | BAML 模型名称 |
BAML_LLM_API_KEY | None | BAML API 密钥 |
BAML_LLM_ENDPOINT | "" | BAML 自定义端点 |
大语言模型（LLM）速率限制
Cognee 可以限流大语言模型（LLM）请求，以防止 API 耗尽 cognee/infrastructure/llm/config.py:64-67。
| 变量 | 默认值 | 描述 |
|---|---|---|
LLM_RATE_LIMIT_ENABLED | False | 启用/禁用大语言模型（LLM）速率限制 |
LLM_RATE_LIMIT_REQUESTS | 60 | 每个时间间隔的最大请求数 |
LLM_RATE_LIMIT_INTERVAL | 60 | 时间间隔（秒） |
来源： cognee/infrastructure/llm/config.py:42-87, .env.template:41-68, cognee/infrastructure/llm/structured_output_framework/litellm_instructor/llm/get_llm_client.py:95-102
嵌入向量配置变量
这些变量配置用于生成向量表示的 EmbeddingEngine。
| 变量 | 默认值 | 描述 |
|---|---|---|
EMBEDDING_PROVIDER | "openai" | 提供商：openai、fastembed、ollama 等 |
EMBEDDING_MODEL | "openai/text-embedding-3-large" | 用于嵌入向量的具体模型 |
EMBEDDING_DIMENSIONS | 3072 | 向量维度 |
EMBEDDING_BATCH_SIZE | 36 | 嵌入操作的批处理大小 |
来源： .env.template:19-22, .env.template:70-80
数据库配置
Cognee 采用三数据库设计。引擎创建函数使用这些变量来实例化正确的适配器。
图数据库（知识图谱）
由 GraphConfig 管理。支持的提供商包括 kuzu、neo4j、networkx 和 postgres .env.template:134-149。
| 变量 | 默认值 | 描述 |
|---|---|---|
GRAPH_DATABASE_PROVIDER | "kuzu" | 主要图数据库提供商 |
GRAPH_DATABASE_URL | "" | 连接 URL（例如 Neo4j 的 bolt://localhost:7687） |
GRAPH_DATABASE_USERNAME | "" | 认证用户名 |
GRAPH_DATABASE_PASSWORD | "" | 认证密码 |
GRAPH_DATASET_DATABASE_HANDLER | "kuzu" | 数据集隔离的处理器 |
向量数据库（语义搜索）
由 VectorConfig 管理。支持的提供商包括 lancedb、pgvector、qdrant、weaviate、milvus 和 chromadb .env.template:156-157。
| 变量 | 默认值 | 描述 |
|---|---|---|
VECTOR_DB_PROVIDER | "lancedb" | 主要向量数据库提供商 |
VECTOR_DB_URL | "" | 向量存储的路径或 URL |
VECTOR_DB_KEY | "" | 托管向量数据库提供商的 API 密钥 |
VECTOR_DATASET_DATABASE_HANDLER | "lancedb" | 数据集隔离的处理器 |
关系数据库
Cognee 使用 SQLAlchemy 进行元数据和关系存储 cognee/api/v1/config/config.py:135-136。
| 变量 | 默认值 | 描述 |
|---|---|---|
DB_PROVIDER | "sqlite" | 提供商：sqlite 或 postgres |
DB_NAME | "cognee_db" | 数据库名称 |
DB_HOST | "127.0.0.1" | Postgres 的主机地址 |
DB_PORT | 5432 | Postgres 的端口 |
来源： .env.template:24-33, .env.template:120-161, cognee/api/v1/config/config.py:133-145
目录和存储配置
控制文件系统和云存储路径的变量。Cognee 可以使用本地存储或 AWS S3 .env.template:101-113。
| 变量 | 默认值 | 描述 |
|---|---|---|
DATA_ROOT_DIRECTORY | None | 原始摄入文件的根目录 |
SYSTEM_ROOT_DIRECTORY | None | 本地数据库文件的根目录 |
STORAGE_BACKEND | "local" | "local" 或 "s3" |
AWS_REGION | "us-east-1" | S3 区域 |
STORAGE_BUCKET_NAME | None | S3 存储桶名称 |
来源： .env.template:93-113, cognee/api/v1/config/config.py:119-157
操作和安全设置
| 变量 | 默认值 | 描述 |
|---|---|---|
ENV | "local" | 环境模式（例如 dev、prod） |
RUNTIME__LOG_LEVEL | "ERROR" | 系统的日志级别 |
COGNEE_TRACING_ENABLED | False | 启用 OpenTelemetry 追踪 |
REQUIRE_AUTHENTICATION | False | （REST API）需要 JWT 令牌 |
USE_UNIFIED_PROVIDER | "" | 设置为 "pghybrid" 以使用 Postgres 进行所有存储 |
统一提供商映射
标题：统一提供商代码关联
来源： .github/workflows/basic_tests.yml:36-38, .github/workflows/graph_db_tests.yml:117-156, .github/workflows/e2e_tests.yml:58-69