技術調査 - Graphiti

■概要

Graphitiは、AIエージェント向けの時間認識型ナレッジグラフを構築し、クエリを実行するためのフレームワークです。

動的な環境で動作するAIエージェント専用に設計されています。ユーザーとの対話、構造化・非構造化された企業データ、外部情報源からの情報を継続的に統合します。これにより、一貫性を持ち、クエリ可能なナレッジグラフを構築します。

Graphitiは、リアルタイムなデータ更新と時間的コンテキストの管理に優れています。従来のGraphRAGアプローチと比較して、動的なデータ管理に特化している点が特徴です。MCPサーバーとGraph Serviceという2つの展開オプションがあり、様々な統合シナリオに対応します。

https://github.com/getzep/graphiti

■特徴

• リアルタイム増分更新:
  • バッチ処理での再計算をせず、新しいデータエピソードを即時に統合
• 双時間データモデル:
  • イベントの発生時刻とデータ取り込み時刻を個別に追跡し、正確な時点でのクエリを実行
• 効率的なハイブリッド検索:
  • セマンティック埋め込み、キーワード検索、グラフトラバーサルを組み合わせ、低遅延のクエリを実現
• カスタムエンティティ定義:
  • Pydanticモデルを使用して、柔軟なオントロジー作成と開発者によるエンティティ定義をサポート
• スケーラビリティ:
  • 並列処理により大規模なデータセットを効率的に管理し、エンタープライズ環境へ適用可能

■システム構造

●システムコンテキスト図

要素名	説明
開発者	Graphitiを使用してナレッジグラフアプリケーションを構築する開発者
AIエージェント	Graphitiのナレッジグラフ機能を利用するAIエージェント
Graphiti	時間認識型ナレッジグラフフレームワーク
Neo4j	グラフデータベースとして使用する外部システム
OpenAI	LLM推論と埋め込み生成に使用する外部システム

●コンテナ図

要素名	説明
MCP Server	Model Context Protocol（MCP）サーバーの実装。AIアシスタントとの統合を提供
Graph Service	FastAPIを基盤としたREST APIサービス
Graphiti Core	中核となるナレッジグラフ機能を提供するメインライブラリ
Neo4j Database	グラフデータを永続的に保管するストレージ
LLM Provider	自然言語処理タスクを実行する言語モデルプロバイダー

●コンポーネント図

要素名	説明
Graphiti Client	メインクライアントクラス。グラフ操作のための統合インターフェースを提供
Node Manager	EntityNode、EpisodicNode、CommunityNodeの管理
Edge Manager	EntityEdge、EpisodicEdgeの管理と関係性の抽出
Search Engine	ハイブリッド検索機能の提供
Embedder Client	テキストの埋め込みベクトル生成
LLM Client	自然言語処理タスクの実行

●統合検索の処理フロー

Graphitiの統合検索（Unified Search）の処理フローを図解します。これはsearch()関数を中心とした複数の検索手法を組み合わせたハイブリッド検索システムです。

統合検索はsearch()関数で開始され、以下の手順で実行されます：

1. クエリベクトル化: 入力クエリを埋め込みベクトルに変換
2. 並列検索実行: semaphore_gather()を使用して4つの検索タイプを同時実行
3. 結果統合: SearchResultsオブジェクトに統合

■情報

●概念モデル

●情報モデル

●主要な概念の関係

• エピソード（EpisodicNode）
  • エピソードは情報の入力単位で、生のコンテンツを保持します。
• エンティティ（EntityNode）
  • エンティティは実世界の概念（人、場所、組織など）を表現し、名前の埋め込みベクトルとサマリーを持ちます。
• ファクト（EntityEdge）
  • ファクトはエンティティ間の関係を自然言語で記述し、時間的な有効性情報を含みます。
• コミュニティ（CommunityNode）
  • コミュニティは関連するエンティティのクラスターを表現し、グラフクラスタリングアルゴリズムによって自動生成されます。

●主要な概念の登録処理フロー

■構築方法

前提条件

• Python 3.10以上をインストールします
• Neo4j 5.26以上を準備します
• OpenAI APIキーを取得します

パッケージインストール

pip install graphiti-core

または

