Langfuseの意味と使い方｜LLMアプリの可観測性・評価・改善入門

1. Langfuseとは何か

Langfuseは、ChatGPT風アプリ、RAG検索システム、ローカルLLM、AIエージェントなどの動作を記録・分析するためのツールです。
通常のWebログが「誰が、いつ、どのURLを呼んだか」を見るものだとすれば、Langfuseは
「LLMに何を渡し、どの文脈で、どんな回答が返り、その品質はどうだったか」を見るためのものです。

短く言うと：
Langfuseは、LLMアプリの点検記録簿です。AIの回答を「雰囲気」で評価せず、入力・検索・プロンプト・出力・評価をセットで残します。

分類	通常のログ	Langfuse
見る対象	HTTPリクエスト、エラー、処理時間	ユーザー入力、プロンプト、LLM応答、RAG文書、token、評価
目的	システム障害の調査	回答品質、プロンプト、RAG、モデル挙動の改善
向いている場面	Webアプリ・API全般	LLMアプリ、チャットボット、AIエージェント、RAG

2. なぜ必要か

LLMアプリは、通常のプログラムよりも原因分析が難しいです。同じような質問でも、プロンプト、検索結果、モデル、temperature、文脈、履歴によって回答が変わります。
Langfuseを入れない場合、問題が起きても「モデルが悪いのか」「検索が悪いのか」「プロンプトが悪いのか」が分かりません。

回答が間違う

原因がモデルなのか、RAGの検索漏れなのか、プロンプトなのか分からない。

遅い

検索、要約、LLM推論、後処理のどこがボトルネックか見えにくい。

改善が勘になる

プロンプトを変えても、本当に良くなったか比較できない。

Langfuseを使うと、LLMアプリの1回の実行をトレースとして保存できます。
そのため、「ユーザー入力 → RAG検索 → プロンプト生成 → LLM応答 → 評価」という流れを後から確認できます。

3. 基本用語

用語	意味	例
Trace トレース	1回の処理全体の記録。ユーザーの1質問に対する処理全体。	「契約書の不利条項を調べて」という1回の依頼
Observation 観測	トレース内の個別処理。関数、検索、LLM呼び出しなど。	文書検索、プロンプト生成、LLM実行
Generation 生成	LLMの呼び出し記録。モデル名、入力、出力、token数など。	Qwen、GPT、Gemma、Claudeなどの応答
Prompt	LLMへ渡す指示文。テンプレート化・バージョン管理できる。	「あなたは契約書レビュー担当です…」
Score スコア	回答の品質評価。人手評価またはLLMによる自動評価。	正確性 4/5、関連性 5/5
Session	複数ターンの会話や一連の利用単位。	1人のユーザーとの相談セッション

4. 使い方の全体像

Langfuseのプロジェクトを作る

Langfuse Cloudまたはセルフホスト環境でプロジェクトを作成し、PUBLIC_KEY、SECRET_KEY、HOSTを取得します。

アプリにSDKを入れる

Pythonなら pip install langfuse で導入します。FastAPI、Flask、バッチ処理、RAG処理などに組み込めます。

記録したい関数に計装する

@observe()デコレータ、コンテキストマネージャ、手動イベント送信などで処理を記録します。

LLM呼び出し・RAG検索を記録する

入力、検索結果、プロンプト、モデル名、応答、処理時間、エラーなどをLangfuseへ送ります。

画面で分析する

遅い処理、失敗した処理、回答品質が低い処理、token使用量が多い処理を確認し、改善します。

5. セルフホスト導入

Langfuseはクラウド版だけでなく、自社サーバ、VM、VPC、オンプレミス環境に構築して使うこともできます。
契約書、現場写真、住民相談、社内RAG文書など、外部クラウドへそのまま送るべきではない情報を扱う場合は、
セルフホストを検討する価値が高いです。

重要：
セルフホストは「情報漏えいリスクを下げる選択肢」ですが、「何もしなくても安全」という意味ではありません。
管理画面の公開範囲、HTTPS、バックアップ、権限、保存期間、マスキングまで設計して初めて意味があります。

Cloud利用とセルフホストの違い

項目	Langfuse Cloud	セルフホスト
導入速度	速い。アカウント作成後すぐ使える。	サーバ、Docker/Kubernetes、DB、ストレージなどの準備が必要。
データ所在	Langfuse側の管理環境に保存される。	自社管理のVM、VPC、オンプレ環境に置ける。
運用負荷	低い。基盤運用はLangfuse側。	高い。更新、バックアップ、監視、障害対応が必要。
機密データ	ダミーデータや公開情報中心なら始めやすい。	契約書、顧客情報、行政・点検系データでは有力。
拡張性	プランに依存。	VM増強、Kubernetes、ストレージ設計で拡張できる。

