12.3 · 开发环境设置（Development Environment Setup）

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节12.3 状态全文译文模块测试、发布与运维、安装与启动、配置治理、接口与服务契约

项目要点页2.5 参考项目项目章节目录Graphiti DeepWiki 原始章节Development Environment Setup 上一章12.2 下一章12.4

源码线索

.github/workflows/release-graphiti-core.yml
.github/workflows/typecheck.yml
.github/workflows/unit_tests.yml
CLAUDE.md
Makefile
OTEL_TRACING.md
examples/opentelemetry/.env.example
examples/opentelemetry/README.md
examples/opentelemetry/otel_stdout_example.py
examples/opentelemetry/pyproject.toml

模块标签

测试、发布与运维
安装与启动
配置治理
接口与服务契约
界面与交互

章节正文

开发环境设置

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/12.3-development-environment-setup

开发环境搭建

概述

Graphiti 开发依赖一套现代 Python 技术栈，核心使用 uv 进行依赖管理，pytest 进行测试。该环境通过可选的依赖模式支持多种图数据库后端（Neo4j、FalkorDB、Kuzu、Neptune）以及多种大语言模型（LLM）提供商 pyproject.toml:27-38。

工具与前置条件

要为 Graphiti 贡献代码，需要安装以下工具：

Python 3.10+：最低支持的 Python 版本 pyproject.toml:12，Makefile:4。
uv：一个快速的 Python 包安装器和解析器，用于所有依赖管理 Makefile:5，uv.lock:1-10。
Docker：推荐用于运行 Neo4j 和 FalkorDB 的本地实例，以进行集成测试 .github/workflows/unit_tests.yml:49-63。
Make：用于编排常见的开发任务，如代码检查、格式化和测试 Makefile:1-33。

来源：pyproject.toml:12，pyproject.toml:27-38，Makefile:4-5，Makefile:1-33，uv.lock:1-10，.github/workflows/unit_tests.yml:49-63

初始工作区设置

本项目使用 uv sync 来管理虚拟环境和依赖。

克隆仓库：

    git clone https://github.com/getzep/graphiti
    cd graphiti

安装依赖：

运行以下命令来创建虚拟环境并安装所有必要的包，包括在 dev 可选依赖组中定义的开发工具 pyproject.toml:39-63。

    make install

该命令会执行 uv sync --extra dev Makefile:15，确保 ruff 和 pyright 等工具可用。

配置环境变量：

在项目根目录创建一个 .env 文件。大多数功能至少需要一个 LLM API 密钥 CLAUDE.md:99。

    OPENAI_API_KEY=your_key_here

其他提供商的密钥（如 ANTHROPIC_API_KEY、GOOGLE_API_KEY、GROQ_API_KEY 或 VOYAGE_API_KEY）请参考 CLAUDE.md:97-101。

来源：pyproject.toml:39-63，Makefile:15，CLAUDE.md:97-101

开发工作流命令

根目录下的 Makefile 为开发任务提供了标准化的接口。

命令	操作	实现方式
`make format`	修复导入顺序并格式化代码	`ruff check --select I --fix` & `ruff format` `Makefile:18-20`
`make lint`	运行静态分析和类型检查	`ruff check` & `pyright ./graphiti_core` `Makefile:23-25`
`make test`	运行单元测试（排除集成测试）	`pytest`，通过环境变量禁用数据库 `Makefile:28-29`
`make check`	运行格式化、代码检查和测试	组合上述目标 `Makefile:32`

服务器与 MCP 开发

FastAPI 服务器：进入 server/ 目录管理 REST API。开发时使用 uvicorn graph_service.main:app --reload 命令 CLAUDE.md:41-46。
MCP 服务器：位于 mcp_server/ 目录。支持通过 docker-compose up 进行容器化部署 CLAUDE.md:54-63。

来源：Makefile:1-33，CLAUDE.md:41-46，CLAUDE.md:54-63

测试与数据库配置

Graphiti 支持多种图数据库。在本地开发时，你可以使用 Kuzu（内存模式），或通过 Docker 启动 Neo4j/FalkorDB。

本地数据库设置

Neo4j（版本 5.26+）： Neo4jDriver 默认使用 neo4j 数据库名称 CLAUDE.md:105-107。GitHub Actions 工作流中提供了测试配置 .github/workflows/unit_tests.yml:55-63。

docker run -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/testpass \
  -e NEO4J_PLUGINS='["apoc"]' \
  neo4j:5.26-community

FalkorDB（版本 1.1.2+）： FalkorDriver 默认使用 default_db CLAUDE.md:108-110。

docker run -p 6379:6379 falkordb/falkordb:latest

运行测试

测试套件通过 pytest 标记和文件命名约定来区分单元测试和集成测试。

单元测试：不需要外部数据库。make test 命令会显式禁用数据库驱动 Makefile:29。

    pytest tests/ -m "not integration"

集成测试：需要活动的数据库连接，通过文件名中的 _int 后缀标识 CLAUDE.md:92。

    # 首先设置必要的环境变量（参见 CONTRIBUTING.md:81-90）
    pytest tests/ -k "_int"

数据库集成流程 下图展示了负责数据库通信的代码实体与实际服务实例之间的关联关系。

Graphiti · 运行测试 · 图 1

来源：Makefile:29，CLAUDE.md:92，CLAUDE.md:105-110，.github/workflows/unit_tests.yml:55-63

可观测性设置（可选）

为了调试复杂的图操作，你可以启用 OpenTelemetry 追踪。这需要安装 tracing 扩展 pyproject.toml:38。

安装 SDK：

    uv sync --extra tracing

使用追踪器初始化 Graphiti：

将 tracer 实例传递给 Graphiti 构造函数 OTEL_TRACING.md:26-32。

追踪实现流程 此图将高层 Graphiti API 调用与底层的 OpenTelemetry 检测关联起来。

Graphiti · 可观测性设置（可选） · 图 2

来源：pyproject.toml:38，OTEL_TRACING.md:26-32

代码质量标准

CI 管线强制执行严格的质量检查，在提交拉取请求（PR）之前必须通过：

类型检查：核心库使用 Pyright，并设置 typeCheckingMode = "basic" pyproject.toml:101-105。

运行命令：make lint Makefile:25。

代码检查：Ruff 强制执行 100 字符行宽限制，并使用单引号 pyproject.toml:72-100。

它选择了 Pyflakes (F)、pycodestyle (E)、isort (I) 和 flake8-bugbear (B) 的规则 pyproject.toml:75-89。
运行命令：make format Makefile:18-20。

第三方集成模式：所有集成必须使用 TYPE_CHECKING 守卫模式，以保持核心库的轻量化。

来源：pyproject.toml:72-105，Makefile:18-20，Makefile:25