実行プログラムと拡張機能
最終更新
Langfuseでローカルエージェントの遅い処理を見つける
1回の回答にかかった時間をモデル・検索・ツールに分けると、遅い箇所を調べやすくなります。
Langfuseはアプリが明示的に送信したトレースイベントを表示します。ローカルインスタンスとPython SDK v4を使う場合、API1のbase URLをそのインスタンスに設定し、@observeで関数呼び出しを記録します。Langfuseを導入しただけで任意のOllamaリクエストが自動記録されるわけではありません。計測した入出力に個人情報や文書内容が含まれる可能性があるため、記録項目を選び機密値をマスクしてください。
ローカルエージェントのモデル呼び出し・ファイル読み込み・ツール実行のどこで待つか調べるときにLangfuseを使います。Python SDKのイベントから各段階の開始・終了・所要時間を確認できます。以下ではローカルOllamaと合成ファイルを計測し、入力・出力本文は記録しません。
応答全体の時間を処理段階に分ける
エージェントが遅い原因は、トークン2生成とは限りません。検索、ファイル読み込み、ツール待機、再試行、回答生成が順に発生します。Langfuse traceに各段階を記録すると、同じテスト入力でどの区間が長くなったか確認できます。

ローカルインスタンスを起動しSDK計測環境を準備する
リポジトリルートのdocker-compose.ymlで# CHANGEMEが付いた値をすべて置き換えます。Webサービスのportsを127.0.0.1:3000:3000に制限し、NEXTAUTH_URLもhttp://localhost:3000に設定します。docker compose up -dとdocker compose psを実行し、ポートが127.0.0.1:3000->3000/tcpと表示されることを確認します。
docker compose logs -f langfuse-webにReadyと表示されたら、ブラウザーでhttp://localhost:3000を開きます。サインアップ画面で最初のユーザーを作成し、プロジェクトのSettings → API Keysで公開キーとシークレットキーを発行します。
git clone https://github.com/langfuse/langfuse.git langfuse-local
cd langfuse-local
# 저장소 루트 docker-compose.yml에서 # CHANGEME 값을 바꾸고 NEXTAUTH_URL을 맞춰요.ports:
- "127.0.0.1:3000:3000"docker compose up -d
docker compose ps
docker compose logs -f langfuse-web
SDK v4でモデル呼び出しとツール処理を記録する
Python環境にlangfuseとrequestsをインストールし、プロジェクトの公開・秘密APIキー、LANGFUSE_BASE_URL=http://localhost:3000、取得済みのOllamaモデルIDを環境変数に設定します。@observeが親request spanを作り、get_client()のcontext managerがOllama generationとファイル読み込みtoolをその下に記録します。本文は入出力に設定せず、状態と文字数だけをmetadataに残します。
python -m venv .venv
source .venv/bin/activate
python -m pip install -U langfuse requests
export LANGFUSE_PUBLIC_KEY='pk-lf-project-key'
export LANGFUSE_SECRET_KEY='sk-lf-project-secret'
export LANGFUSE_BASE_URL='http://localhost:3000'
export OLLAMA_MODEL='YOUR_INSTALLED_MODEL_ID'環境変数を設定してから以下をrun_trace.pyに保存します。固定プロンプト3でOllamaを1回呼び、合成テキストファイルを読みます。traceには2段階の所要時間と状態だけを残します。
import os
from pathlib import Path
import requests
from langfuse import get_client, observe, propagate_attributes
MODEL = os.environ['OLLAMA_MODEL']
langfuse = get_client()
@observe(name='local-agent-request', as_type='span', capture_input=False, capture_output=False)
def run_trace():
with propagate_attributes(trace_name='local-agent-toy', session_id='toy-session-1'):
with langfuse.start_as_current_observation(as_type='generation', name='ollama-chat', model=MODEL) as generation:
response = requests.post('http://127.0.0.1:11434/api/chat', json={'model': MODEL, 'stream': False, 'messages': [{'role': 'user', 'content': 'Reply with exactly: local trace test'}]}, timeout=120)
response.raise_for_status()
generation.update(metadata={'http_status': response.status_code})
with langfuse.start_as_current_observation(as_type='tool', name='read-toy-file') as tool:
text = Path('fixture.txt').read_text(encoding='utf-8')
tool.update(metadata={'file': 'fixture.txt', 'characters': len(text)})
print('Ollama status:', response.status_code, '| fixture characters:', len(text))
run_trace()
langfuse.flush()printf '%s\n' 'Synthetic fixture for a local tracing example.' > fixture.txt && python run_trace.py機密性のない固定入力でtraceを確認する
Tracesにlocal-agent-toyが表示されたら開き、親span、その子のollama-chat generationとread-toy-file tool、各所要時間と記録されたmetadataを確認します。
最初に401/403が出たら、公開・秘密キーが同じプロジェクトのものか、API URLがhttp://localhost:3000か確認します。接続エラーではサービス状態とdocker compose psのPORTSを、Ollamaエラーではcurl http://127.0.0.1:11434/api/tagsの応答を確認します。
合成プロンプトとfixtureだけを使い、文書本文やモデル応答をtraceの入出力には設定しません。

用語の注釈
よくある質問
- この記事で最初に確認すべきことは何ですか?
- Langfuseはアプリが明示的に送信したトレースイベントを表示します。ローカルインスタンスとPython SDK v4を使う場合、APIのbase URLをそのインスタンスに設定し、`@observe`で関数呼び出しを記録します。Langfuseを導入しただけで任意のOllamaリクエストが自動記録されるわけではありません。計測した入出力に個人情報や文書内容が含まれる可能性があるため、記録項目を選び機密値をマスクしてください。
