LibreChatに統合されたLangfuseトレース送信機能を試す
- Shogo Umeda
- 3 時間前
- 読了時間: 9分
はじめに
この記事では、オープンソースのチャットUI「LibreChat」をDocker Composeでセットアップし、既存のLangfuseへトレースを送信する機能を試します。
LibreChatでLangfuseにトレースを送信するには
LibreChatでLangfuseにトレースを送信するには、これまでLiteLLMをプロキシとして挟む構成が必要でした。
LibreChat → LiteLLM (プロキシ) → LLM Provider
↓
LangfuseLiteLLMはLangfuse連携をサポートしており、LLM呼び出しをトレースできますが、LibreChatとは別にLiteLLMの構築・管理が必要になるため、セットアップの複雑さが増すという課題がありました。
LibreChat v0.8.1（2025年12月11日リリース）では、PR #10292により、LiteLLMなしでLibreChatから直接Langfuseにトレースを送信できるようになりました。
LibreChat → LLM Provider
↓
Langfuse（直接送信）これにより、LibreChatとLangfuseだけのシンプルな構成でオブザーバビリティを実現できます。
この記事で実現すること
この記事では、以下の内容を実践します。
Docker ComposeでLibreChatを構築し、OpenAI APIとLangfuseに接続
基本的なトレースの確認
LibreChatでMCP Server利用時のトレースを確認
注意：この記事では、Langfuseは既に用意されている前提で進めます。Langfuseをセルフホストする方法については、Langfuse公式ドキュメントを参照してください。Langfuse Cloudを利用する場合は、https://cloud.langfuse.com でアカウントを作成してください。
それでは、環境構築から始めます。
環境構築編
LibreChatをDocker Composeでローカル環境に構築し、既存のLangfuseに接続します。
前提条件
以下がインストールされていることを前提とします。
Docker Desktopなど、Docker Composeが使える環境
以下何れかのLangfuseとAPIキー
Langfuse Cloud
セルフホストしたLangfuse
LLMプロバイダーのAPIキー（OpenAI、Anthropic、Google Vertex AIなど）
アーキテクチャ概要
今回構築する環境の構成は以下の通りです。
各コンポーネントの役割
LibreChat: チャットUIおよびLLM統合層
MongoDB: LibreChatのデータベース（ユーザー情報、会話履歴など）
外部Langfuse: トレース収集・可視化（Cloudまたはセルフホスト）
LLM Provider API: OpenAI、Vertex AI、Anthropicなどのモデルプロバイダー
セットアップ手順
1. ディレクトリ構成
以下のようなディレクトリ構成で環境構築します。
librechat-langfuse-integrate/
├── .env # 環境変数
├── docker-compose.yml # コンテナ構成定義
└── librechat.yaml # LibreChatの設定ファイル任意のディレクトリを作成し、以降の手順で各ファイルを配置していきます。
2. 環境変数ファイル (.env)
.env ファイルを作成し、Langfuse接続情報とLLMプロバイダーのAPIキーを設定します。
.env
# ============================================
# LibreChat Server Settings
# ============================================
PORT=3080
ALLOW_REGISTRATION=true
# ============================================
# LLM Provider Settings
# ============================================
# OpenAI API Key
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx
# ============================================
# Langfuse Settings (External Server)
# ============================================
# Get these values from your Langfuse project settings
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxxxxxxxxxx
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxxxxxxxxxx
LANGFUSE_BASE_URL=https://cloud.langfuse.com # または https://your-langfuse-server.com
# ============================================
# LibreChat Auth Secrets
# ============================================
# セキュリティ上、必ず変更してください
# 生成: openssl rand -hex 16
CREDS_KEY=your-creds-key-change-this
# 生成: openssl rand -hex 8
CREDS_IV=your-creds-iv-change-this
# 生成: openssl rand -hex 32
JWT_SECRET=your-jwt-secret-change-this
# 生成: openssl rand -hex 32
JWT_REFRESH_SECRET=your-jwt-refresh-secret-change-this補足
Langfuseとの接続に必要なのは `LANGFUSE_SECRET_KEY`、`LANGFUSE_PUBLIC_KEY`、`LANGFUSE_BASE_URL` の3つです。これらの値はLangfuseプロジェクトの Settings → API Keys から取得できます。
Auth Secrets（`CREDS_KEY`、`CREDS_IV`、`JWT_SECRET`、`JWT_REFRESH_SECRET`）は、各項目のコメントに記載した `openssl rand` コマンドで生成した値に置き換えてください。
3. Docker Compose設定ファイル (docker-compose.yml)
LibreChatとMongoDBのみを起動し、OpenAI APIを利用したシンプルな構成です。
フル機能を含む公式のDocker Compose設定は以下公式GitHubリポジトリの設定ファイルを参照して下さい。
docker-compose.yml
services:
# ===========================================
# LibreChat Application Server
# ===========================================
api:
container_name: LibreChat
image: ghcr.io/danny-avila/librechat:v0.8.1
ports:
- "${PORT}:${PORT}"
depends_on:
- mongodb
restart: always
extra_hosts:
- "host.docker.internal:host-gateway"
env_file:
- .env
environment:
- HOST=0.0.0.0
- MONGO_URI=mongodb://mongodb:27017/LibreChat
volumes:
- ./librechat.yaml:/app/librechat.yaml:ro
# ===========================================
# MongoDB - LibreChatのデータストア
# ===========================================
mongodb:
container_name: chat-mongodb
image: mongo:8.0.17
restart: always
volumes:
- mongodb-data:/data/db
command: mongod --noauth
volumes:
mongodb-data:4. LibreChat設定ファイル (librechat.yaml)
LibreChatの動作をカスタマイズする設定ファイルです。以下の例はOpenAIモデルとエージェント機能を使用する設定です。
librechat.yaml
# Configuration version (required)
version: 1.3.5
# Cache settings: Set to true to enable caching
cache: true
# Endpoints Configuration
endpoints:
# OpenAI Configuration
openAI:
apiKey: "${OPENAI_API_KEY}"
models:
default:
- "gpt-5"
- "gpt-5-mini"
- "gpt-5-nano"
titleConvo: true
summarize: false
titleModel: "gpt-5-nano"
# Agents Configuration
# Langfuse tracing is enabled for Agents
agents:
disableBuilder: false # Enable Agent Builder UI
recursionLimit: 25 # Default steps an agent can take
maxRecursionLimit: 50 # Maximum steps limit
# MCP Server Configuration（後ほど検証編2で使用）
mcpServers: {}
registration:
socialLogins: []補足
`mcpServers` は後ほどMCP Server機能を検証する際に設定を追加します。
5. Docker ComposeでLibreChatを起動・動作確認
以下のコマンドでLibreChatを起動します。
# LibreChatとMongoDBを起動
docker compose up -d
# 起動状態を確認
docker compose ps初回起動時は、イメージのダウンロードやデータベースの初期化が行われるため、数分かかる場合があります。
サービスが正常に起動しているか、ログを確認します。
# LibreChatコンテナのログを確認
docker compose logs -f api
# 正常に起動していれば、以下のようなログが表示されます
# LibreChat v0.8.1
# Server listening on port 3082
# Connected to MongoDB起動を確認したら、以下の手順でLibreChatにアクセスします。
http://localhost:3080 にアクセス
新規登録からアカウントを作成
ログイン後、設定したLLM（OpenAI）を選択し、LLMに挨拶をし、LibreChatで正しくLLMが動作することを確認します。
6. Langfuse接続の確認
LibreChatで簡単な会話を実行した後、Langfuse UIにアクセスしてトレースが記録されているか確認します。
Langfuse UI アクセス先
Langfuse Cloud : https://cloud.langfuse.com
セルフホスト : セルフホストのLangfuseURL
Traceing ページに移動し、LibreChatからのトレースが表示されていれば成功です。
これで、LibreChatと外部Langfuseの統合環境が完成しました。次は、実際にトレースの詳細を確認します。
検証編1 - 基本的なトレース確認
環境構築が完了したので、トレースが正しく送信されているか確認します。
「5. Docker ComposeでLibreChatを起動・動作確認」での会話のトレース詳細を確認しましょう。
トレースの確認
上記で実行した会話の内容についてトレースを深堀りしてみます。
Langfuse UIの Tracing ページに移動します。
確認できる情報
主に以下のような内容がトレースから確認できます。
Trace ID（各会話に一意のIDが付与されています）
Timestamp（トレースが記録された日時）
User ID（LibreChat MongoDBのObjectIDと紐づく）
Session ID （LibreChatのスレッドID : ConversationIDと紐づく）
Input/Output（プロンプトとLLMの応答）
Latency（リクエストにかかった時間）
Tokens（入力トークン数と出力トークン数）
Cost（トークン使用量から計算されたコスト）
トレースの詳細を確認
特定のトレースをクリックすると、詳細情報が表示されます。
1. 実行フロー
トレースは階層構造で表示され、以下のような流れと各処理にかかったコストが確認できます。
また、自動的にエージェントの処理フローがグラフとしても表示されます。
2. プロンプト詳細
Input 、Output セクションには、実際にLLMに送信されたプロンプトとLLMからの応答がが表示されます。
3. パフォーマンスメトリクス
パフォーマンス関連のメトリクスとしては以下のようなものが確認できます。
Latency（リクエストの開始から完了までの時間）
Time to First Token (TTFT)（最初のトークンが生成されるまでの時間）
これらの指標により、モデルのパフォーマンスを定量的に評価できます。
複数の会話スレッドを確認
LibreChatで新規チャットを開始すると、新しい Conversation ID が付与されます。Langfuse UIの Sessions ページで、Conversation ID ごとにグループ化された会話を確認できます。
これにより、ユーザーがどのような会話の流れを持っているかを追跡できます。
コスト分析
デフォルトで用意されている Langfuse Cost Dashboard ページにより、
以下のようなコスト分析が可能です。
総コスト（トークン使用量から計算された総コスト）
モデル別コスト（どのモデルがどれだけコストを使っているか）
ユーザー別コスト（どのユーザーがどれだけコストを使っているか）
検証1のまとめ
基本的なトレース送信機能の検証により、以下のことが確認できました。
LibreChatからLangfuseへのトレース送信が正常に動作
会話内容、パフォーマンスメトリクスが正確に記録される
Sessions から ConversationIDごとの、会話を追跡できる
トークン使用量とコストを可視化できる
次は、MCP Server機能を使用した場合のトレースを確認します。
検証編2 - MCP Server利用時のトレース
LibreChatはMCP (Model Context Protocol) Serverをサポートしており、LLMにツール実行機能を追加できます。ここでは、MCP Serverを設定し、ツール呼び出し時のトレースがどのように記録されるかを確認します。
MCP Serverの設定
Langfuse Docs MCP Serverを設定する例を示します。
librechat.yamlの更新
librechat.yaml を編集し、mcpServers セクションに以下の設定を追加します。
mcpServers:
langfuse-docs:
command: npx
args:
- "-y"
- "mcp-remote"
- "https://langfuse.com/api/mcp"
metadata:
name: "Langfuse Documentation"
description: "Access to Langfuse official documentation via MCP"追記後の librechat.yaml は下記セクションを参照ください。
librechat.yaml
# Configuration version (required)
version: 1.3.5
# Cache settings: Set to true to enable caching
cache: true
# Endpoints Configuration
endpoints:
# OpenAI Configuration
openAI:
apiKey: "${OPENAI_API_KEY}"
models:
default:
- "gpt-5"
- "gpt-5-mini"
- "gpt-5-nano"
titleConvo: true
summarize: false
titleModel: "gpt-5-nano"
# Agents Configuration
# Langfuse tracing is enabled for Agents
agents:
disableBuilder: false # Enable Agent Builder UI
recursionLimit: 25 # Default steps an agent can take
maxRecursionLimit: 50 # Maximum steps limit
# MCP Server Configuration
mcpServers:
langfuse-docs:
command: npx
args:
- "-y"
- "mcp-remote"
- "https://langfuse.com/api/mcp"
metadata:
name: "Langfuse Documentation"
description: "Access to Langfuse official documentation via MCP"
registration:
socialLogins: []設定の反映
# LibreChatコンテナを再起動
docker compose restart api
# ログを確認
docker compose logs -f api起動ログに以下のようなメッセージが表示されれば、MCP Serverが正常に起動しています。
info: MCP servers initialized successfully. Added 3 MCP tools.MCP Serverを使った会話
LibreChat UIに戻り、新しい会話を開始します。MCP Serverが有効化されている場合、チャット欄に「MCP サーバー」という欄が表示され、「MCP サーバー」を押下すると langfuse-docs が選択できます。
langfuse-docs にチェックを入れた後、以下のような指示をLLMに依頼しましょう。
すると、LLMは langfuse-docs の Tool : searchLangfuseDocs を利用して調査しその内容を下に回答を生成してくれます。（生成された回答は長いので一部省略）
Langfuse UIでMCP Serverトレースを確認
MCP Serverを使用した会話のトレースを確認します。
Toolの利用
LLMがToolを利用した記録を確認できます。
また、Toolの Input、Outpuより、呼び出し（クエリ内容）とそれに対する戻り値（クエリ結果）が確認できます。
（Outputは階層が深いので一部省略。）
検証2のまとめ
MCP Server利用時のトレース検証により、以下のことが確認できました。
MCP Serverのツール呼び出しが正確にトレースされる
ツール呼び出しのパラメータと戻り値が記録される
まとめ
LibreChat v0.8.1で追加されたLangfuse統合機能を、外部Langfuse接続で検証しました。
良かった点
セットアップが簡単（Langfuseの環境変数を3つ追加するだけで動作）
コード変更なしで会話が自動的にトレースされる
User ID、Conversation IDなどのメタデータが自動記録されLangfuse上でトレースがグルーピングされる
MCP Serverのツール呼び出しも含めてトレースされる
こんな人におすすめ
既にLangfuseを使っていて、LibreChatの会話も一元管理したい方
企業内でLLMチャットUIを提供し、利用状況を可視化したい方
MCP Serverやエージェント機能のデバッグに詳細なトレース情報が必要な方
今後の期待
今回の検証では、トレースに記録されるObservation Typeが主に generation（LLM呼び出し）に限られていることも確認できました。
Langfuseは generation 以外にも、agent、tool、など多彩なObservation Type をサポートしています。
例えば、MCP Serverのツール呼び出しが tool 型として記録されるようになれば、Langfuse UI上でのフィルタリングや分析がより直感的になるはずです。
LibreChatのLangfuse統合はv0.8.1で初めて導入された機能です。今後のバージョンアップでこれらのObservation Typeへの対応が進むことで、トレースの表現力がさらに向上し、より実践的なオブザーバビリティが実現できるのではないかと期待しています。
参考リンク
LibreChat公式ドキュメント: https://www.librechat.ai/docs
Langfuse公式ドキュメント: https://langfuse.com/docs
Langfuse LibreChat統合ガイド: https://langfuse.com/integrations/other/librechat
LibreChat PR #10292 (Langfuse統合): https://github.com/danny-avila/LibreChat/pull/10292
コメント