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

4 · 系统架构（System Architecture）

时序知识图谱与动态事实记忆 · 本章是 Graphiti DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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
翻译时间：2026-05-27T08:45:03.687Z
翻译模型：deepseek-chat
原文字符数：16364
项目：Graphiti (graphiti)

---

系统架构

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

  • 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）提供者和嵌入向量服务可以独立替换。

三层架构

graph TB
    subgraph tier1["第一层：用户接口层"]
        Graphiti["Graphiti 类<br/>(graphiti.py:137)"]
        NodeNamespace["NodeNamespace<br/>(namespaces.py)"]
        EdgeNamespace["EdgeNamespace<br/>(namespaces.py)"]
    end

    subgraph tier2["第二层：服务编排"]
        GraphitiClients["GraphitiClients<br/>(graphiti_types.py:42)"]
        EpisodeProcessor["剧集处理<br/>extract_nodes()<br/>extract_edges()<br/>(utils/maintenance/)"]
        SearchEngine["搜索引擎<br/>search()<br/>(search/search.py)"]
        CommunityBuilder["社区构建器<br/>build_communities()<br/>(utils/maintenance/community_operations.py:87)"]
    end

    subgraph tier3["第三层：可插拔提供者"]
        LLMClient["LLMClient<br/>OpenAIClient<br/>AnthropicClient<br/>GeminiClient<br/>GroqClient"]
        EmbedderClient["EmbedderClient<br/>OpenAIEmbedder<br/>VoyageAIEmbedder<br/>GeminiEmbedder"]
        CrossEncoderClient["CrossEncoderClient<br/>OpenAIRerankerClient<br/>GeminiRerankerClient"]
        GraphDriver["GraphDriver<br/>Neo4jDriver<br/>FalkorDriver<br/>KuzuDriver<br/>NeptuneDriver"]
    end

    Graphiti --> GraphitiClients
    Graphiti --> NodeNamespace
    Graphiti --> EdgeNamespace

    GraphitiClients --> LLMClient
    GraphitiClients --> EmbedderClient
    GraphitiClients --> CrossEncoderClient
    GraphitiClients --> GraphDriver

    EpisodeProcessor --> GraphitiClients
    SearchEngine --> GraphitiClients
    CommunityBuilder --> GraphitiClients

    Graphiti --> EpisodeProcessor
    Graphiti --> SearchEngine
    Graphiti --> CommunityBuilder

来源：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）。

