10.2 · 开发设置（Development Setup）

开发设置

开发环境搭建

相关源文件

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

• .env.example
• .github/CODEOWNERS
• .github/actions/cognee_setup/action.yml
• .github/pull_request_template.md
• .github/workflows/approve_dco.yaml
• .github/workflows/backend_docker_build_test.yml
• .github/workflows/basic_tests.yml
• .github/workflows/clean_stale_pr.yaml
• .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.yml
• CONTRIBUTING.md
• NOTICE.md
• licenses/README.md

本文档提供在本地搭建 Cognee 开发环境的说明，涵盖安装、环境配置、数据库初始化以及开发工具。如需使用 Docker 容器进行部署，请参阅 Docker 部署。关于运行测试的信息，请参阅 测试指南。

前提条件

Cognee 需要 Python 3.10 至 3.13 版本，目前不支持 Python 3.14。

来源： .github/workflows/search_db_tests.yml:18, .github/workflows/weighted_edges_tests.yml:31

安装方法

使用 uv 进行开发安装

uv 是 Cognee 开发推荐的包管理器，与 pip 相比，它能提供更快的依赖解析和安装速度。

步骤 1：安装 uv 请遵循官方 uv 安装指南。

步骤 2：克隆并安装 Cognee

# 克隆仓库
git clone https://github.com/topoteretes/cognee.git
cd cognee

# 以可编辑模式安装，并包含开发依赖
uv sync --extra dev

dev 额外组会安装用于测试、代码检查和格式化的开发依赖。

来源： CONTRIBUTING.md:67-77, .github/actions/cognee_setup/action.yml:62

可选依赖

Cognee 使用可选依赖组来支持不同功能。根据需要，通过 uv sync --extra <组名> 或 pip install ".[组名]" 安装其他组。

来源： .github/actions/cognee_setup/action.yml:62, .github/workflows/basic_tests.yml:140, .github/workflows/examples_tests.yml:48, .github/workflows/reusable_notebook.yml:54

环境配置

配置加载

Cognee 在启动时从 .env 文件加载环境变量。配置系统使用 Pydantic 设置进行校验。

图示：配置与设置流程

来源： .github/actions/cognee_setup/action.yml:67-75, .github/workflows/basic_tests.yml:45-58

必需的环境变量

至少需要配置一个 LLM API 密钥。Cognee 在许多示例中默认使用 OpenAI。

LLM_API_KEY="你的 OpenAI API 密钥"

来源： CONTRIBUTING.md:102, .github/workflows/e2e_tests.yml:34-35

数据库初始化

默认嵌入式数据库

Cognee 设计为开箱即用，支持嵌入式数据库：

• 关系型：SQLite（默认 DB_PROVIDER）.github/workflows/search_db_tests.yml:63
• 图数据库：Kuzu（嵌入式图引擎）.github/workflows/search_db_tests.yml:61
• 向量数据库：LanceDB（无服务器向量数据库）.github/workflows/search_db_tests.yml:62

多数据库测试

CI 环境会针对多个数据库后端验证 Cognee。开发者可以通过设置以下环境变量来切换后端：

来源： .github/workflows/graph_db_tests.yml:117-119, .github/workflows/vector_db_tests.yml:98-110

开发工具

代码质量

该项目通过 GitHub Actions 使用 ruff 进行代码检查和格式化。

# 运行代码检查和格式化检查
uv run ruff check .
uv run ruff format --check .

来源： .github/workflows/weighted_edges_tests.yml:162-170

运行测试

测试文件位于 cognee/tests 目录下。你可以使用 pytest 或 uv run 来运行它们。

# 运行基础库测试
uv run python cognee/tests/test_library.py

# 运行单元测试
uv run pytest cognee/tests/unit/

# 使用特定提供商运行搜索数据库测试
GRAPH_DATABASE_PROVIDER=kuzu VECTOR_DB_PROVIDER=lancedb uv run pytest cognee/tests/test_search_db.py

来源： CONTRIBUTING.md:105, .github/workflows/basic_tests.yml:71, .github/workflows/search_db_tests.yml:64

Git 钩子

Cognee 使用 pre-commit 来确保提交前的代码质量。

# 安装 pre-commit 钩子
uv run pip install pre-commit && pre-commit install

# 手动运行钩子
pre-commit run --all-files

来源： CONTRIBUTING.md:68, CONTRIBUTING.md:140

运行示例

仓库中包含一组示例，位于 examples/demos/ 和 examples/database_examples/ 目录下。

# 运行一个简单演示
uv run python examples/demos/simple_cognee_example.py

# 运行特定数据库的示例（例如 Neo4j）
uv run python examples/database_examples/neo4j_example.py

来源： CONTRIBUTING.md:115-121, .github/workflows/basic_tests.yml:103, .github/workflows/db_examples_tests.yml:83

贡献工作流

1. 分支管理：始终从 dev 分支创建新分支。CONTRIBUTING.md:1-2
2. DCO 声明：所有拉取请求必须包含开发者原创证书声明：*"我确认此拉取请求中每个提交的所有代码均符合 Topoteretes 开发者原创证书的条款"*。CONTRIBUTING.md:167-168, .github/pull_request_template.md:37-38
3. 签名提交：使用 git commit -s 签署你的提交。CONTRIBUTING.md:144, CONTRIBUTING.md:163
4. 截图：你必须在拉取请求描述中提供本地测试通过的截图。CONTRIBUTING.md:152, .github/pull_request_template.md:22-23

来源： CONTRIBUTING.md:1-184, .github/pull_request_template.md:1-39