LangFuse完全ガイド！LLMアプリの可観測性を実現するオープンソースプラットフォーム

LLMアプリの「見えない問題」

本番環境のLLMアプリケーションで、こんな経験はありませんか？

• エージェントが失敗した理由がわからない
• プロンプトの変更が性能に与えた影響が不明
• トークン使用量が膨らみ、コストが制御不能
• A/Bテストの結果を定量的に比較できない

LangFuseは、これら全ての問題を解決するオープンソースプラットフォームです。

LangFuseとは？LLM可観測性の統合ソリューション

LangFuseは、OpenTelemetryベースのLLMアプリケーション専用可観測性プラットフォームです。

3つのコア機能

1. トレーシング: LLM呼び出しを完全に可視化
2. プロンプト管理: バージョン管理と即座のデプロイ
3. 評価: 自動・手動両方の品質評価

実践1: トレーシングで透明性を確保

基本的なトレーシング

from langfuse import Langfuse

langfuse = Langfuse(
    secret_key="sk-lf-...",
    public_key="pk-lf-...",
    host="https://cloud.langfuse.com"  # またはセルフホスト
)

# トレースの開始
trace = langfuse.trace(
    name="customer_support_session",
    user_id="user_123",
    metadata={"channel": "web"}
)

# スパン（個別ステップ）の記録
generation = trace.generation(
    name="initial_response",
    model="gpt-4",
    model_parameters={"temperature": 0.7},
    input="ユーザーからの質問",
    output="AIの回答",
    usage={
        "input": 150,
        "output": 300,
        "total": 450
    }
)

# トレースの終了
trace.update(
    output="最終的な回答"
)

AIエージェントの可視化

# マルチステップエージェントのトレース
trace = langfuse.trace(name="research_agent")

# ステップ1: 計画
plan_span = trace.span(
    name="planning",
    input="市場調査のタスク"
)
plan_output = agent.plan("市場調査を実施")
plan_span.end(output=plan_output)

# ステップ2: Web検索
search_span = trace.span(
    name="web_search",
    metadata={"tool": "serpapi"}
)
search_results = agent.search(plan_output["query"])
search_span.end(output=search_results)

# ステップ3: LLM分析
analysis_gen = trace.generation(
    name="analysis",
    model="claude-3-sonnet",
    input=search_results,
    output=agent.analyze(search_results)
)

# エラーの記録
try:
    result = risky_operation()
except Exception as e:
    trace.span(
        name="error",
        level="ERROR",
        status_message=str(e)
    )

LangFuseダッシュボードでの確認

トレースは自動的に以下の情報と共に記録されます：

• コスト: トークン使用量から自動計算
• レイテンシ: 各ステップの実行時間
• 成功率: エラー発生率
• セッション: ユーザーごとの会話履歴

実践2: プロンプト管理で開発を加速

プロンプトのバージョン管理

# プロンプトの取得（バージョン管理されている）
prompt = langfuse.get_prompt("customer_support_v3")

# OpenAI APIで使用
response = openai.chat.completions.create(
    model=prompt.config["model"],
    messages=[
        {"role": "system", "content": prompt.compile()},
        {"role": "user", "content": user_message}
    ],
    temperature=prompt.config["temperature"]
)

# LangFuseにトレース
langfuse.trace(
    prompt=prompt,
    input=user_message,
    output=response.choices[0].message.content
)

Web UIでのプロンプト編集

LangFuse Dashboard:

Prompts > customer_support

Version 3 (Production) ✓
---
あなたは親切なカスタマーサポート担当者です。
以下のガイドラインに従ってください：
1. 丁寧な言葉遣い
2. 具体的な解決策の提示
3. 必要に応じてエスカレーション

[Deploy to Production] [Create New Version]

即座のロールバック

# コード変更なしでプロンプトを切り替え
# Web UIで "Rollback to v2" をクリックするだけ

# アプリケーション側の変更不要
prompt = langfuse.get_prompt("customer_support")  # 自動的にv2が取得される

実践3: 自動評価でプロンプトを改善

LLM-as-a-Judge評価

from langfuse.decorators import observe, langfuse_context