构造参数
参数类型默认值用途
uri`str \None`—图数据库 URI（当 graph_driver 为 None 时使用）
user`str \None`—数据库用户名
password`str \None`—数据库密码
llm_client`LLMClient \None`OpenAIClient()用于实体/边提取和去重的大语言模型（LLM）
embedder`EmbedderClient \None`OpenAIEmbedder()向量嵌入服务
cross_encoder`CrossEncoderClient \None`OpenAIRerankerClient()用于搜索结果评分的重排序器
store_raw_episode_contentboolTrue是否在图谱中持久化原始剧集文本
graph_driver`GraphDriver \None`Neo4jDriver(...)直接注入预配置的驱动
max_coroutines`int \None`环境变量 SEMAPHORE_LIMIT异步操作的并发上限
tracer`Tracer \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 构造时注入，使得提供者可以独立替换。

提供者接口映射

graph LR
    subgraph interfaces["抽象接口"]
        LLMClient["LLMClient<br/>(llm_client/client.py)"]
        EmbedderClient["EmbedderClient<br/>(embedder/client.py)"]
        CrossEncoderClient["CrossEncoderClient<br/>(cross_encoder/client.py)"]
        GraphDriver["GraphDriver<br/>(driver/driver.py:90)"]
    end

    subgraph llm_impls["大语言模型（LLM）实现"]
        OpenAIClient["OpenAIClient<br/>(llm_client/openai_client.py)"]
        AnthropicClient["AnthropicClient<br/>(llm_client/anthropic_client.py)"]
        GeminiClient["GeminiClient<br/>(llm_client/gemini_client.py)"]
        GroqClient["GroqClient<br/>(llm_client/groq_client.py)"]
    end

    subgraph emb_impls["嵌入器实现"]
        OpenAIEmbedder["OpenAIEmbedder<br/>(embedder/openai.py)"]
        VoyageAIEmbedder["VoyageAIEmbedder<br/>(embedder/voyageai.py)"]
        GeminiEmbedder["GeminiEmbedder<br/>(embedder/gemini.py)"]
    end

    subgraph db_impls["数据库实现"]
        Neo4jDriver["Neo4jDriver<br/>(driver/neo4j_driver.py:60)"]
        FalkorDriver["FalkorDriver<br/>(driver/falkordb_driver.py:110)"]
        KuzuDriver["KuzuDriver<br/>(driver/kuzu_driver.py)"]
        NeptuneDriver["NeptuneDriver<br/>(driver/neptune_driver.py)"]
    end

    LLMClient -.->|实现| OpenAIClient
    LLMClient -.->|实现| AnthropicClient
    LLMClient -.->|实现| GeminiClient
    LLMClient -.->|实现| GroqClient

    EmbedderClient -.->|实现| OpenAIEmbedder
    EmbedderClient -.->|实现| VoyageAIEmbedder
    EmbedderClient -.->|实现| GeminiEmbedder

    GraphDriver -.->|实现| Neo4jDriver
    GraphDriver -.->|实现| FalkorDriver
    GraphDriver -.->|实现| KuzuDriver
    GraphDriver -.->|实现| NeptuneDriver
角色抽象基类默认实现文件路径
大语言模型（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 架构

graph TD
    subgraph tier1 ["第一层：核心抽象基类（driver/driver.py）"]
        GraphDriver["GraphDriver (抽象基类)<br/>(driver.py:90)"]
        GraphProvider["GraphProvider (枚举):<br/>NEO4J, FALKORDB, KUZU, NEPTUNE<br/>(driver.py:59)"]
        GraphDriverSession["GraphDriverSession (抽象基类)<br/>(driver.py:66)"]
        QueryExecutor["QueryExecutor (协议)<br/>(driver/query_executor.py)"]
    end

    subgraph tier2 ["第二层：操作抽象基类（driver/operations/）"]
        NodeOps["EntityNodeOperations<br/>EpisodeNodeOperations<br/>CommunityNodeOperations<br/>SagaNodeOperations"]
        EdgeOps["EntityEdgeOperations<br/>EpisodicEdgeOperations<br/>CommunityEdgeOperations<br/>HasEpisodeEdgeOperations<br/>NextEpisodeEdgeOperations"]
        SvcOps["SearchOperations<br/>GraphMaintenanceOperations"]
    end

    subgraph tier3 ["第三层：具体驱动"]
        Neo4jDriver["Neo4jDriver<br/>(neo4j_driver.py:60)"]
        FalkorDriver["FalkorDriver<br/>(falkordb_driver.py:110)"]
        KuzuDriver["KuzuDriver"]
        NeptuneDriver["NeptuneDriver"]
    end

    GraphDriver --> Neo4jDriver
    GraphDriver --> FalkorDriver
    GraphDriver --> KuzuDriver
    GraphDriver --> NeptuneDriver
    Neo4jDriver --> |"通过 @property 暴露"| tier2
    FalkorDriver --> |"通过 @property 暴露"| tier2
操作接口

每个具体驱动在 __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）编排了一个多阶段管线。

剧集处理管线及函数调用

flowchart TD
    A["Graphiti.add_episode()<br/>(graphiti.py:788)"] --> B["validate_entity_types()<br/>validate_excluded_entity_types()<br/>(helpers.py:189)"]
    B --> C["解析 group_id<br/>按需克隆驱动<br/>(graphiti.py:881)"]

    C --> D["阶段 1：上下文检索"]
    D --> E["retrieve_episodes()<br/>(utils/maintenance/graph_data_operations.py:99)"]
    E --> F["创建 EpisodicNode<br/>(nodes.py:55)"]

    F --> G["阶段 2：节点提取与解析"]
    G --> H["extract_nodes()<br/>(utils/maintenance/node_operations.py:103)"]
    H --> I["resolve_extracted_nodes()<br/>(utils/maintenance/node_operations.py:104)"]

    I --> J["阶段 3：边提取与解析"]
    J --> K["extract_edges()<br/>(utils/maintenance/edge_operations.py:93)"]
    K --> L["resolve_edge_pointers()<br/>(utils/bulk_utils.py:82)"]
    L --> M["resolve_extracted_edges()<br/>(utils/maintenance/edge_operations.py:95)"]

    M --> N["阶段 4：属性丰富"]
    N --> O["extract_attributes_from_nodes()<br/>(utils/maintenance/node_operations.py:102)"]

    O --> P["阶段 5：持久化"]
    P --> Q["build_episodic_edges()<br/>(utils/maintenance/edge_operations.py:92)"]
    Q --> R["add_nodes_and_edges_bulk()<br/>(utils/bulk_utils.py:78)"]

    R --> S{"提供了 saga？"}
    S -->|是| T["_get_or_create_saga()<br/>保存 HasEpisodeEdge<br/>保存 NextEpisodeEdge<br/>(graphiti.py:343)"]
    S -->|否| U{"update_communities？"}
    T --> U
    U -->|是| V["update_community()<br/>(utils/maintenance/community_operations.py:89)"]
    U -->|否| W["返回 AddEpisodeResults<br/>(graphiti.py:114)"]
    V --> W

来源：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()，该方法并发执行搜索策略并融合结果。

混合搜索管线

graph TB
    subgraph input["搜索输入"]
        query["query: str"]
        config["SearchConfig<br/>(search/search.py:62)"]
        filters["SearchFilters<br/>(search/search_filters.py:69)"]
    end

    subgraph methods["并发搜索方法"]
        bm25["fulltext_search()<br/>通过数据库索引的 BM25"]
        vector["vector_search()<br/>余弦相似度"]
        bfs["bfs_search()<br/>图遍历"]
    end

    subgraph fusion["结果融合"]
        rrf["reciprocal_rank_fusion()"]
        mmr["maximal_marginal_relevance()"]
    end

    subgraph rerank["重排序策略"]
        cross_encoder["rerank_with_cross_encoder()<br/>大语言模型（LLM）相关性评分"]
    end

    subgraph output["搜索输出"]
        SearchResults["SearchResults<br/>(search/search_config.py:63)"]
    end

    query --> bm25
    query --> vector
    query --> bfs

    bm25 --> rrf
    vector --> rrf
    bfs --> rrf

    rrf --> mmr
    mmr --> cross_encoder
    cross_encoder --> SearchResults

来源：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