Posted in人工知能

OpenLLMetryとTraceloopを活用したLLMアプリケーションの監視とトレーシング実践ガイド

Artificial Intelligence tutorial - IT technology blog
Artificial Intelligence tutorial - IT technology blog

LLMアプリケーションを本番環境へデプロイする際の実課題

ローカル環境での検証時、生成AIアプリは極めてスムーズに動作しているように見えます。OpenAI APIやLangChainを呼び出すコードを数行書き、2〜3秒でレスポンスが返ってくれば、自信を持ってデプロイしたくなるものです。しかし、本番環境（Production）は全く異なる課題を突きつけてきます。

デプロイ直後から、次のような現実的な問題が次々と浮き彫りになります：

  • 深刻なレスポンス遅延： 1つのリクエスト処理に12〜15秒も要してしまう。テキストの埋め込み（Embedding）、Milvus/Pineconeへのベクトル検索、あるいはモデル自体の推論遅延のどこがボトルネックなのか特定できません。
  • トークンコストの急増： 月末のAPI利用料請求が3倍に跳ね上がる。どのワークフローが最もトークンを消費しているのか、どのアカウントやエージェントが無停電ループに陥っているのかを把握する術がありません。
  • サイレントエラー（潜在的障害）： モデルがJSONスキーマに違反した出力を返す、空のレスポンスを生成する、あるいはハルシネーションを起こす。バックエンド側では例外（Exception）が発生せずHTTP 200で意味不明なテキストを返却してしまうか、単にInternal Server Errorという簡素なログだけを残してクラッシュします。

複雑なマルチステップのRAGパイプラインにおいて、print()デバッグやテキストログの手動追跡に頼るのは、もはや現実的ではありません。

LLMのオブザーバビリティが従来のCRUDシステムと根本的に異なる理由

一般的なWebサービスであれば、処理フローはRoute → Controller → Database → Responseと極めて直線的です。従来のAPM（アプリケーションパフォーマンス監視）ツールは、SQLクエリの実行時間を計測し、HTTPステータスコードをキャッチするだけで十分でした。

しかし、LLMアプリケーションには以下のような固有の性質が存在します：

  • 非決定性（Non-deterministic）： まったく同じプロンプトを入力しても、推論ごとに生成されるトークン数や出力内容が変動します。
  • 複雑な呼び出しチェーン（Chains & Agents）： ユーザーの1回の入力に対して、2回の埋め込み生成、3回のベクトル検索、4回の中間ツール呼び出しが連鎖的にトリガーされることがあります。
  • SDKごとの仕様の不統一： OpenAI、Anthropic、ChromaDB、Cohereなど、各ベンダーが独自のペイロード形式を持っています。これらを横断してトレースを一元化する標準スキーマが存在しませんでした。

各実行スパン（Span）を個別に可視化・分析できなければ、深夜に発生した障害の根本原因を追究することは不可能です。

現在主流となっているLLMオブザーバビリティの3つのアプローチ

プロジェクトの規模や要件に応じて、一般的に以下の3つのアプローチが検討されます：

アプローチ1：自作デコレータと手動ロギング

自前で関数をデコレータでラップし、time.perf_counter()で実行時間を計測してプロンプトやレイテンシをJSONログファイルに書き出します。

  • メリット： 外部ライブラリへの依存がありません。
  • デメリット： 保守コストが高い点です。ビジネスロジックがロギングコードで汚染され、ネストした呼び出しフローを視覚的に把握できるウォーターフォール表示も得られません。

アプローチ2：独自仕様のマネージドプラットフォーム（ベンダーSDK）の採用

LangSmithやArize Phoenixといった特化型ソリューションを利用すると、完成度の高いダッシュボードを即座に導入できます。

  • メリット： 直感的なUIが用意されており、対応フレームワークであれば短時間でセットアップ可能です。
  • デメリット： ベンダーロックインに陥りやすい点です。トレースデータをDatadogやDynatraceへ転送したくなった場合や、LangChainからLlamaIndexあるいはカスタム実装へ移行する際、監視基盤の大部分を作り直す必要があります。

アプローチ3：OpenLLMetryとTraceloopによるOpenTelemetry標準化

