Graphiti是一个用于构建和查询时间感知知识图谱的开源框架。它专为在动态环境中运行的AI智能体设计，能够持续整合用户交互、结构化与非结构化企业数据以及外部信息，形成一个连贯且可查询的图谱。
项目地址：https://github.com/getzep/graphiti
一、技术原理
Graphiti的技术原理围绕动态知识图谱构建与时间感知能力展开，核心设计包括以下关键机制：
（一）双时间轴建模与冲突解决
Graphiti采用事件发生时间（有效时间）和数据摄取时间（事务时间）的双时间模型，明确记录每个事实的时间维度。当新数据与现有知识冲突时，通过LLM驱动的边失效机制自动处理：
1.语义冲突检测：利用LLM分析新事实与图谱中现有关系的语义差异，识别潜在冲突（如用户偏好变化）。
2.动态标记失效：将旧信息标记为失效状态，并记录失效时间戳，确保历史查询仍可追溯原状态。
3.时间旅行查询：支持精确查询特定时间点的知识状态，例如“用户在2025年7月1日前的偏好”。
这种设计使Graphiti能够处理复杂时间关系（如“项目实际启动时间早于用户提及时间”），并保持数据的时序一致性。
（二）三层知识图谱架构
Graphiti采用分层设计构建知识图谱，模拟人类记忆模式：
1.情节子图（Episode Subgraph）
存储原始输入数据（如对话文本、JSON文档），保留完整上下文。通过情节边连接到语义实体，确保可追溯数据来源。
2.语义实体子图（Semantic Entity Subgraph）
利用LLM从情节中提取实体（如人物、产品）和关系（如“喜欢”“属于”），形成结构化知识网络。实体节点包含属性摘要，支持快速检索。
3.社区子图（Community Subgraph）
通过标签传播算法对实体进行聚类，形成高层次概念（如“运动品牌”）。社区边连接语义实体与社区，支持抽象推理（如“Adidas属于运动品牌社区”）。
分层架构既保留细节信息，又支持从具体事件到抽象概念的多层次查询。
（三）混合检索与重排序
Graphiti结合三种互补检索方法实现高效查询：
1.语义嵌入搜索
使用OpenAI/Gemini等模型生成文本向量，通过余弦相似度匹配语义相关内容。
2.BM25关键词搜索
对文本内容进行关键词匹配，快速定位包含特定术语的节点或边。
3.图遍历搜索
基于图结构关系（如“用户→喜欢→品牌”）进行路径查询，支持复杂关系推理。
检索结果通过RRF（逆排名融合）和MMR（最大边际相关）算法重排序，平衡相关性与多样性。例如，优先返回语义相似且在图中距离更近的节点。
（ 四）实时增量更新与事件驱动
Graphiti采用事件流处理机制，将数据摄入视为离散事件（Episode）：
1.增量式构建
新数据无需批量重新计算，直接以事件形式添加到图谱中，通过LLM实时提取实体和关系。
2.异步处理
事件解析与图谱更新异步执行，确保低延迟响应。例如，用户对话可立即存储为情节，同时后台异步提取语义信息。
3.并行化优化
支持多线程或分布式任务分发，处理大规模数据流时通过并行计算提升吞吐量。
（五）LLM驱动的动态知识生成
Graphiti深度集成LLM实现智能化处理：
1.实体与关系提取
通过结构化输出提示（如JSON格式）引导LLM从非结构化文本中提取实体、关系及属性，例如从“用户反馈鞋子损坏”中识别“用户→损坏→鞋子”关系。
2.语义冲突检测
LLM分析新事实与现有知识的语义差异，判断是否触发边失效流程。例如，当用户从“喜欢Adidas”变为“偏好Nike”时，旧关系自动失效。
3.嵌入生成
利用LLM生成文本的高维向量表示，用于语义搜索和相似性计算，替代传统的TF-IDF等方法。
（六）可扩展的存储与查询优化
Graphiti以Neo4j为存储后端，结合以下优化提升性能：
1.索引与约束
为时间戳、实体类型等字段创建索引，加速时间范围查询和类型过滤。
2.混合存储模型
情节数据以原始格式存储，语义实体和关系以图结构存储，兼顾灵活性与查询效率。
3.查询计划优化
利用Neo4j的Cypher查询优化器，自动生成高效执行计划，例如合并路径查询与属性过滤。
（七）自定义本体与领域建模
通过Pydantic模型定义自定义实体类型和关系，开发者可灵活扩展本体：
1.动态实体定义
例如，在医疗场景中定义“患者”“诊断”等实体，并关联“患有”“处方”等关系。
2.属性约束
通过模型字段定义实体属性的类型、长度等约束，确保数据一致性。
3.继承与扩展
支持实体类型继承，例如“运动鞋”继承“鞋子”的通用属性，同时添加“鞋底材质”等特定字段。
（八）三层架构与层次化推理
Graphiti的情节-语义-社区三层架构支持从原始数据到抽象概念的多层次分析：
1.情节子图保留对话、文档等原始输入，确保可追溯性；
2.语义子图构建实体关系网络，支持精确查询（如“用户购买过哪些产品”）；
3.社区子图通过聚类形成领域概念（如“高性价比品牌”），支持跨领域推理（如“推荐同类品牌”）。
这种设计使Graphiti既能处理细粒度数据，又能进行宏观趋势分析，适用于智能客服、推荐系统等复杂场景。
二、 核心功能
1.实时增量更新：无需批量重新计算，可立即集成新的数据集，能快速响应数据变化。
2.双时间数据模型：明确跟踪事件发生和摄取时间，支持精确的时点查询，例如可查询特定时刻系统所知的用户偏好等信息。
3.高效的混合检索：结合语义嵌入、关键词（BM25）和图遍历，实现低延迟查询，无需依赖LLM汇总，能快速从知识图谱中检索出所需信息。
3.自定义实体定义：通过简单的Pydantic模型支持灵活的本体创建和开发者定义的实体，可满足不同领域和业务场景的需求。
4.可扩展性：支持并行处理，能高效管理大规模数据集，适用于企业级应用场景，可应对大量数据的存储和处理需求。
三、使用方法
Graphiti的安装和使用相对简单。使用时需确保系统具备Neo4j 5.26或更高版本（用作嵌入存储后端），以及OpenAI API密钥（用于LLM推理和嵌入生成）。它提供了用户友好的界面来管理Neo4j实例和数据库，也可通过FastAPI构建的API服务，以RESTful接口方式与Graphiti API进行交互。
1.环境准备
- 安装Python：确保使用Python 3.10或更高版本。
- 安装图数据库：需安装Neo4j 5.26或更高版本作为嵌入存储后端，可通过Neo4j Desktop进行安装，方便管理实例和数据库。
- 获取API密钥：准备OpenAI API密钥用于LLM推理和嵌入生成，也可准备Google Gemini、Anthropic或Groq的API密钥以接入其他LLM提供商。
2.安装Graphiti
- 使用`pip`安装，命令为`pip install graphiti-core`。
- 若需安装特定LLM提供商支持，可使用如`pip install graphiti-core(anthropic)`（安装Anthropic支持）等命令，也可同时安装多个，如`pip install graphiti-core(anthropic,groq,google - genai)`。
3.连接数据库与初始化：参考项目中`examples/quickstart`目录下的快速入门示例，首先连接到Neo4j数据库，建立与图数据库的连接，然后初始化Graphiti索引和约束，设置必要的数据库结构以优化查询。
4.添加数据：将数据以“事件片段”（Episodes）的形式添加到知识图谱中，可添加文本和结构化JSON数据。例如，若有用户购买商品的数据，可将用户信息、商品信息及购买时间等以规定格式添加，构建知识图谱中的实体和关系。
5.执行查询：利用Graphiti的混合搜索功能查找关系，可结合语义、关键词和图遍历进行搜索。还能根据图距离重排搜索结果，根据节点在图中的接近程度优化搜索结果的相关性，也可使用预定义配方搜索节点。
6.集成与部署：Graphiti提供了模型上下文协议（MCP）服务器和基于FastAPI构建的REST服务。可通过Docker将MCP服务器与Neo4j一起部署，便于将Graphiti集成到AI助手工作流中，通过MCP协议让AI助手与Graphiti的知识图谱能力进行交互，实现事件管理、实体管理和关系处理等功能。
四、应用场景
1.智能客服与客户关系管理
Graphiti能够实时整合用户对话、历史工单、产品信息等多源数据，构建动态客户知识图谱，实现以下功能：
上下文感知服务：通过跟踪用户交互的时间线（如“用户在2025年7月10日反馈订单延迟”），客服机器人可自动关联历史问题，提供连贯回答。例如，当用户再次咨询同一订单时，系统能快速检索历史对话中的解决方案，避免重复沟通。
动态需求预测：结合用户行为数据（如浏览记录、购买频率），实时更新用户偏好模型。例如，电商客服可根据用户近期浏览的商品类型，主动推荐相关促销活动。
语义冲突处理：当用户偏好发生变化（如“从喜欢运动鞋转为偏好休闲鞋”），Graphiti通过LLM检测语义差异，自动标记旧关系为失效状态，确保推荐策略实时调整。
2.智能推荐系统
Graphiti的时间感知与混合检索能力，可精准捕捉用户兴趣的动态变化：
跨渠道行为分析：整合用户在APP、官网、社交媒体等多渠道的交互数据，构建“用户-商品-场景”关系网络。例如，根据用户近期健身相关搜索，推荐运动装备的同时关联线下活动信息。
时效性内容推荐：通过事件发生时间（如“2025年欧洲杯期间”）和数据摄取时间（如“最新赛事报道”）的双时间轴建模，优先推荐与当前热点相关的内容或商品。
动态偏好预测：利用社区子图聚类技术（如“高性价比品牌”），结合用户历史购买记录，预测潜在需求。例如，当某品牌进入用户偏好社区时，自动触发个性化推荐。
3.医疗健康与临床决策支持
Graphiti在医疗场景中可构建包含患者病历、医学指南、临床试验数据的动态知识网络：
实时病历分析：整合电子健康记录（EHR）、检查报告等结构化数据，以及医生笔记、患者描述等非结构化文本，通过LLM提取实体（如“糖尿病”“胰岛素剂量”）和关系（如“患者→服用→药物”），辅助医生快速诊断。
治疗方案优化：结合患者实时生理指标（如血糖值、心率）和历史治疗效果，通过图遍历分析相似病例，推荐个性化治疗路径。例如，识别“患者A的用药反应与患者B在2024年的情况相似”，调整药物剂量。
药物相互作用预警：通过社区子图关联药物知识库，实时监测处方中药物的潜在冲突。例如，当医生开具新药时，系统自动检索“药物X与药物Y在肾功能不全患者中存在相互作用”的历史案例。
4.金融风险评估与交易监控
Graphiti的实时更新和时间旅行查询能力，可有效应对金融市场的动态变化：
实时市场监测：整合股票行情、新闻事件、交易记录等数据流，构建“企业-行业-市场”关系图谱。例如，当某公司股价异常波动时，系统自动关联其上下游企业的交易数据，分析潜在风险。
反欺诈检测：通过追踪账户行为的时间线（如“账户在2025年7月15日异常登录后发起大额转账”），结合历史欺诈模式，识别高风险交易。例如，标记“用户A的转账路径与2024年某诈骗案例相似度达85%”。
合规性审计：支持查询特定时间点的合规状态（如“2025年6月30日某基金持仓是否符合监管要求”），满足审计回溯需求。例如，通过时间旅行查询验证“某交易是否在合规窗口期内执行”。
5.物流与供应链优化
Graphiti可实时整合运输数据、库存状态、客户需求，构建动态物流知识图谱：
路径规划与调度：结合运输成本、时效要求和实时路况，通过图遍历算法推荐最优路线。例如，当某路段发生拥堵时，系统自动切换至“仓库→转运中心2→配送点”的备选路径，并更新预计到达时间。
库存动态管理：关联仓库库存、订单状态和供应商数据，实时调整补货策略。例如，当某商品库存低于安全阈值时，系统自动触发“从仓库3调拨至仓库1”的指令，并更新物流事件时间轴。
异常事件响应：通过事件流处理机制，即时响应运输异常（如“包裹在2025年7月17日14:00滞留中转站”）。系统可自动检索历史类似事件的解决方案（如“联系当地配送团队优先处理”），并通知相关人员。
6.工业生产与设备运维
Graphiti支持构建包含设备状态、生产流程、维护记录的动态知识网络：
预测性维护：整合传感器数据、故障日志和维修历史，通过图关联分析预测设备故障。例如，当某生产线的电机振动值异常时，系统自动关联“该型号电机在2024年因轴承磨损导致停机”的案例，提前触发维护工单。
生产流程优化：通过追踪生产事件的时间线（如“2025年7月18日某批次产品因原料延误导致交付延迟”），分析瓶颈环节。例如，识别“供应商X的交货时间波动与生产线效率下降的相关性达70%”，优化供应链策略。
质量追溯与分析：结合产品批次、原材料来源和质检数据，构建可追溯的质量知识图谱。例如，当某批次产品出现缺陷时，系统可快速定位“原料供应商A在2025年5月提供的批次存在类似问题”，追溯责任并召回相关产品。
7.教育与个性化学习
Graphiti可构建包含知识点、学习路径、学生表现的动态教育知识图谱：
自适应学习推荐：通过分析学生答题记录和学习时间线，实时调整学习内容。例如，当学生在“微积分”模块多次答错时，系统自动推送“极限概念”的复习资料，并关联相关例题。
学习进度管理：结合课程大纲和学生进度数据，生成个性化学习计划。例如，根据“学生B在2025年7月已完成80%的课程内容”，推荐“剩余章节的重点突破策略”。
教育资源优化：通过图聚类技术分析学习资源的使用情况，动态调整内容分发。例如，当某知识点的教学视频播放量显著下降时，系统自动检索“该视频与最新考试大纲的匹配度”，并建议更新内容。
8.智能体协作与任务自动化
Graphiti作为AI智能体的记忆层，支持多智能体系统的动态协作：
跨系统数据整合：连接CRM、ERP等企业系统，构建统一知识图谱。例如，销售智能体可实时获取客户订单状态，自动触发售后智能体的回访任务。
复杂任务流程管理：通过状态推理和时间线分析，自动化执行多步骤任务。例如，当采购智能体检测到库存不足时，自动触发“生成采购申请→发送供应商询价→跟踪物流状态”的完整流程，并记录每个步骤的时间戳。
历史经验复用：通过时间旅行查询，智能体可借鉴历史案例优化决策。例如，当客服智能体遇到新问题时，系统自动检索“2024年类似问题的解决方案”，并生成建议话术。
通过上述场景化应用，Graphiti不仅实现了数据的实时整合与智能推理，更通过时间感知和语义分析能力，为各行业提供了从“数据存储”到“决策支持”的完整解决方案。无论是需要动态响应的智能客服，还是依赖时序分析的金融风控，Graphiti均能通过知识图谱的动态构建与高效查询，显著提升业务效率与决策准确性。
