依赖与可选特性
依赖项与可选特性
相关源文件
本章引用的主要源码文件：
mcp_server/pyproject.tomlmcp_server/uv.lockpyproject.tomlserver/pyproject.tomlserver/uv.lockuv.lock
本文档描述了 Graphiti 的依赖结构，包括核心依赖、可选特性包以及用于可重现构建的锁文件机制。安装后如需配置特定提供方，请参阅提供方配置。运行时环境变量请参见环境变量与设置。
概述
Graphiti 采用模块化依赖架构，核心功能仅需少量依赖，而附加特性（如替代的大语言模型提供方、图数据库、嵌入向量器）则作为可选扩展安装。这种设计在支持多种提供方组合的同时，最小化了基础安装体积。
该项目要求 Python 3.10 或更高版本，但排除 Python 4.x pyproject.toml:12-12。依赖版本通过 pyproject.toml pyproject.toml:1-105 管理，精确解析版本则锁定在 uv.lock uv.lock:1-10 中。
来源： pyproject.toml:1-105, uv.lock:1-10
核心依赖
以下包是所有 Graphiti 安装所必需的，提供了基础框架能力：
| 包名 | 最低版本 | 用途 |
|---|---|---|
pydantic | 2.11.5 | 数据校验与模式定义 pyproject.toml:14-14 |
neo4j | 5.26.0 | 默认图数据库驱动 pyproject.toml:15-15 |
openai | 1.91.0 | 默认大语言模型客户端与嵌入向量器 pyproject.toml:16-16 |
tenacity | 9.0.0 | 大语言模型和数据库调用的重试逻辑 pyproject.toml:17-17 |
numpy | 1.0.0 | 嵌入向量的向量运算 pyproject.toml:18-18 |
python-dotenv | 1.0.1 | 环境变量管理 pyproject.toml:19-19 |
posthog | 3.0.0 | 匿名使用分析 pyproject.toml:20-20 |
这些依赖会随 pip install graphiti-core 或 uv add graphiti-core 自动安装。
来源： pyproject.toml:13-21
可选依赖组（扩展）
Graphiti 提供了可选依赖组，用于启用特定提供方或特性。使用方括号标记进行安装：
pip install graphiti-core[anthropic,groq,google-genai]
uv add "graphiti-core[falkordb,voyageai]"大语言模型提供方扩展
大语言模型提供方通过 LLMClient 接口进行抽象。安装对应扩展后，即可使用相应的提供方客户端。
大语言模型提供方映射
| 扩展名 | 包含的包 | 启用功能 |
|---|---|---|
anthropic | anthropic>=0.49.0 | AnthropicClient pyproject.toml:28-28 |
groq | groq>=0.2.0 | GroqClient pyproject.toml:29-29 |
google-genai | google-genai>=1.62.0 | GeminiClient, GeminiEmbedder pyproject.toml:30-30 |
来源： pyproject.toml:28-30
图数据库扩展
图数据库通过 GraphDriver 抽象层提供支持。
数据库驱动映射
| 扩展名 | 包含的包 | 启用功能 |
|---|---|---|
kuzu | kuzu>=0.11.3 | KuzuDriver pyproject.toml:31-31 |
falkordb | falkordb>=1.1.2,<2.0.0 | FalkorDriver pyproject.toml:32-32 |
neptune | langchain-aws>=0.2.29, opensearch-py>=3.0.0, boto3>=1.39.16 | NeptuneDriver pyproject.toml:37-37 |
neo4j-opensearch | boto3>=1.39.16, opensearch-py>=3.0.0 | Neo4j 的混合搜索 pyproject.toml:35-35 |
来源： pyproject.toml:31-37
专用特性扩展
| 扩展名 | 包含的包 | 用途 |
|---|---|---|
voyageai | voyageai>=0.2.3 | VoyageEmbedderClient pyproject.toml:33-33 |
sentence-transformers | sentence-transformers>=3.2.1 | 本地嵌入向量模型 pyproject.toml:36-36 |
gliner2 | gliner2>=1.2.0 | 实体识别（Python 3.11+） pyproject.toml:34-34 |
tracing | opentelemetry-api, opentelemetry-sdk | 可观测性 pyproject.toml:38-38 |
来源： pyproject.toml:33-38
依赖锁文件 (uv.lock)
uv.lock 文件通过锁定所有传递依赖的精确版本，提供了可重现构建能力。该文件由 uv 包管理器管理 uv.lock:1-2。
锁文件结构
关键部分：
- 元数据
uv.lock:1-10：锁版本、Python 要求和解析标记。 - 包条目
uv.lock:12-55：每个[[package]]块指定了名称、版本、来源和依赖项。
Python 版本标记
锁文件使用解析标记来处理因 Python 版本而异的依赖项 uv.lock:4-10：
python_full_version >= '3.14'uv.lock:5-5python_full_version < '3.11'（例如，用于async-timeoutuv.lock:28-28）
来源： uv.lock:1-55
MCP 服务器依赖
MCP（模型上下文协议）服务器在 mcp_server/pyproject.toml mcp_server/pyproject.toml:1-14 中有自己的依赖规范。值得注意的是，它默认将 graphiti-core[falkordb] 作为依赖包含在内 mcp_server/pyproject.toml:10-10。
[project]
name = "mcp-server"
version = "1.0.2"
dependencies = [
"mcp>=1.9.4",
"openai>=1.91.0",
"graphiti-core[falkordb]>=0.28.2",
"pydantic-settings>=2.0.0",
"pyyaml>=6.0",
"typing-extensions>=4.0.0",
]MCP 可选依赖
| 扩展 | 包含的包 | 用途 |
|---|---|---|
azure | azure-identity>=1.21.0 | Azure 认证 mcp_server/pyproject.toml:17-19 |
providers | google-genai, anthropic, groq, voyageai, sentence-transformers | 替代 AI 提供方 mcp_server/pyproject.toml:20-26 |
来源： mcp_server/pyproject.toml:1-26
图服务依赖
定义在 server/ 目录下的基于 FastAPI 的 REST 服务使用了以下核心依赖：
| 包名 | 最低版本 | 用途 |
|---|---|---|
fastapi | 0.115.0 | Web 框架 server/pyproject.toml:11-11 |
graphiti-core | 0.28.2 | 核心库 server/pyproject.toml:12-12 |
pydantic-settings | 2.4.0 | 配置管理 server/pyproject.toml:13-13 |
uvicorn | 0.44.0 | ASGI 服务器 server/pyproject.toml:14-14 |
httpx | 0.28.1 | 异步 HTTP 客户端 server/pyproject.toml:15-15 |
来源： server/pyproject.toml:10-16
总结
Graphiti 的依赖架构在简洁性和灵活性之间取得了平衡：
- 核心包提供基础功能（Neo4j + OpenAI）。
- 可选扩展支持替代数据库（Kuzu、FalkorDB、Neptune）和大语言模型（Anthropic、Groq、Gemini）。
- uv.lock确保所有环境中的可重现构建。
- MCP 服务器通过捆绑常用提供方并默认使用
falkordbmcp_server/pyproject.toml:10-10简化了部署。
来源： pyproject.toml:1-105, mcp_server/pyproject.toml:1-74, server/pyproject.toml:1-32