はじめに

大規模言語モデル（LLM）を活用したアプリケーションは、ドキュメント検索や質問応答など、多種多様なユースケースで利用されています。しかし、LLM を用いたシステムでは

出力のクオリティ（モデルがどの程度正確か、根拠は正しいか）
プロセスの可視化・追跡（どのようなプロンプトや文脈が使用されたか）
評価指標に基づく改善サイクル（何をもって「良い回答」「悪い回答」とするのか）

といった観点が重要になります。本リポジトリ「langfuse-ragas-sandbox」では、これらの課題を Langfuse と Ragas を使って解決するためのサンプル実装を紹介しています。

Roo-code(Roo-cline)を使って、langfuseとragasでマーダーミステリーのデータを使って遊んでみます②
langfuseでlangchainの中身を追えるのは普通に便利やん！！ https://t.co/aRZgXoHGsX pic.twitter.com/t3pwkc2XLK
— Maki@Sunwood AI Labs. (@hAru_mAki_ch) January 31, 2025

Langfuse と Ragas について

Langfuse とは

Langfuse は、LLM を使用するアプリケーションのための可観測性（Observability）と分析プラットフォームです。

ログの追跡・可視化: LLM へのプロンプト、返ってきた応答、実行時間などをトレース可能
スコアの管理: 各種評価指標（スコア）をモデル・実行タイミングごとに記録して比較・分析
デバッグ・改善: モデルをどのように呼び出し、どんな結果だったかを俯瞰することで、プロンプト設計や評価手法の見直しに役立つ

Ragas とは

Ragas は、LLM の性能を客観的に評価するためのライブラリです。

標準的な評価指標の提供: 回答の忠実性（Faithfulness）や関連性（Relevancy）といった、LLM によく用いられる指標を実装
カスタム評価指標の拡張性: ユースケースに特化した評価指標を導入可能（例：推理ゲーム向けの要素にどれだけ言及しているかなど）
LLM と連動した自動評価: GPT-4 等を評価のために利用し、テキストの論理構造や要素を数値的にスコアリング

Example 01 とは？

1. 位置づけ

example/01_basic_setup は、Langfuse と Ragas を活用した評価実験の最初のステップです。ここでは、主に RAG（Retrieval-Augmented Generation） の基本部分と簡単なログ取得を体験します。

RAG: ベクトルストアから検索した文脈情報（ドキュメント）を LLM の入力に組み込み、より正確で根拠ある回答を生成する手法

2. ディレクトリ構成

01_basic_setup/
├─ logs/
├─ requirements.txt
├─ README.md
├─ basic_rag.py
├─ .env.example

logs/
実行時のログファイルが保存されるディレクトリ。
requirements.txt
このサンプルに必要なパッケージの一覧。
README.md
Example 01 の概要と実行手順などを説明。
basic_rag.py
RAG システムのメインスクリプト。データの読み込みから回答生成までの流れがここにまとまっています。
.env.example
環境変数（OpenAI API Key や Langfuse Key）の設定テンプレート。.env にリネームして使用します。

実行手順

以下のステップで Example 01 を実行できます。

リポジトリをクローン

git clone https://github.com/yourusername/langfuse-ragas-sandbox.git
cd langfuse-ragas-sandbox

.env の設定

cd example/01_basic_setup
cp .env.example .env
# .env を開いて、以下を自分の環境に合わせて設定
# LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST, OPENAI_API_KEY, etc.

依存パッケージのインストール
```
uv pip install -r requirements.txt
```
※ uv は任意のパッケージマネージャを意味していますが、通常の pip install でも構いません。
スクリプトの実行
```
python basic_rag.py
```
- ターミナルにて、各質問に対する回答が表示されます。
- 同時に、Langfuse に対してログとスコアが送られ、logs/ ディレクトリにも実行ログ (rag_app_{time}.log) が生成されます。
Langfuse ダッシュボードで確認
LANGFUSE_HOST で指定した URL（例: http://localhost:3000）を開き、ダッシュボード上で実行履歴やトレース情報を確認できます。

`basic_rag.py` のポイント

def main():
    # 1. Langfuse コールバックハンドラーのセットアップ
    handler = setup_callback_handler()
    
    # 2. データセットの読み込み
    dataset = load_mystery_dataset()
    documents = create_documents(dataset)
    
    # 3. 質問リストと使用するモデルの設定
    questions = [
        "深夜の美術館殺人事件の概要を教えてください",
        "仮面舞踏会の事件で発見された証拠品は何ですか？",
        "美術館殺人事件の容疑者は誰がいますか？"
    ]
    models = ["gpt-4o", "gpt-4o-mini"]
    
    # 4. RAG チェーンの作成と回答生成
    for model_name in models:
        chain = create_rag_chain(documents, model_name)
        for question in questions:
            response = chain.invoke(question, config={"callbacks": [handler]})
            print(f"回答 ({model_name}): {response.content}")

Langfuse ハンドラー
.env に設定した LANGFUSE_PUBLIC_KEY などの情報を読み込み、Langfuse へイベント送信するコールバックが作られます。
マーダーミステリー用データセット読み込み
架空の殺人事件データから事件概要・証拠・容疑者情報をテキストとして抽出。
RAG チェーンの実装
- ベクトルストア: OpenAI Embeddings × FAISS で文脈検索
- LLM: GPT-4 系モデルで回答生成
Langfuse へのロギング
質問や検索結果、最終的な回答を Langfuse ダッシュボードで可視化・分析できます。

使ってみるとわかること

RAG の基本的な流れ
- ユーザーの質問 → ベクトルストアから類似ドキュメント取得 → LLM で回答生成
- 外部知識を LLM に提供することで、答えの正確性を高める仕組みを把握できます。
Langfuse を使ったトレースの可視化
- 「どんな質問が来て、どんな文脈を検索し、どんな回答を生成したか」を一元管理。
- 複数モデル（例: gpt-4o / gpt-4o-mini）を比較しやすい。
ログとコスト管理
- GPT-4 は API コストが高めなので、実行ログを見ながら回数を調整するなどの運用が大切です。

次のステップ

Example 02: Ragas 評価
回答の忠実性（Faithfulness）や関連性（Relevancy）などを Ragas による評価指標で数値化します。Langfuse 上でスコアを参照できるようになるため、複数モデルや設定の比較が容易です。
Example 03: カスタム評価指標
ミステリー特有の要素（動機やアリバイへの言及、ストーリーの一貫性など）をスコアに反映させるカスタマイズ例を紹介しています。

まとめ

example/01_basic_setup は、

RAG（Retrieval-Augmented Generation）の基本的な仕組み
Langfuse を使ったログ・トレースの可視化
Ragas を含めた初歩的な評価フロー

の第一歩として最適なサンプルです。実行してみることで、ベクトル検索 → LLM 回答 → Langfuse による可観測性 という一連の流れを体験できます。
もし高度な評価基準やシナリオごとのモデル比較を行いたい場合は、続く Example 02、Example 03 もぜひ参考にしてください。

これから Langfuse と Ragas を使って LLM プロジェクトの評価を始める方にとって、この Example 01 がスムーズな導入となれば幸いです。ぜひご活用ください。

リポジトリ