@observe()
def generate_response(user_input: str):
    """ユーザー入力に対して応答を生成"""
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": user_input}]
    )
    return response.choices[0].message.content

# 評価関数
@observe()
def evaluate_response(input_text: str, output_text: str):
    """LLMで品質を評価"""
    eval_prompt = f"""
    以下の応答を1-5で評価してください：
    
    入力: {input_text}
    出力: {output_text}
    
    評価基準:
    - 正確性
    - 丁寧さ
    - 具体性
    """
    
    eval_response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": eval_prompt}]
    )
    
    score = int(eval_response.choices[0].message.content)
    
    # スコアをLangFuseに記録
    langfuse_context.score_current_trace(
        name="quality_score",
        value=score,
        comment="LLM-as-a-Judge評価"
    )
    
    return score

# 使用例
response = generate_response("商品の返品方法を教えて")
evaluate_response("商品の返品方法を教えて", response)

データセットでのベンチマーク

# データセットの作成
langfuse.create_dataset(
    name="support_questions",
    items=[
        langfuse.create_dataset_item(
            dataset_name="support_questions",
            input={"question": "返品期限は？"},
            expected_output={"answer": "購入後30日以内"}
        ),
        # ...他の質問
    ]
)

# データセットでの評価実行
dataset = langfuse.get_dataset("support_questions")

for item in dataset.items:
    # 応答生成
    response = generate_response(item.input["question"])
    
    # トレースにデータセット情報を紐付け
    trace = langfuse.trace(
        name="dataset_eval",
        metadata={
            "dataset_item_id": item.id,
            "expected": item.expected_output["answer"]
        }
    )
    
    # 評価スコアの記録
    exact_match = response == item.expected_output["answer"]
    trace.score(
        name="exact_match",
        value=1.0 if exact_match else 0.0
    )

LangChain/LlamaIndexとの統合

LangChain

from langfuse.callback import CallbackHandler

# LangFuseハンドラー
langfuse_handler = CallbackHandler(
    secret_key="sk-lf-...",
    public_key="pk-lf-..."
)

# LangChainチェーンで使用
from langchain.chains import LLMChain
from langchain.llms import OpenAI

chain = LLMChain(
    llm=OpenAI(),
    prompt=prompt_template,
    callbacks=[langfuse_handler]  # ここでトレースが自動的に記録される
)

result = chain.run("質問")

LlamaIndex

from llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager
from langfuse.llama_index import LlamaIndexCallbackHandler

# LangFuseハンドラー
langfuse_handler = LlamaIndexCallbackHandler()

Settings.callback_manager = CallbackManager([langfuse_handler])

# 以降、全てのLlamaIndex操作が自動トレースされる
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("質問")

コスト最適化

トークン使用量の可視化

LangFuseダッシュボードで、以下が自動集計されます：

過去7日間のコスト:
- GPT-4: $157.32 (68%)
- Claude-3-Sonnet: $52.18 (23%)
- GPT-3.5-turbo: $21.45 (9%)

最もコストのかかるトレース Top 3:
1. research_agent: $12.34 (トークン数: 45,231)
2. data_analysis: $8.76 (トークン数: 32,145)
3. summarization: $6.21 (トークン数: 22,891)

アラート設定

# 高コストトレースのアラート（Web UIで設定可能）
# コスト > $5.00 の場合、Slackに通知

セルフホスティング vs クラウド

セルフホスティング（無料）

# Dockerで起動
docker run --name langfuse \
  -e DATABASE_URL=postgresql://... \
  -e NEXTAUTH_SECRET=... \
  -p 3000:3000 \
  langfuse/langfuse

クラウド（マネージド）

• 無料プラン: 月50,000イベントまで
• Proプラン: $49/月 - 無制限イベント
• Enterprise: カスタム価格 - RBAC、SSO対応

まとめ

LangFuseは、LLMアプリケーションの「ブラックボックス」を透明化します。

• トレーシングで全ての動作を可視化
• プロンプト管理でデプロイを高速化
• 自動評価で品質を定量化
• コスト可視化で予算を管理

特に、本番環境で動くAIエージェントを開発・運用する際には、LangFuseは必須ツールです。

オープンソースなので、まずはセルフホストで試してみることをお勧めします。