poetry add graphiti-core

追加プロバイダーのインストール

# Anthropicサポート付き
pip install graphiti-core[anthropic]

# Groqサポート付き
pip install graphiti-core[groq]

# Google Geminiサポート付き
pip install graphiti-core[google-genai]

# 複数プロバイダー
pip install graphiti-core[anthropic,groq,google-genai]

環境変数設定

export OPENAI_API_KEY=your_openai_api_key_here
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=password

■利用方法

基本的な初期化

from graphiti_core import Graphiti

# Graphitiクライアントの初期化
graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j", 
    password="password"
)

# インデックスと制約の構築
await graphiti.build_indices_and_constraints()

エピソードの追加

# テキストエピソードの追加
await graphiti.add_episode(
    name="会議メモ",
    episode_body="プロジェクトの進捗について議論しました",
    source=EpisodeType.text,
    group_id="project_alpha"
)

# JSONエピソードの追加
await graphiti.add_episode(
    name="顧客データ",
    episode_body='{"company": {"name": "Acme Corp"}, "contact": "[e-mail]"}',
    source=EpisodeType.json,
    group_id="customers"
)

検索の実行

# ノード検索
search_results = await graphiti.search(
    query="プロジェクトの進捗",
    group_ids=["project_alpha"],
    limit=10
)

# ファクト検索
fact_results = await graphiti.search_facts(
    query="顧客情報",
    group_ids=["customers"],
    limit=5
)

MCPサーバーの起動

# SSEトランスポート（デフォルト）
uv run graphiti_mcp_server.py --transport sse

# stdioトランスポート
uv run graphiti_mcp_server.py --transport stdio

# カスタム設定
uv run graphiti_mcp_server.py --model gpt-4.1-mini --group-id my-project

■運用

ヘルスチェック

# データベース接続確認
async def check_health():
    try:
        await graphiti.driver.verify_connectivity()
        return {"status": "healthy"}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}

バックグラウンド処理の監視

MCPサーバーでは、グループIDごとに専用のキューワーカーが動作します：

# エピソード処理キューの状態確認
episode_queues = {}  # グループIDごとのキュー
queue_workers = {}   # ワーカーの状態管理

データ管理

# グラフのクリア
await graphiti.clear_graph()

# 特定グループの削除
await zep_graphiti.delete_group(group_id="old_project")

# エピソードの削除
await zep_graphiti.delete_episodic_node(episode_uuid)

Docker運用

# Docker Composeでの起動
docker-compose up -d

# ログ確認
docker-compose logs graphiti-mcp-server

# 停止
docker-compose down

■参考リンク

• 概要
  • Graphiti - Overview | Zep Help Center
  • DeepWiki - getzep/graphiti - 1-overview
  • arxiv - Zep: A Temporal Knowledge Graph Architecture for Agent Memory
• 構造
  • DeepWiki - getzep/graphiti - 4-system-architecture
  • DeepWiki - getzep/graphiti - 4.1-graphiti-core
  • DeepWiki - getzep/graphiti - 4.2-search-system
  • DeepWiki - getzep/graphiti - 4.3-llm-integration
  • DeepWiki - getzep/graphiti - 4.4-embedding-and-reranking
• 情報
  • DeepWiki - getzep/graphiti - 3-core-concepts
  • DeepWiki - getzep/graphiti - 3.1-knowledge-graph-model
  • Graphiti - Custom Entity Types | Zep Help Center
  • Graphiti - Adding Fact Triples | Zep Help Center
• 構築方法
  • Graphiti - Installation | Zep Help Center
  • DeepWiki - getzep/graphiti - 2-getting-started
  • DeepWiki - getzep/graphiti - 5-deployment-options
• 利用方法
  • Graphiti - Quick Start | Zep Help Center
  • Graphiti - Adding Episodes | Zep Help Center
  • Graphiti - Searching | Zep Help Center
  • Graphiti - Communities | Zep Help Center
  • Graphiti - CRUD Operations | Zep Help Center
  • Graphiti - LangGraph Agent | Zep Help Center
  • DeepWiki - getzep/graphiti - 6-advanced-usage
• 運用
  • Graphiti - Graph Namespacing | Zep Help Center

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！