はじめに
近年 LLM の台頭により、LLM Observability への関心が高まっています。
本記事は LLM Observability ツールとして知られている Langfuse について実際に構築してみる記事となります。
LLM Observability とは
LLM を用いたアプリケーション開発には、以下のような課題があります。
- ブラックボックス化
- LLM の内部動作が見えず、なぜその出力が生成されたのか把握しづらい
- コスト管理の困難さ
- トークン使用量や API 呼び出しコストの追跡が難しい
- 品質の不安定さ
- プロンプトの変更による出力品質への影響を定量的に測定しにくい
- デバッグの複雑さ
- 複数の LLM 呼び出しが連鎖するアプリケーションでは、問題箇所の特定が困難
- ハルシネーションの検出
- 不正確な情報生成を検知・監視する仕組みが必要
これらを解決するツールとして、LLM Observability ツールが存在します。
LLM Observability とは、LLM アプリケーションの動作を可視化・トレース・分析するための仕組みです。
Langfuse とは
Langfuse は、LLM アプリケーションの観測性を提供するオープンソースツールです。MIT ライセンスで提供されており、SaaS 版（Langfuse Cloud）とセルフホスト版の両方が利用可能です。
主な機能
| 機能 | 説明 |
|---|---|
| トレーシング | LLM 呼び出しごとに入力プロンプト、トークン使用量、出力内容、実行時間、例外情報などを記録 |
| コスト・メトリクス可視化 | レスポンス時間、トークン使用量、コスト効率などの KPI をダッシュボードで可視化 |
| プロンプト管理 | プロンプトのバージョン管理機能。どのプロンプトでどの結果が出たかを追跡可能 |
| 評価・スコアリング | 収集した trace に対してスコアを付与。自動評価も可能 |
| セッション管理 | チャット型アプリケーションなど、連続的な LLM 実行のメタデータを収集 |
Langfuse をローカルでサクッと構築してみよう
Langfuse をサクッと構築していきます。
今回は公式で提供しているリポジトリを使用して構築していきます。
環境
- macOS
Langfuse v3 のざっくり構成
構成図
主な役割
- Langfuse Web
- Next.js ベースの Web UI・API サーバー
- Langfuse Worker
- イベント処理、評価実行などの非同期処理
- PostgreSQL
- ユーザー、プロジェクト、プロンプト等のメタデータ保存
- ClickHouse
- トレース、スパン等の大量観測データを保存
- Redis
- キャッシュ、キュー
- s3 (langfuse リポジトリだと minio で互換)
- ファイル・添付データ保存
Langfuse v3 の構築手順
1. リポジトリをクローン
git clone https://github.com/langfuse/langfuse.git
cd langfuse
2. Docker Compose で起動
docker compose up
初回は Docker イメージのダウンロードに結構時間がかかります。ゆっくり待ちましょう。
3. 起動確認
以下のログが表示されたら起動完了です。
langfuse-langfuse-web-1 | ✓ Ready in XXXms
別ターミナルで docker ps を実行し、6 つのコンテナが Up 状態であることを確認できます。
docker ps 1.1m 水 12/ 3 08:29:27 2025
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
e502fc004d77 langfuse/langfuse:3 "dumb-init -- ./web/…" 32 minutes ago Up 32 minutes 0.0.0.0:3000->3000/tcp langfuse-local-langfuse-web-1
3e369e03fe22 langfuse/langfuse-worker:3 "dumb-init -- ./work…" 32 minutes ago Up 32 minutes 127.0.0.1:3030->3030/tcp langfuse-local-langfuse-worker-1
7a3ac52e39be clickhouse/clickhouse-server "/entrypoint.sh" 32 minutes ago Up 32 minutes (healthy) 127.0.0.1:8123->8123/tcp, 127.0.0.1:9000->9000/tcp, 9009/tcp langfuse-local-clickhouse-1
30f32d794f73 cgr.dev/chainguard/minio "sh -c 'mkdir -p /da…" 32 minutes ago Up 32 minutes (healthy) 0.0.0.0:9090->9000/tcp, 127.0.0.1:9091->9001/tcp langfuse-local-minio-1
ea2e4a0420a5 postgres:17 "docker-entrypoint.s…" 32 minutes ago Up 32 minutes (healthy) 127.0.0.1:5432->5432/tcp langfuse-local-postgres-1
6aab4110505d redis:7 "docker-entrypoint.s…" 32 minutes ago Up 32 minutes (healthy) 127.0.0.1:6379->6379/tcp langfuse-local-redis-1
4. Langfuse にアクセス
ブラウザで http://localhost:3000 にアクセスします。
うまくいけば画面が表示できます。
初回はアカウント作成（Sign Up）が必要です。ローカル環境なので任意のメールアドレスとパスワードで登録できます。
SignUp すると以下のような画面が表示されます。
Langfuse が構築できましたね！
まとめ
- LLM Observability は、LLM アプリケーションのブラックボックス化やコスト管理、品質管理などの課題を解決するための仕組みである
- Langfuse はオープンソースの LLM Observability ツールで、トレーシング、コスト可視化、プロンプト管理、評価機能などを提供する