1 · 总览（Overview）

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

项目Graphiti 章节1 状态全文译文模块图谱与关系、系统架构、检索、召回与索引、界面与交互

项目要点页2.5 参考项目项目章节目录Graphiti DeepWiki 原始章节Overview 下一章2

源码线索

README.md
examples/quickstart/README.md
graphiti_core/graphiti.py
pyproject.toml
uv.lock

模块标签

图谱与关系
系统架构
检索、召回与索引
界面与交互
模型调用与提供方适配

中文译文

总览（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/1-overview

翻译时间：2026-05-27T08:44:47.028Z

翻译模型：deepseek-chat

原文字符数：8157

项目：Graphiti (graphiti)

---

概述

目的与范围

Graphiti 能够从非结构化数据流（称为"片段"）中实时构建和查询知识图谱。该框架会持续整合新信息，自动提取实体和关系，并通过显式的双时态时间追踪来处理矛盾。

核心差异化优势：

与传统检索增强生成（RAG）对比：Graphiti 提供持续的增量更新而非批量处理，并使用混合检索（语义 + 关键词 + 图遍历）而非仅向量搜索 README.md:46-56。
与 GraphRAG 对比：Graphiti 支持实时入库而非静态文档摘要，并使用时序边失效机制来解决矛盾 README.md:122-132。

来源：README.md:42-56、README.md:120-132

什么是上下文图谱？

Graphiti 中的上下文图谱是一种时序图谱，其中节点代表实体，边代表事实。每个事实都有一个有效时间窗口：它何时变为真，以及何时被取代。

双时态模型

Graphiti 为每条关系追踪四个时间维度：

created_at：数据首次被入库到系统中的时间 graphiti_core/nodes.py:51-59。
valid_at：事件或事实在现实世界中实际发生的时间 graphiti_core/utils/maintenance/graph_data_operations.py:97-100。
invalid_at：事实不再为真的时间（被新数据取代）。
expired_at：用于版本管理和逻辑删除的系统内部时间。

来源：README.md:65-74、graphiti_core/nodes.py:51-59、graphiti_core/utils/maintenance/graph_data_operations.py:97-100

系统架构

Graphiti 采用多层架构，将核心逻辑与特定的数据库和 AI 提供商解耦。

高层架构图

graph TB
    subgraph "接口层"
        CLI["直接 Python API<br/>(Graphiti 类)"]
        MCP["MCP 服务器<br/>(模型上下文协议)"]
        REST["FastAPI REST 服务"]
    end

    subgraph "核心编排"
        G_CORE["Graphiti 编排器<br/>graphiti_core/graphiti.py"]
        SEARCH_SYS["搜索与检索系统<br/>graphiti_core/search/search.py"]
        PIPELINE["数据处理管线<br/>graphiti_core/utils/maintenance/"]
    end

    subgraph "提供商抽象层（插件架构）"
        DRIVER_ABC["GraphDriver 抽象基类<br/>graphiti_core/driver/driver.py"]
        LLM_ABC["LLMClient 抽象基类<br/>graphiti_core/llm_client.py"]
        EMB_ABC["EmbedderClient 抽象基类<br/>graphiti_core/embedder.py"]
    end

    subgraph "存储与 AI 后端"
        DB_NEO["Neo4j / FalkorDB<br/>Kuzu / Neptune"]
        LLM_PROV["OpenAI / Anthropic<br/>Gemini / Groq"]
        EMB_PROV["Voyage / SentenceTransformers<br/>OpenAI"]
    end

    CLI --> G_CORE
    MCP --> G_CORE
    REST --> G_CORE

    G_CORE --> SEARCH_SYS
    G_CORE --> PIPELINE

    PIPELINE --> LLM_ABC
    SEARCH_SYS --> EMB_ABC

    G_CORE --> DRIVER_ABC
    DRIVER_ABC --> DB_NEO
    LLM_ABC --> LLM_PROV
    EMB_ABC --> EMB_PROV

来源：graphiti_core/graphiti.py:137-187、graphiti_core/driver/driver.py:29-29、README.md:138-160

关键特性

1. 混合检索系统

Graphiti.search() 方法 graphiti_core/graphiti.py:62-63 结合了多种策略，以确保高召回率和高精度的结果：

