⚡MLflow Tracing入門⚡ LLM・Retriever・Toolを1つのTraceで可視化する方法
📚 参考書籍
※この記事は書籍の一部をベースに再構成しています。もう少し踏み込んだ内容（設計や具体例）は書籍の中でまとめているので、気になる方はそちらもどうぞ。
本書は、AI Agentを「作って動かす」だけでなく、その品質をどう観測し、どう評価し、どう守り、どう説明可能にするかを体系的に学ぶための入門書です。
⚡MLflow Tracing入門⚡ LLM・Retriever・Toolを1つのTraceで可視化する方法
AI AgentはLLMだけで動きません。RAGの検索や外部システムのToolも利用します。誤回答の原因を特定するには、一連の処理を1つのTraceで記録することが重要です。
1. TraceとSpanの基本
「社員の残り有給休暇を確認するAgent」を例に考えます。
Retriever：休暇規程を検索
Tool：人事システムから残日数を取得
LLM：取得情報から回答を生成
MLflowでは、全体をTrace、各処理をSpanとして記録します。AGENT、RETRIEVER、TOOLなどのSpan Typeで役割を区別できます。
2. Retrieverを記録する
@mlflow.trace(span_type=SpanType.RETRIEVER)で、検索Queryと取得文書を追跡できます。
文書ID・順位・スコアも検索品質の分析に役立ちます。文書出力にはpage_contentとmetadataなどを利用します。
3. LLMはAutologで記録する
OpenAI SDKではmlflow.openai.autolog()を有効にするだけで、対応するLLM呼び出しを記録できます。
Prompt・Response
Model名・Token Usage
Latency・エラー
Responses APIにも対応しています。
4. Toolの引数と結果を記録する
SpanType.TOOLを指定すると、例えば次の情報を確認できます。
Input：employee_id = E001
Output：remaining_days = 8
引数と返却結果が障害調査の鍵です。
5. Agent全体を1つのTraceにまとめる
Manual TracingとAutomatic Tracingを組み合わせた例です。検索とToolは説明用の固定値を返します。
[
import mlflow
from mlflow.entities import SpanType
from openai import OpenAI
mlflow.set_experiment("leave-agent")
mlflow.openai.autolog()
client = OpenAI()
@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_policy(query):
return [{
"page_content": "有給休暇は社員ごとの付与日数で管理します。",
"metadata": {"doc_uri": "leave-policy-01"}
}]
@mlflow.trace(span_type=SpanType.TOOL)
def get_remaining_leave(employee_id):
return {"employee_id": employee_id, "remaining_days": 8}
@mlflow.trace(span_type=SpanType.AGENT)
def run_agent(question, employee_id):
docs = retrieve_policy(question)
leave = get_remaining_leave(employee_id)
response = client.responses.create(
model="gpt-4o-mini",
input=f"質問: {question}\n規程: {docs}\n残日数: {leave}"
)
return response.output_text
print(run_agent("残りの有給休暇は何日？", "E001"))
]
Retriever・Tool・LLMが子Spanとして表示されます。この例ではToolを事前に呼び、LLMに選択させていません。
6. Traceで誤回答を切り分ける
Agentが「残り5日」と誤回答した場合、Traceを確認します。
Retriever：正しい規程を取得したか
Tool：実際に8日を返したか
LLM：8日を受け取り、5日と誤生成したか
Toolが正しければ回答生成側、Tool自体が誤っていれば外部APIや元データを調査します。
本番では個人情報のマスキングと閲覧権限も設計します。
まとめると
Trace：Agent全体の実行履歴
Span：各処理のInput・Output
Manual Tracing：独自処理を計測
Automatic Tracing：LLM呼び出しを自動記録
MLflow TracingはAI Agentをブラックボックスにせず、失敗箇所を調査できる仕組みです。継続監視ではLog・Metric・Eventも組み合わせます。
