OllamaとLangfuseでLLM可観測性を実装する方法｜プロンプト・レスポンス・トークン使用量をローカル環境でトレースする手順

この記事のポイント

・LangfuseはDocker Composeでセルフホストでき、プロンプト・レスポンス・トークン使用量を完全ローカルで記録できる
・langfuse.openaiのOpenAIラッパーをOllamaのbase_urlに向けるだけで既存コードをほぼ変更なしにトレース対応にできる
・@observeデコレータを付けるだけでRAGパイプライン全体をネストスパンとして可視化できる
・ClickHouseに全文保存するためディスク容量管理とデータ保持期間の設定が本番運用の鉄則

# Dockerの公式リポジトリからインストール
$ sudo apt update
$ sudo apt install ca-certificates curl gnupg -y
$ sudo install -m 0755 -d /etc/apt/keyrings
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
$ sudo apt update
$ sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

# 動作確認
$ docker --version
Docker version 27.x.x, build xxxxxxx
$ docker compose version
Docker Compose version v2.x.x

# Langfuseのリポジトリをクローン
$ git clone https://github.com/langfuse/langfuse.git
$ cd langfuse

# .envファイルをサンプルからコピー
$ cp .env.example .env

# NEXTAUTH_SECRET と SALT をランダム値で設定する（必須）
$ sed -i "s|NEXTAUTH_SECRET=.*|NEXTAUTH_SECRET=$(openssl rand -hex 32)|" .env
$ sed -i "s|SALT=.*|SALT=$(openssl rand -hex 16)|" .env

# 設定内容を確認
$ grep -E "NEXTAUTH_SECRET|SALT" .env
NEXTAUTH_SECRET=a3f8c2...（ランダム値）
SALT=9d4e...（ランダム値）

# Docker Composeで起動（初回はイメージのダウンロードに数分かかる）
$ docker compose up -d

# コンテナの起動状態を確認
$ docker compose ps
NAME                 IMAGE               STATUS
langfuse-web         langfuse/langfuse   Up (healthy)
langfuse-worker      langfuse/langfuse   Up
langfuse-db          postgres:15         Up (healthy)
langfuse-ch          clickhouse          Up (healthy)

# Python仮想環境を作成して有効化
$ python3 -m venv langfuse-env
$ source langfuse-env/bin/activate

# Langfuse SDK と OpenAIクライアントをインストール
$ pip install langfuse openai

# インストール確認
$ pip show langfuse | grep Version
Version: 2.x.x

# ~/.bashrc または .env に追記
export LANGFUSE_PUBLIC_KEY="pk-lf-xxxxxxxxxxxxxxxxxxxx"
export LANGFUSE_SECRET_KEY="sk-lf-xxxxxxxxxxxxxxxxxxxx"
export LANGFUSE_HOST="http://localhost:3000"

# openai.OpenAI の代わりに langfuse.openai.OpenAI を使う
from langfuse.openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # Ollamaはapi_keyを使わないがクライアントの仕様で設定が必要
)

response = client.chat.completions.create(
    model="llama3.3:70b-instruct-q4_0",
    messages=[
        {"role": "system",  "content": "あなたはLinuxの専門家です。"},
        {"role": "user",    "content": "journalctlでエラーログだけを抽出する方法を教えてください。"},
    ],
    name="journalctl-query",  # Langfuseのトレース名（任意）
)

print(response.choices[0].message.content)

# SDKの内部バッファをフラッシュしてLangfuseに確実に送信する
from langfuse.openai import langfuse_context
langfuse_context.flush()

from langfuse.decorators import observe, langfuse_context
from langfuse.openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

@observe()
def call_ollama(prompt: str, model: str = "llama3.3:70b-instruct-q4_0") -> str:
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

@observe()
def analyze_log_line(log_line: str) -> dict:
    """ログ1行を分析してカテゴリと重要度を返す（@observeで親スパンになる）"""
    summary = call_ollama(f"以下のLinuxログを分析してください:\n{log_line}")
    return {"log": log_line, "analysis": summary}

# analyze_log_lineが親スパン、call_ollamaが子スパンとしてLangfuseに記録される
result = analyze_log_line("kernel: EXT4-fs error (device sda1): ext4_find_entry:1455")
print(result["analysis"])
langfuse_context.flush()

import requests
from langfuse import Langfuse

langfuse = Langfuse(
    public_key="pk-lf-xxxxxxxxxxxxxxxxxxxx",
    secret_key="sk-lf-xxxxxxxxxxxxxxxxxxxx",
    host="http://localhost:3000"
)

trace = langfuse.trace(name="manual-trace-example")
generation = trace.generation(
    name="llama3.3-generation",
    model="llama3.3:70b-instruct-q4_0",
    input=[{"role": "user", "content": "Linuxのdiskio監視方法は？"}],
)

res = requests.post("http://localhost:11434/api/chat", json={
    "model": "llama3.3:70b-instruct-q4_0",
    "messages": [{"role": "user", "content": "Linuxのdiskio監視方法は？"}],
    "stream": False,
})
data = res.json()

# Ollamaのレスポンスに含まれるトークン数をLangfuseに記録する
generation.end(
    output=data["message"]["content"],
    usage={
        "input":  data.get("prompt_eval_count", 0),
        "output": data.get("eval_count", 0),
    }
)
langfuse.flush()

from langfuse.decorators import observe, langfuse_context
from langfuse.openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

@observe()
def summarize_document(doc_id: str, content: str) -> str:
    """1ドキュメントを200字で要約する（子スパン）"""
    response = client.chat.completions.create(
        model="llama3.3:70b-instruct-q4_0",
        messages=[{"role": "user", "content": f"以下を200字で要約してください:\n{content}"}],
    )
    return response.choices[0].message.content

@observe()
def batch_summarize(documents: list) -> list:
    """ドキュメントリストをバッチ要約する（親スパン）"""
    results = []
    for doc in documents:
        summary = summarize_document(doc_id=doc["id"], content=doc["body"])
        results.append({"id": doc["id"], "summary": summary})
    return results

docs = [
    {"id": "doc-001", "body": "Linuxのカーネルパラメータ調整..."},
    {"id": "doc-002", "body": "iptablesのルール設定..."},
    {"id": "doc-003", "body": "systemdサービス管理..."},
]
batch_summarize(docs)
langfuse_context.flush()

# Langfuseコンテナのボリューム使用量を確認
$ docker system df
TYPE            TOTAL    ACTIVE   SIZE      RECLAIMABLE
Volumes         4        4        8.7GB     0B

# ClickHouseデータボリュームのサイズを個別確認
$ docker volume inspect langfuse_clickhouse-data --format '{{.Mountpoint}}' | xargs sudo du -sh
3.2G    /var/lib/docker/volumes/langfuse_clickhouse-data/_data

# Webコンテナのエラーログを確認
$ docker compose logs langfuse-web --tail 50

# よくあるエラー: NEXTAUTH_SECRET が未設定
Error: You must set NEXTAUTH_SECRET environment variable.

# 対処: .envにNEXTAUTH_SECRETが正しく設定されているか確認する
$ grep NEXTAUTH_SECRET .env
NEXTAUTH_SECRET=a3f8c2...（空でないこと）

# 設定変更後はコンテナを再起動する
$ docker compose down && docker compose up -d

ローカルLLMの本番運用を2日間のハンズオンで習得する

Langfuseによるトレース設計からOllamaの本番構成まで、実機GPU環境で手を動かしながら習得したい方向けに、「ローカルAIマスターセミナー」を開催しています。
少人数（最大8名）ZOOMハンズオン形式で実施しています。