语义搜索：对实体/边嵌入向量进行向量相似度匹配。
关键词搜索：对名称和摘要进行 BM25 全文搜索。
图遍历：通过关系查找连接的上下文。
重排序：支持倒数排序融合（RRF）、交叉编码器和图距离重排序 graphiti_core/search/search_config_recipes.py:64-68。

来源：examples/quickstart/README.md:76-78、graphiti_core/graphiti.py:62-63、graphiti_core/search/search_config_recipes.py:64-68

2. 多提供商插件架构

Graphiti 通过核心库中定义的抽象基类支持多种后端。

数据库：Neo4j、FalkorDB、Kuzu 和 Amazon Neptune graphiti_core/graphiti.py:29-30。
大语言模型（LLM）：OpenAI、Anthropic、Google Gemini 和 Groq graphiti_core/graphiti.py:49-49。
嵌入向量模型：Voyage AI、Sentence Transformers 和 OpenAI graphiti_core/graphiti.py:40-40。

来源：pyproject.toml:27-38、graphiti_core/graphiti.py:26-59

3. 数据处理管线

当通过 add_episode() 添加一个片段时，会经历多阶段处理：

提取：大语言模型（LLM）通过 extract_nodes graphiti_core/utils/maintenance/node_operations.py:103-103 和 extract_edges graphiti_core/utils/maintenance/edge_operations.py:93-93 从文本中识别实体和关系。
解析：通过 resolve_extracted_nodes graphiti_core/utils/maintenance/node_operations.py:104-104 和 resolve_extracted_edges graphiti_core/utils/maintenance/edge_operations.py:95-95 对节点和边进行去重。
矛盾检测：与现有事实矛盾的新事实会触发时序失效。

来源：README.md:120-132、graphiti_core/graphiti.py:101-105

代码实体空间映射

此图将高层系统组件映射到实现它们的特定类和文件。

graph TD
    subgraph "代码入口点"
        G_CLASS["Graphiti 类<br/>graphiti_core/graphiti.py"]
    end

    subgraph "数据模型"
        NODE_BASE["Node 抽象基类<br/>graphiti_core/nodes.py"]
        ENT_NODE["EntityNode<br/>graphiti_core/nodes.py"]
        EP_NODE["EpisodicNode<br/>graphiti_core/nodes.py"]
        EDGE_BASE["Edge 抽象基类<br/>graphiti_core/edges.py"]
        ENT_EDGE["EntityEdge<br/>graphiti_core/edges.py"]
    end

    subgraph "数据库驱动"
        NEO_DRV["Neo4jDriver<br/>graphiti_core/driver/neo4j_driver.py"]
        DRV_BASE["GraphDriver 抽象基类<br/>graphiti_core/driver/driver.py"]
    end

    subgraph "搜索逻辑"
        S_FILT["SearchFilters<br/>graphiti_core/search/search_filters.py"]
        S_RECIPE["搜索配置<br/>graphiti_core/search/search_config_recipes.py"]
        S_FUNC["search 函数<br/>graphiti_core/search/search.py"]
    end

    G_CLASS -->|管理| NODE_BASE
    G_CLASS -->|管理| EDGE_BASE
    G_CLASS -->|调用| S_FUNC
    S_FUNC -->|使用| S_FILT
    G_CLASS -->|初始化| DRV_BASE
    DRV_BASE <|-- NEO_DRV

    S_FILT -->|由...解析| S_RECIPE

来源：graphiti_core/graphiti.py:137-151、graphiti_core/nodes.py:51-59、graphiti_core/edges.py:31-39、graphiti_core/search/search.py:62-63

组件摘要

组件	代码实体	描述
核心客户端	`Graphiti` `graphiti_core/graphiti.py:137`	`add_episode` 和 `search` 的主要入口点。
节点模型	`EntityNode` `graphiti_core/nodes.py:53`	表示人物、产品或概念，并带有摘要。
边模型	`EntityEdge` `graphiti_core/edges.py:34`	表示带有时间有效性的事实/关系。
搜索配置	`SearchFilters` `graphiti_core/search/search_filters.py:69`	定义查询的节点标签、边类型和日期范围。
数据库接口	`GraphDriver` `graphiti_core/driver/driver.py:29`	用于 Cypher/Gremlin 查询生成的抽象层。

来源：README.md:77-83、graphiti_core/graphiti.py:137-151、graphiti_core/nodes.py:51-59、graphiti_core/edges.py:31-39