OpenLLMetryは、Traceloopが主導して開発しているオープンソースツール群です。業界標準であるOpenTelemetry (OTel)を拡張し、LLM特有のセマンティック規約（Semantic Conventions）を定義しています。OpenAI、Anthropic、LangChain、ChromaDBなどの呼び出しを、モデル呼び出しコードを変更することなく自動計装（Auto-instrumentation）できます。

TraceloopとOpenLLMetryの実装手順

最も柔軟でおすすめなアプローチはtraceloop-sdkの利用です。クリーンな自動計装の恩恵を受けつつ、トレースデータをTraceloop Cloudや社内のJaeger/Grafanaクラスターへ容易にエクスポートできます。

ステップ1：ライブラリのインストール

プロジェクトの仮想環境内で、pipを使用してSDKをインストールします：

pip install traceloop-sdk openai

ステップ2：環境変数の設定

app.traceloop.comで無料アカウントを作成してAPIキーを取得し、環境変数にエクスポートします：

export TRACELOOP_API_KEY="tlp_your_api_key_here"
export OPENAI_API_KEY="sk-proj-your_openai_key"

ステップ3：PythonソースコードでのTraceloop初期化

Traceloopの強みはそのシンプルさにあります。アプリケーションのエントリーポイントで初期化処理を1行呼び出すだけで、以降のすべてのOpenAIリクエストが自動的にトレースされます。

import os
from traceloop.sdk import Traceloop
from openai import OpenAI

# 1. AIクライアントを呼び出す前にTraceloopを初期化
Traceloop.init(
    app_name="customer-support-bot",
    disable_batch=True  # トレースを即時送信（ローカルデバッグ時に非常に便利）
)

# 2. 通常通りOpenAIクライアントを初期化
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

def generate_answer(question: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "あなたは技術的な質問に簡潔に回答するアシスタントです。"},
            {"role": "user", "content": question}
        ],
        temperature=0.2
    )
    return response.choices[0].message.content

if __name__ == "__main__":
    user_query = "OpenTelemetryとは何ですか？なぜLLMに必要なのですか？"
    answer = generate_answer(user_query)
    print("モデルからの回答:", answer)

ステップ4：デコレータによるビジネスタスクのグルーピング

実際のパイプラインは、入力検証、データベース検索、モデル呼び出し、後処理など複数の工程で構成されます。@workflowデコレータと@taskデコレータを活用することで、ダッシュボード上でトレースツリーを構造化して可視化できます：

from traceloop.sdk.decorators import workflow, task
from openai import OpenAI

client = OpenAI()

@task(name="validate_input")
def check_prompt(prompt: str) -> bool:
    # 短すぎるプロンプトや無効な入力をブロック
    return len(prompt.strip()) > 5

@task(name="call_llm_service")
def ask_llm(prompt: str) -> str:
    res = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}]
    )
    return res.choices[0].message.content

@workflow(name="full_qa_pipeline")
def handle_user_request(query: str):
    if not check_prompt(query):
        return "質問が短すぎます。もう一度入力してください。"
    return ask_llm(query)

# ワークフローのテスト実行
handle_user_request("OpenLLMetryでJaegerにトレースを送信する設定方法は？")

ステップ5：ダッシュボードでのメトリクス分析

TraceloopやGrafana Tempoの管理画面を開くと、主要な指標を直感的に確認できます：

  • レイテンシの内訳（Latency Breakdown）： ウォーターフォールチャートにより各スパンの所要時間を把握できます（例：バリデーション処理に12ms、モデル推論に1,840msなど）。
  • トークン消費統計： プロンプトトークンと完了トークンをコールごとに正確に集計し、機能ごとのAPIコスト（USD）を正確に算出できます。
  • 詳細なペイロードデータ： 入力プロンプトと生成レスポンスを直接確認できるため、ユーザーからの障害報告時にもハルシネーションの発生を即座に特定可能です。

OpenTelemetry標準に準拠しているため、インフラの選択肢も制限されません。将来的にDatadogや自社のOtel Collectorへ切り替える場合も、TRACELOOP_BASE_URLなどの環境変数を向け先変更するだけで対応でき、ビジネスロジックの修正は一切不要です。

Share:
Tags: