1 · 总览（Overview）

总览

概述

相关源文件

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

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

Graphiti 是一个用于构建和查询时序知识图谱的 Python 框架，专为在动态环境中运行的 AI 智能体设计。与静态知识图谱不同，Graphiti 会追踪事实随时间的变化，维护数据来源的溯源信息，并同时支持预设和习得的本体。

目的与范围

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

核心差异化优势：

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

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

什么是上下文图谱？

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

双时态模型

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

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

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

系统架构

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

高层架构图

来源：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() 添加一个片段时，会经历多阶段处理：

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

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

代码实体空间映射

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

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

组件摘要

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