agentic_huge_data_base / wiki
页面 Graphiti · 4 系统架构·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 4

4 · 系统架构（System Architecture）

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

项目Graphiti 章节4 状态全文译文 模块模型调用与提供方适配、界面与交互、系统架构、检索、召回与索引
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节System Architecture 上一章3.4 下一章4.1
源码线索
  • README.md
  • examples/quickstart/README.md
  • graphiti_core/driver/driver.py
  • graphiti_core/driver/falkordb_driver.py
  • graphiti_core/driver/neo4j_driver.py
  • graphiti_core/graphiti.py
  • graphiti_core/helpers.py
模块标签
  • 模型调用与提供方适配
  • 界面与交互
  • 系统架构
  • 检索、召回与索引
  • 安装与启动

章节正文

系统架构

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/4-system-architecture

系统架构

相关源文件

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

  • README.md
  • examples/quickstart/README.md
  • graphiti_core/driver/driver.py
  • graphiti_core/driver/falkordb_driver.py
  • graphiti_core/driver/neo4j_driver.py
  • graphiti_core/graphiti.py
  • graphiti_core/helpers.py

本文档涵盖了 graphiti-core 的高层架构：核心的 Graphiti 编排器类、GraphitiClients 服务容器、可插拔的 AI 提供者和数据库驱动系统，以及从剧集入库到图谱存储和检索的完整数据流。

有关各个子系统的详细 API 文档，请参见：Graphiti Core 客户端、数据模型与模式、搜索与检索系统、多提供者插件架构、数据库抽象层。关于逐步骤的剧集处理管线，请参见数据处理管线。

架构总览

Graphiti 采用三层架构，用户面向的操作通过 Graphiti 编排器类（graphiti_core/graphiti.py:137-151）流转，该类协调知识提取管线、搜索操作和社区检测。所有 AI 服务调用和数据库操作都通过可插拔的提供者接口路由，使得图谱后端、大语言模型（LLM）提供者和嵌入向量服务可以独立替换。

三层架构

Graphiti · 架构总览 · 图 1
Graphiti · 架构总览 · 图 1

来源：graphiti_core/graphiti.py:137-246、graphiti_core/graphiti_types.py:42-42、graphiti_core/utils/maintenance/node_operations.py:101-105、graphiti_core/utils/maintenance/edge_operations.py:91-96、graphiti_core/utils/maintenance/community_operations.py:86-90

Graphiti 编排器

Graphiti（graphiti_core/graphiti.py:137）是顶层类。构造时接受直接连接凭证（用于默认的 Neo4jDriver），或通过 graph_driver 参数传入预配置的 GraphDriver 实例（graphiti_core/graphiti.py:147）。如果未提供服务客户端，所有服务客户端默认使用 OpenAI 支持的实现（graphiti_core/graphiti.py:166-174）。

构造参数
参数类型默认值用途
uristr | None—图数据库 URI（当 graph_driver 为 None 时使用）
userstr | None—数据库用户名
passwordstr | None—数据库密码
llm_clientLLMClient | NoneOpenAIClient()用于实体/边提取和去重的大语言模型（LLM）
embedderEmbedderClient | NoneOpenAIEmbedder()向量嵌入服务
cross_encoderCrossEncoderClient | NoneOpenAIRerankerClient()用于搜索结果评分的重排序器
store_raw_episode_contentboolTrue是否在图谱中持久化原始剧集文本
graph_driverGraphDriver | NoneNeo4jDriver(...)直接注入预配置的驱动
max_coroutinesint | None环境变量 SEMAPHORE_LIMIT异步操作的并发上限
tracerTracer | None无操作OpenTelemetry 追踪器实例
trace_span_prefixstr'graphiti'应用于所有追踪跨度名称的前缀

来源：graphiti_core/graphiti.py:138-186、graphiti_core/helpers.py:38-38

关键公共方法
方法返回类型描述
add_episode(...)AddEpisodeResults入库一个剧集；提取、解析并持久化实体和关系
add_episode_bulk(...)AddBulkEpisodeResults批量入库 RawEpisode 对象列表，共享去重逻辑
search(...)SearchResults混合搜索，返回边、节点、剧集和社区
retrieve_episodes(...)list[EpisodicNode]获取相对于参考时间的最近 n 个剧集
build_indices_and_constraints()None创建数据库索引和约束（在设置期间运行一次）
close()None优雅关闭底层图数据库驱动连接

来源：graphiti_core/graphiti.py:114-130、graphiti_core/graphiti.py:311-342、graphiti_core/graphiti.py:393-426、graphiti_core/graphiti.py:735-786、graphiti_core/graphiti.py:788-806

GraphitiClients 容器

