Graphiti：构建AI智能体的实时知识图谱完全指南

摘要

本文深入探讨Graphiti框架的核心概念、架构设计和实践应用。Graphiti是一个专门为AI智能体设计的实时知识图谱构建框架，它能够持续整合用户交互、结构化数据和非结构化数据，构建可查询的时序知识图谱。通过详细的代码示例、架构图和最佳实践，帮助开发者掌握Graphiti的使用方法，构建智能、动态的AI应用系统。

1. 知识图谱与Graphiti概述

1.1 什么是知识图谱

知识图谱是一种以图结构表示知识的方式，由实体（节点）和关系（边）组成。例如："小明喜欢Python编程"这个事实可以表示为：

实体1：小明
关系：喜欢
实体2：Python编程

1.2 Graphiti的独特优势

1.3 与传统RAG的对比

特性	传统RAG	Graphiti
数据处理	批量处理	实时增量
时序处理	基础时间戳	双时序模型
检索方式	顺序LLM总结	混合检索
适应性	低	高
查询延迟	秒级	亚秒级

2. Graphiti核心特性

2.1 实时增量更新

from graphiti_core import Graphiti

# 初始化Graphiti实例
graphiti = Graphiti(
    "bolt://localhost:7687",  # Neo4j连接地址
    "neo4j",                  # 用户名
    "password",               # 密码
)

# 添加新的交互数据
async def add_interaction(user_id: str, content: str):
    """添加用户交互数据到知识图谱"""
    try:
        await graphiti.add_episode(
            content=content,
            metadata={
                "user_id": user_id,
                "timestamp": datetime.now().isoformat()
            }
        )
    except Exception as e:
        logger.error(f"添加交互数据失败: {str(e)}")
        raise

2.2 双时序数据模型

2.3 混合检索能力

# 混合检索示例
async def search_knowledge(query: str, limit: int = 5):
    """执行混合检索"""
    try:
        results = await graphiti.search(
            query=query,
            search_type="hybrid",  # 混合检索
            limit=limit
        )
        return results
    except Exception as e:
        logger.error(f"检索失败: {str(e)}")
        raise

3. 系统架构设计

3.1 整体架构

3.2 数据流

4. 快速开始指南

4.1 环境准备

# 安装Graphiti
pip install graphiti-core

# 安装可选依赖
pip install graphiti-core[anthropic]  # Anthropic支持
pip install graphiti-core[google-genai]  # Google Gemini支持

4.2 基础配置

from graphiti_core import Graphiti
from graphiti_core.llm_client import OpenAIClient
from graphiti_core.embedder.openai import OpenAIEmbedder

# 配置OpenAI
graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password",
    llm_client=OpenAIClient(
        api_key="your-openai-api-key"
    ),
    embedder=OpenAIEmbedder(
        api_key="your-openai-api-key"
    )
)

4.3 数据操作示例

# 添加知识
async def add_knowledge():
    """添加知识到图谱"""
    try:
        # 添加文本数据
        await graphiti.add_episode(
            content="小明是一名Python开发者，他喜欢使用Django框架",
            metadata={"source": "user_input"}
        )
        
        # 添加结构化数据
        await graphiti.add_episode(
            content={
                "person": "小明",
                "skill": "Python",
                "framework": "Django"
            },
            metadata={"type": "structured"}
        )
    except Exception as e:
        logger.error(f"添加知识失败: {str(e)}")
        raise

5. 高级功能应用

5.1 自定义实体定义

from pydantic import BaseModel

class Person(BaseModel):
    """人物实体定义"""
    name: str
    age: int
    skills: list[str]

class Project(BaseModel):
    """项目实体定义"""
    name: str
    description: str
    technologies: list[str]

# 使用自定义实体
async def add_custom_entities():
    """添加自定义实体"""
    person = Person(
        name="小明",
        age=25,
        skills=["Python", "Django", "React"]
    )
    
    project = Project(
        name="智能客服系统",
        description="基于知识图谱的智能客服系统",
        technologies=["Python", "Neo4j", "React"]
    )
    
    await graphiti.add_episode(
        content={
            "person": person.dict(),
            "project": project.dict()
        }
    )

5.2 高级查询功能

# 复杂查询示例
async def complex_query():
    """执行复杂查询"""
    try:
        # 语义搜索
        semantic_results = await graphiti.search(
            query="Python开发者使用的框架",
            search_type="semantic"
        )
        
        # 图遍历查询
        graph_results = await graphiti.traverse(
            start_node="小明",
            relationship_type="USES",
            depth=2
        )
        
        return {
            "semantic": semantic_results,
            "graph": graph_results
        }
    except Exception as e:
        logger.error(f"查询失败: {str(e)}")
        raise

6. 最佳实践与优化

6.1 性能优化

6.2 错误处理

class GraphitiError(Exception):
    """Graphiti基础异常类"""
    pass

class ConnectionError(GraphitiError):
    """连接错误"""
    pass

class QueryError(GraphitiError):
    """查询错误"""
    pass

# 错误处理示例
async def safe_operation():
    """安全操作示例"""
    try:
        result = await graphiti.operation()
        return result
    except ConnectionError as e:
        logger.error(f"连接错误: {str(e)}")
        # 重试逻辑
    except QueryError as e:
        logger.error(f"查询错误: {str(e)}")
        # 错误恢复逻辑
    except Exception as e:
        logger.error(f"未知错误: {str(e)}")
        raise