セルフホストの代表的な構成

Langfuseのセルフホストは、単一のWebアプリだけではありません。Web/API、非同期ワーカー、Postgres、ClickHouse、Redis/Valkey、S3互換ストレージなどで構成されます。
そのため、最初は公式のDocker Compose構成で理解し、本番では可用性とバックアップを考えてKubernetesやクラウド基盤へ進むのが現実的です。

小規模・検証

1台VM + Docker Compose。最短で動かせるが、高可用性、水平スケール、バックアップは別途設計が必要。

本番・高負荷

Kubernetes/Helm、またはAWS・Azure・GCPなどのマネージド基盤。運用設計は重いが、耐障害性を作りやすい。

高セキュリティ

VPC内、VPN内、オンプレミスで管理画面を限定公開。外部公開は必要最小限にする。

完全閉域に近い構成

Langfuse自体は必須のインターネット接続なしでも構成可能。ただしLLM評価や外部LLM接続を使うなら別途出口が必要。

ざっくり構成図

LLM/RAGアプリ
  │
  │  trace / observation / score を送信
  ▼
Langfuse Web/API  ── 管理画面・SDK/API受付
  │
  ├─ Langfuse Worker ── 非同期処理・取り込み
  ├─ Postgres        ── ユーザー、設定、プロジェクトなど
  ├─ ClickHouse      ── Trace / Observation / Score の分析データ
  ├─ Redis/Valkey    ── キュー、キャッシュ
  └─ S3/MinIO        ── 大きなイベント、メディア、エクスポート

初期導入の進め方

検証用VMを1台用意する

UbuntuなどにDockerとDocker Composeを入れ、まずは社内LANまたはVPN内だけで起動します。

公式Docker Composeで起動する

公式リポジトリを取得し、docker-compose.yml内の秘密情報を必ず変更してから起動します。

管理画面へアクセスする

標準ではWeb/APIが:3000で起動します。外部公開する場合はNginxやロードバランサでHTTPS終端します。

プロジェクトとAPIキーを作る

プロジェクトを作成し、LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_HOSTをアプリ側に設定します。

まずは1関数だけ記録する

LLMを呼ぶ中心関数に@observe()を付け、入力・出力・処理時間が見えることを確認します。

本番前チェックリスト

確認項目	見るべき内容
公開範囲	管理画面を全世界公開しない。VPN、IP制限、社内ネットワーク、認証を組み合わせる。
HTTPS	NginxやロードバランサでTLS終端し、平文HTTPのまま外部公開しない。
秘密情報	`NEXTAUTH_SECRET`、DBパスワード、APIキーなどを初期値のまま使わない。
バックアップ	Postgres、ClickHouse、S3/MinIOのバックアップ方針を決める。Dockerボリュームだけに頼らない。
マスキング	氏名、住所、電話、メール、契約本文、写真メタデータなどを送信前に削る。
保存期間	トレースを無期限に溜めるとリスクと容量が増える。削除・アーカイブ方針を決める。
時刻設定	PostgresやClickHouseなどの基盤時刻をUTCで揃える。時刻ズレは分析結果の欠落につながる。

実務判断：
最初の学習やデモはCloudでもよいですが、本番データを扱う契約書レビュー、自治体相談、インフラ点検、写真付きRAGでは、
セルフホストまたは少なくとも送信前マスキングを前提にした方が安全です。

6. Pythonでの最小構成

まずはDockerでLangfuseサーバを構築するより、Langfuse Cloudまたは既存のLangfuseサーバへトレースを送る構成が簡単です。
アプリ側はPython SDKを入れて、記録したい関数に @observe() を付けるところから始めます。

インストール

python3 -m venv .venv
source .venv/bin/activate
pip install langfuse python-dotenv openai

.env の例

LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_HOST=https://cloud.langfuse.com

# ローカルvLLMやOllama互換APIを使う場合の例
OPENAI_BASE_URL=http://127.0.0.1:8000/v1
OPENAI_API_KEY=dummy

最小サンプル

from dotenv import load_dotenv
from langfuse import observe, get_client
from openai import OpenAI

load_dotenv()

client = OpenAI()
langfuse = get_client()

@observe()
def ask_llm(user_input: str) -> str:
    messages = [
        {"role": "system", "content": "あなたは日本語で簡潔に答えるアシスタントです。"},
        {"role": "user", "content": user_input},
    ]

    response = client.chat.completions.create(
        model="local-model",
        messages=messages,
        temperature=0.2,
    )

    return response.choices[0].message.content

