📚 suwa-sh / zenn-contents
🕸️ 技術調査 - Graphiti
目次

🕸️ 技術調査 - Graphiti

2025-06-05

■概要

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

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

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

https://github.com/getzep/graphiti

■特徴

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

■システム構造

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

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

●コンテナ図

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

●コンポーネント図

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

●統合検索の処理フロー

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

検索エントリーポイント 検索エントリーポイント 検索エントリーポイント 検索エントリーポイント 検索エントリーポイント search() クエリベクトル化 edge_search() node_search() episode_search() community_search() フルテキスト検索BM25/Lucene ベクトル類似度検索コサイン類似度 幅優先探索グラフトラバーサル RRF相互ランク融合 MMR最大限界関連性 CrossEncoderニューラルリランキング ノード距離リランキング メンション数リランキング SearchResults コンテキスト文字列化

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

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

■データ

●概念モデル

Core Entities Relationships Clients EpisodicNode EntityNode CommunityNode EntityEdge EpisodicEdge GraphitiClient LLMClient EmbedderClient

●情報モデル

EpisodicNode + str: uuid: + str: name: + str: group_id: + str: content: + str: source: + str: source_description: + datetime: created_at: + datetime: valid_at: EntityNode + str: uuid: + str: name: + str: group_id: + str: summary: + list[str]: labels: + datetime: created_at: + list[float]: name_embedding: EntityEdge + str: uuid: + str: name: + str: group_id: + str: fact: + datetime: created_at: + datetime: valid_at: + datetime: invalid_at: + datetime: expired_at: + list[float]: fact_embedding: + list[str]: episodes: Graphiti + AsyncDriver: driver: + LLMClient: llm_client: + EmbedderClient: embedder: + CrossEncoderClient: cross_encoder: + add_episode() + search() + build_indices_and_constraints() connects mentions manages manages manages

●主要な概念の関係

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

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

データベース層 エピソード入力 エンティティ・ファクト抽出 重複解決・時間的検証 グラフデータベース保存 コミュニティ検出 EPISODIC_NODE_SAVE ENTITY_NODE_SAVE ENTITY_EDGE_SAVE COMMUNITY_NODE_SAVE

■構築方法

前提条件

  • 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": "john@acme.com"}',
    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

■参考リンク

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