GraphitiClients（graphiti_core/graphiti_types.py:42）是一个数据类，将服务客户端打包成一个对象，传递给所有内部管线函数。这消除了调用栈中冗余的参数传递。

# 在 Graphiti.__init__ 中创建
self.clients = GraphitiClients(
    driver=self.driver,           # GraphDriver 实例
    llm_client=self.llm_client,   # LLMClient 实例
    embedder=self.embedder,       # EmbedderClient 实例
    cross_encoder=self.cross_encoder,  # CrossEncoderClient 实例
    tracer=self.tracer,           # Tracer 实例
)

使用 GraphitiClients 的函数：

  • extract_nodes(clients, ...) - graphiti_core/utils/maintenance/node_operations.py:103
  • resolve_extracted_nodes(clients, ...) - graphiti_core/utils/maintenance/node_operations.py:104
  • extract_edges(clients, ...) - graphiti_core/utils/maintenance/edge_operations.py:93
  • resolve_extracted_edges(clients, ...) - graphiti_core/utils/maintenance/edge_operations.py:95
  • search(clients, ...) - graphiti_core/search/search.py:62

来源：graphiti_core/graphiti.py:232-238、graphiti_core/graphiti_types.py:42-42

可插拔提供者系统

所有服务接口都定义为抽象基类。具体实现会在 Graphiti 构造时注入，使得提供者可以独立替换。

提供者接口映射

Graphiti · 可插拔提供者系统 · 图 2
Graphiti · 可插拔提供者系统 · 图 2
角色抽象基类默认实现文件路径
大语言模型（LLM）推理LLMClientOpenAIClientgraphiti_core/llm_client/openai_client.py
向量嵌入EmbedderClientOpenAIEmbeddergraphiti_core/embedder/openai.py
搜索重排序CrossEncoderClientOpenAIRerankerClientgraphiti_core/cross_encoder/openai_reranker_client.py
图数据库GraphDriverNeo4jDrivergraphiti_core/driver/neo4j_driver.py:60

来源：graphiti_core/graphiti.py:203-238、graphiti_core/driver/driver.py:59-64、graphiti_core/driver/driver.py:90-96

数据库抽象层

图数据库层采用三层架构。

GraphDriver 架构

Graphiti · 数据库抽象层 · 图 3
Graphiti · 数据库抽象层 · 图 3
操作接口

每个具体驱动在 __init__ 中实例化操作类，并通过 @property 访问器暴露它们。例如，Neo4jDriver 实例化 Neo4jEntityNodeOperations 和其他类（graphiti_core/driver/neo4j_driver.py:79-89），并通过 entity_node_ops 等属性暴露它们（graphiti_core/driver/neo4j_driver.py:108-110）。

类别抽象基类
节点操作EntityNodeOperations、EpisodeNodeOperations、CommunityNodeOperations、SagaNodeOperations
边操作EntityEdgeOperations、EpisodicEdgeOperations、CommunityEdgeOperations、HasEpisodeEdgeOperations、NextEpisodeEdgeOperations
搜索与维护SearchOperations、GraphMaintenanceOperations

来源：graphiti_core/driver/driver.py:59-212、graphiti_core/driver/neo4j_driver.py:60-150、graphiti_core/driver/falkordb_driver.py:110-160

剧集入库数据流

add_episode 方法（graphiti_core/graphiti.py:788）编排了一个多阶段管线。

剧集处理管线及函数调用

Graphiti · 剧集入库数据流 · 图 4
Graphiti · 剧集入库数据流 · 图 4

来源：graphiti_core/graphiti.py:788-1000、graphiti_core/utils/maintenance/node_operations.py:101-105、graphiti_core/utils/maintenance/edge_operations.py:91-96、graphiti_core/utils/bulk_utils.py:76-84

搜索架构

Graphiti.search_() 方法委托给 graphiti_core/search/search.py 中的 search()，该方法并发执行搜索策略并融合结果。

混合搜索管线

Graphiti · 搜索架构 · 图 5
Graphiti · 搜索架构 · 图 5

来源：graphiti_core/search/search.py:62-62、graphiti_core/search/search_config.py:63-63、graphiti_core/search/search_filters.py:69-69

并发模型

所有并发操作由 semaphore_gather（graphiti_core/helpers.py:123-133）协调。该函数将 asyncio.gather 与 asyncio.Semaphore 结合使用，信号量上限由 SEMAPHORE_LIMIT（graphiti_core/helpers.py:38）或构造参数 max_coroutines（graphiti_core/graphiti.py:180-182）决定。

来源：graphiti_core/helpers.py:123-133、graphiti_core/helpers.py:38-38、graphiti_core/graphiti.py:180-182