if __name__ == "__main__":
    answer = ask_llm("Langfuseは何に使うものですか？")
    print(answer)

    # バッチや短いスクリプトでは送信完了を明示すると安全
    langfuse.flush()

ポイント：
@observe()を付けた関数は、入力、出力、処理時間、エラーをLangfuseへ記録できます。
まずはアプリ全体を細かく計装するより、LLMを呼んでいる中心関数から記録するのが現実的です。

7. RAG/ローカルLLMでの使いどころ

RAGでは、回答の品質はモデルだけで決まりません。検索された文書、チャンクの分割方法、プロンプトへの詰め方、LLMの設定が全部効きます。
Langfuseを使うと、この流れを一連の記録として残せます。

RAGで記録したいもの

検索クエリ、検索結果、使用チャンク、スコア、最終プロンプト、回答、参照元。

ローカルLLMで記録したいもの

モデル名、量子化方式、temperature、max_tokens、応答時間、GPU負荷の傾向。

RAG処理の記録イメージ

from langfuse import observe

@observe()
def rag_answer(question: str) -> str:
    docs = search_documents(question)       # どの文書が取れたかを記録したい
    prompt = build_prompt(question, docs)   # LLMへ実際に渡す内容を記録したい
    answer = call_llm(prompt)               # モデル応答を記録したい
    return answer

この形にしておくと、回答が悪かったときに「検索時点で必要な文書が取れていなかった」のか、
「文書は取れていたがプロンプトにうまく入っていなかった」のか、
「プロンプトは良いがモデルが読み違えた」のかを切り分けやすくなります。

8. 導入効果

Langfuseの効果は、単なるログ保存ではありません。LLMアプリを継続的に改善するための根拠を作ることです。

効果	内容	現場での意味
原因分析	入力、検索、プロンプト、出力を1本の流れで確認できる。	「AIが間違えた」で終わらず、原因箇所を絞れる。
品質改善	良い回答・悪い回答を比較し、プロンプトや検索条件を調整できる。	勘ではなく、履歴に基づいて改善できる。
再現性	どのモデル設定・プロンプト・入力で出た回答かを残せる。	顧客説明や障害調査で「その時の状態」を確認できる。
速度改善	処理ごとの時間を追える。	RAG検索が遅いのか、LLM推論が遅いのか分かる。
コスト管理	token数、モデル別利用量、呼び出し回数を把握できる。	クラウドAPI利用料やローカルGPU負荷を制御しやすい。
評価基盤	回答にスコアを付け、モデルやプロンプトの比較に使える。	モデル更新前後の品質差を説明できる。

9. 注意点

Langfuseは便利ですが、入力・プロンプト・回答を記録する性質があります。
業務利用では、便利さより先に情報管理を設計しないと危険です。

個人情報・機密情報

相談内容、契約書、社内文書、顧客名などをそのまま保存しない。必要に応じてマスク、要約、保存除外を行う。

保存容量

プロンプトやRAG文書を丸ごと保存すると容量が増える。保存期間、サンプリング、圧縮を設計する。

本番・検証の分離

開発用の実験トレースと、本番ユーザーのトレースは分ける。アクセス権も分ける。

ログを残しすぎない

LLMに渡した情報をすべて残すのは危険な場合がある。必要な粒度で記録する。

セルフホストでも油断しない

自社サーバに置いても、公開設定、権限、バックアップ、APIキー管理を誤れば漏えいする。

実務での鉄則：
Langfuseは「全部記録する道具」ではなく、「改善に必要な情報を適切な粒度で残す道具」と考えるべきです。

最初に作るべき構成

初めて使う場合は、いきなり大規模セルフホストや全機能導入を狙わない方がよいです。
まずは次の構成で十分です。

1つのLLM呼び出し関数だけ記録

チャットやRAGの中心関数に @observe() を付ける。

質問・回答・処理時間を見る

まずは「何を聞かれ、何を返し、何秒かかったか」を確認する。

RAG検索結果を追加で記録

必要文書が検索できているかを確認する。

評価スコアを付ける

良い回答・悪い回答を蓄積し、プロンプト改善やモデル比較に使う。

まとめ

Langfuseは、LLMアプリを「動いた・動かない」だけでなく、なぜその回答になったか、どう改善すべきかまで追うための基盤です。
特にRAG、ローカルLLM、業務チャット、契約書レビュー、点検レポート生成、自治体・インフラ系の相談支援のように、説明責任が必要な用途では効果が大きいです。

最初の一歩は難しくありません。LLMを呼ぶ関数に @observe() を付け、入力・出力・処理時間を見える化する。
そこからRAG検索、プロンプト管理、評価、モデル比較へ広げていけばよいです。

目次