トレーシング・データ・モデル
このドキュメントでは、MLflow トレース データ モデルの詳細な概要について説明します。このモデルを理解することは、生成MLflow Tracing アプリケーションの可観測性と分析にAI を活用するための鍵となります。
MLflow トレースは、可観測性について広く採用されている業界標準である OpenTelemetry 仕様と互換性 があるように設計されています。これにより、相互運用性が確保され、MLflow トレースをエクスポートして他の OpenTelemetry 互換システムで使用できます。MLflow 、生成AI ユースケースの特定の構造と属性を定義することで、基本的なOpenTelemetry Spanモデルを強化し、品質とパフォーマンスに関する豊富なコンテキストと深い知見を提供します。
トレースの構造
大まかに言うと、MLflow トレース は 2 つの主要なオブジェクトで構成されます。
-
- 実際のペイロードには、入力から出力までのアプリケーションのステップバイステップの実行をキャプチャするインストルメント化された Span オブジェクトが含まれています。
これらのデータクラス オブジェクトのヘルパー メソッドに関する API のドキュメントを参照して、データ変換または抽出方法の詳細を確認してください。
1. トレース情報
MLflow のトレース機能内の TraceInfo は、トレース全体に関する重要なデータの軽量スナップショットを提供することを目的としています。TraceInfo は、トレースに関するメタデータを含むデータ・クラス・オブジェクトです。
このメタデータには、トレースの配信元、状態、および mlflow.client.MlflowClient.search_traces で使用するトレースの取得とフィルター処理、および MLflow UI 内でのトレースのナビゲーションに役立つその他のさまざまなデータに関する情報が含まれています。TraceInfoメタデータが検索にどのように使用されるかの詳細については、こちらで例をご覧ください。
パラメーター | データ型 | 説明 |
|---|---|---|
|
| トレースのプライマリ識別子。 |
|
| トレースが格納されている場所 (:p y:class: |
|
| トレースの開始時刻 (ミリ秒単位)。 |
|
| トレースの状態 (:p y:class: |
|
| モデル/エージェントへのリクエストは、ルートスパンの入力と同じですが、JSONでエンコードされており、切り捨てることができます。 |
|
| モデル/エージェントからの応答で、ルートスパンの出力と同じですが、JSONでエンコードされており、切り捨てることができます。 |
|
| トレースに関連付けられた要求 ID がクライアントから提供されました。これは、トレースを生成した外部システムからのトレース/リクエスト(WebアプリケーションのセッションIDなど)を識別するために使用できます。 |
|
| トレースの期間 (ミリ秒単位)。 |
|
| トレースに関連付けられたキーと値のペア。これらは、トレースに関連付けられた実行 ID などの不変の値用に設計されています。 |
| トレースに関連付けられたタグ。これらは変更可能な値用に設計されており、MLflow UI または API を使用してトレースを作成した後に更新できます。 | |
| トレースに関連付けられている評価の一覧。 |
TraceInfo オブジェクトに含まれるデータは、次に示すように、MLflow 追跡 UI 内のトレース ビュー ページを設定するために使用されます。
MLflow TraceInfo オブジェクトの主なコンポーネントを次に示します。
メタデータ
評価
評価は、トレースでキャプチャされた 生成AI アプリケーションの動作の品質と正確性を評価するために重要です。これにより、構造化されたラベル、スコア、またはグラウンド トゥルース情報をトレースまたはトレース内の特定の範囲にアタッチできます。
MLflow では、主に 2 種類の評価が定義されており、どちらも基本 Assessment の概念から継承されます。
- フィードバック : 操作の出力に関する定性的または定量的な判断を表します。これは、人間のレビュアー、LLM-as-a-judge、またはカスタムスコアリング機能から得られる可能性があります。
- 期待値 : 特定の操作のグラウンド トゥルースまたは予想される結果を表し、多くの場合、実際の出力と直接比較するために使用されます。
評価は通常、 mlflow.log_feedback()、 mlflow.log_expectation()、またはより一般的な mlflow.log_assessment()などの関数を使用してトレースに記録されます。
評価ソース
すべての評価は、その発生元を追跡するためのソースに関連付けられています。
-
source_type:mlflow.entities.AssessmentSourceType列挙型。主な値は次のとおりです。HUMAN: 人間が提供するフィードバックまたは期待。LLM_JUDGE:裁判官として行動するLLMによって生成される評価。CODE: プログラム ルール、ヒューリスティック、またはカスタム スコアラーによって生成された評価。
-
source_id: 特定のソースの文字列識別子 (例: ユーザー ID、LLM ジャッジのモデル名、スクリプト名)。
from mlflow.entities import AssessmentSource, AssessmentSourceType
# Example: Human source
human_source = AssessmentSource(
source_type=AssessmentSourceType.HUMAN,
source_id="reviewer_alice@example.com"
)
# Example: LLM Judge source
llm_judge_source = AssessmentSource(
source_type=AssessmentSourceType.LLM_JUDGE,
source_id="gpt-4o-mini-evaluator"
)
# Example: Code-based scorer source
code_source = AssessmentSource(
source_type=AssessmentSourceType.CODE,
source_id="custom_metrics/flesch_kincaid_scorer.py"
)
フィードバック
フィードバックは、トレースまたはスパン出力の品質または特性に関する判断をキャプチャします。
主なフィールド :
パラメーター | データ型 | 説明 |
|---|---|---|
|
| 評価の名前。指定しない場合は、デフォルト名 "feedback" が使用されます。 |
|
| フィードバック値。float、int、str、bool、これらの型のリスト、またはこれらの型の文字列キーと値を持つdictを指定できます。 |
|
| フィードバックに関連付けられたオプションのエラー。これは、フィードバックが有効でないか、または処理できないことを示すために使用されます。例外オブジェクト、:p y:class: |
|
| フィードバックの理論的根拠/正当化。 |
| 評価のソース。指定しない場合、デフォルトのソースは CODE です。 | |
|
| 評価に関連付けられたトレースの ID。設定されていない場合、評価はまだトレースに関連付けられていません。 |
|
| 評価に関連付けられているメタデータ。 |
|
| 評価に関連付けられたスパンの ID (評価をトレース内の特定のスパンに関連付ける必要がある場合)。 |
|
| 評価の作成時間 (ミリ秒単位)。設定されていない場合は、現在の時刻が使用されます。 |
|
| 評価の最終更新時刻 (ミリ秒単位)。設定されていない場合は、現在の時刻が使用されます。 |
次に例を示します 。
import mlflow
from mlflow.entities import Feedback, AssessmentSource, AssessmentSourceType
# Log simple binary feedback
mlflow.log_feedback(
trace_id="trace_123",
name="is_correct",
value=True,
source=AssessmentSource(source_type=AssessmentSourceType.HUMAN, source_id="user_bob"),
rationale="The answer provided was factually accurate."
)
# Log a numeric score from an LLM judge
llm_judge_feedback = Feedback(
name="relevance_score",
value=0.85,
source=AssessmentSource(source_type=AssessmentSourceType.LLM_JUDGE, source_id="claude-3-sonnet"),
rationale="The response directly addressed the user's core question.",
metadata={"judge_prompt_version": "v1.2"}
)
# Assuming trace_id is known, you can also use log_assessment
# mlflow.log_assessment(trace_id="trace_456", assessment=llm_judge_feedback)
期待
期待値は、オペレーションのグラウンドトゥルースまたはターゲット出力を定義します。
主なフィールド :
パラメーター | データ型 | 説明 |
|---|---|---|
|
| 評価の名前。 |
|
| 操作の期待値。これは、JSONでシリアル化可能な任意の値にすることができます。 |
| 評価のソース。指定しない場合、デフォルトのソースは HUMAN です。(詳細については、 評価ソース を参照してください)。 | |
|
| 評価に関連付けられたトレースの ID。設定されていない場合、評価はまだトレースに関連付けられていません。 |
|
| 評価に関連付けられているメタデータ。 |
|
| 評価に関連付けられたスパンの ID (評価をトレース内の特定のスパンに関連付ける必要がある場合)。 |
|
| 評価の作成時間 (ミリ秒単位)。設定されていない場合は、現在の時刻が使用されます。 |
|
| 評価の最終更新時刻 (ミリ秒単位)。設定されていない場合は、現在の時刻が使用されます。 |
次に例を示します 。
import mlflow
from mlflow.entities import Expectation, AssessmentSource, AssessmentSourceType
# Log a ground truth answer
mlflow.log_expectation(
trace_id="trace_789",
name="ground_truth_response",
value="The Battle of Hastings was in 1066.",
source=AssessmentSource(source_type=AssessmentSourceType.HUMAN, source_id="history_expert_01")
)
# Log an expected structured output for a tool call
expected_tool_output = Expectation(
name="expected_tool_call_result",
value={"result": {"status": "success", "data": "item_abc_123"}},
metadata={"tool_name": "inventory_check"}
)
# Assuming trace_id is known:
# mlflow.log_assessment(trace_id="trace_101", assessment=expected_tool_output)
評価エラー
フィードバックまたは期待値の生成または計算中に発生したエラー(LLMジャッジの失敗など)を記録するために使用されます。
主なフィールド :
error_code(str): エラーのコード (例: "RATE_LIMIT_EXCEEDED"、"JUDGE_ERROR")。error_message(オプション[str]): 詳細なエラーメッセージ。stack_trace(Optional[str]): スタックトレース (利用可能な場合)。
次に例を示します 。
import mlflow
from mlflow.entities import AssessmentError, Feedback, AssessmentSource, AssessmentSourceType
judge_error = AssessmentError(
error_code="LLM_JUDGE_TIMEOUT",
error_message="The LLM judge timed out after 30 seconds while assessing relevance."
)
mlflow.log_feedback(
trace_id="trace_error_example",
name="relevance_with_judge_v2",
source=AssessmentSource(source_type=AssessmentSourceType.LLM_JUDGE, source_id="custom_judge_model"),
error=judge_error
# Note: `value` is typically None when an error is provided
)
これらのエンティティは、豊富な定性的および定量的データをトレースに関連付けるための柔軟でありながら構造化された方法を提供し、MLflow Tracing 内の可観測性と評価機能の重要な部分を形成します。
タグ
MLflow の TraceInfo オブジェクトの tags プロパティは、トレースに追加のコンテキストを提供するために使用されます。これらのタグは、トレースに関する追加情報の検索、フィルタリング、または提供に使用できます。
タグはキーと値のペアであり、変更可能です。つまり、トレースがエクスペリメントに記録された後でも、いつでもタグを追加、変更、または削除できます。
カスタムタグを追加してカスタムメタデータをキャプチャする方法については、「 カスタムタグ/メタデータのアタッチ」を参照してください。
標準タグ
MLflow では、ユーザー、セッション、環境に関する一般的なコンテキスト情報に一連の標準タグが使用され、MLflow UI と SDK 内で強化されたフィルター処理とグループ化機能が可能になります。
mlflow.trace.session: ユーザーとセッションの追跡で導入されたセッション ID の標準タグ。mlflow.trace.user: ユーザーとセッションの追跡で導入されたユーザー ID の標準タグ。mlflow.source.name: トレースを生成したエントリポイントまたはスクリプト。mlflow.source.git.commit: Git リポジトリから実行する場合は、ソース コードのコミット ハッシュ。mlflow.source.type: トレースを生成したソース タイプで、通常はPROJECT( MLflow プロジェクト実行の場合) またはNOTEBOOK(ノートブックから実行する場合) です。
これらの実装方法の詳細については、 ユーザーとセッションの追跡 および 環境とコンテキストの追跡に関するガイドを参照してください。
2. トレースデータ
Trace.data経由でアクセスできる MLflow TraceData オブジェクトは、トレースのコア ペイロードを保持します。これには主に、発生した一連の操作 (スパン) と、トレースをトリガーした最初の要求、および生成された最終的な応答が含まれます。
主なフィールド :
-
spans(リスト[Span]):- これは、トレース内の個々のステップ、操作、または関数呼び出しを表す
Spanオブジェクト (mlflow.entities.Spanおよび OpenTelemetry 仕様に準拠) のリストです。各スパンには、特定の作業単位の詳細が表示されます。 - スパンは、実行フローを表すために
parent_idによって階層的に編成されます。 Spanオブジェクトの詳細な内訳については、以下の「スパンスキーマ」セクションを参照してください。
- これは、トレース内の個々のステップ、操作、または関数呼び出しを表す
request プロパティと response プロパティは、下位互換性のために保持されます。それらの値は、ルート スパンのそれぞれの inputs 属性と outputs 属性から検索され、ユーザーが TraceData オブジェクトに対して直接設定することはありません。
-
request(str):- トレースのルートスパンの入力データを表す JSON シリアル化された文字列。これは通常、エンドユーザーの要求、またはトレースされたアプリケーションまたはワークフローを呼び出した初期パラメーターです。
- 次に例を示します 。
'{"query": "What is MLflow Tracing?", "user_id": "user123"}'
-
response(str):- トレースされたアプリケーションまたはワークフローのルートスパンからの最終出力データを表す JSON シリアル化された文字列。
- 次に例を示します 。
'{"answer": "MLflow Tracing provides observability...", "confidence": 0.95}'
概念表現 :
通常、クライアントを介して取得されたmlflow.entities.Traceオブジェクト(client.get_trace(trace_id).dataなど)を介してTraceDataと対話しますが、概念的には、次のコアコンポーネントがバンドルされています。
# Conceptual structure (not direct instantiation like this)
class TraceData:
def __init__(self, spans: list[Span], request: str, response: str):
self.spans = spans # List of Span objects
self.request = request # JSON string: Overall input to the trace
self.response = response # JSON string: Overall output of the trace
TraceDataを理解することは、生成AI アプリケーションのライフサイクル全体で発生する詳細な実行パスとデータ変換をプログラムで分析するための鍵です。
またがる
MLflow のトレース機能内の Span オブジェクトは、トレースの個々のステップに関する詳細情報を提供します。
OpenTelemetry Span仕様に準拠しています。各 Span オブジェクトには、span_id、名前、start_time、parent_id、状態、入力、出力、属性、イベントなど、インストゥルメントされるステップに関する情報が含まれています。
スパンスキーマ
スパンはトレース データの中核です。これらは、生成AIアプリケーション内の各ステップに関する重要なデータを記録します。
MLflow UI 内でトレースを表示すると、次に示すように、スパンのコレクションが表示されます。
以下のセクションでは、スパンの構造について詳しく説明します。
スパン タイプ
スパンタイプは、トレース内のスパンを分類する方法です。デフォルトでは、トレースデコレータを使用すると、スパンタイプは "UNKNOWN" に設定されます。MLflow には、一般的なユース ケース用に定義済みのスパンの種類のセットが用意されているだけでなく、カスタム スパンの種類を設定することもできます。
次のスパンタイプを使用できます。また、スパン タイプを開発者が指定した任意の str 値に設定できます。
スパンタイプ | 説明 |
|---|---|
| チャット モデルに対するクエリを表します。これは、LLM インタラクションの特殊なケースです。 |
| 操作のチェーンを表します。 |
| 自律エージェント操作を表します。 |
| 検索エンジンのクエリなど、ツールの実行 (通常はエージェントによる) を表します。 |
| テキストの埋め込み操作を表します。 |
| ベクトル・データベースのクエリーなど、コンテキスト取得操作を表します。 |
| 解析操作を表し、テキストを構造化形式に変換します。 |
| 再ランク付け操作を表し、取得したコンテキストを関連性に基づいて順序付けます。 |
| 他のスパン・タイプが指定されていない場合に使用されるデフォルトのスパン・タイプ。 |
スパンタイプを設定するには、 span_type パラメーターを mlflow.trace デコレーターまたは mlflow.start_span コンテキストマネージャーに渡します。 自動トレースを使用している場合、スパンの種類は MLflow によって自動的に設定されます。
import mlflow
from mlflow.entities import SpanType
# Using a built-in span type
@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_documents(query: str):
...
# Setting a custom span type
with mlflow.start_span(name="add", span_type="MATH") as span:
span.set_inputs({"x": z, "y": y})
z = x + y
span.set_outputs({"z": z})
print(span.span_type)
# Output: MATH
特定のスパンタイプのスキーマ
MLflow には、定義済みの種類のスパンのセットがあり ( mlflow.entities.SpanTypeを参照)、特定のスパンの種類には、UI 内の追加機能や評価などのダウンストリーム タスクを有効にするために必要なプロパティがあります。
レトリーバースパン
RETRIEVER span 型は、データ ストアからデータを取得する操作 (たとえば、ベクトル ストアからのドキュメントのクエリ) に使用されます。RETRIEVERスパンの出力は、ドキュメントのリストであることが想定されます。
リスト内の各ドキュメントは、ディクショナリ (または次のキーを使用してディクショナリにシリアル化できるオブジェクト) である必要があり、理想的には次のものが含まれます。
-
page_content(str): 取得したドキュメントチャンクのテキストコンテンツ。 -
metadata(Optional[Dict[str, Any]]): ドキュメントに関連付けられた追加のメタデータのディクショナリ。- MLflow UI と評価メトリクスは、表示と機能を強化するために、このメタデータ内で
doc_uri(ドキュメント ソースの文字列 URI) とchunk_id(ドキュメントがより大きなチャンク ドキュメントの一部である場合は文字列識別子) を特に探すことができます。
- MLflow UI と評価メトリクスは、表示と機能を強化するために、このメタデータ内で
-
id(Optional[str]): ドキュメント チャンク自体のオプションの一意の識別子。
Retriever Span の動作例 :
import mlflow
from mlflow.entities import SpanType, Document
def search_store(query: str) -> list[(str, str)]:
# Simulate retrieving documents (e.g., from a vector database)
return [
("MLflow Tracing helps debug GenAI applications...", "docs/mlflow/tracing_intro.md"),
("Key components of a trace include spans...", "docs/mlflow/tracing_datamodel.md"),
("MLflow provides automatic instrumentation...", "docs/mlflow/auto_trace.md")
]
@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_relevant_documents(query: str):
# Get documents from the search store
docs = search_store(query)
# Get the current active span (created by @mlflow.trace)
span = mlflow.get_current_active_span()
# Set the outputs of the span in accordance with the tracing schema
outputs = [Document(page_content=doc, metadata={"doc_uri": uri}) for doc, uri in docs]
span.set_outputs(outputs)
# Return the original format for downstream usage
return docs
# Example usage
user_query = "MLflow Tracing benefits"
retrieved_docs = retrieve_relevant_documents(user_query)
# Read path: Reconstructing the document list from the span outputs
trace_id = mlflow.get_last_active_trace_id()
trace = mlflow.get_trace(trace_id)
span = trace.search_spans(name="retrieve_relevant_documents")[0]
documents = [Document(**doc) for doc in span.outputs]
print(documents)
この構造 (特に page_content や doc_uriなどの関連metadataを含める) 準拠すると、RETRIEVER スパンが MLflow UI で情報量的にレンダリングされ (ドキュメント コンテンツの表示やリンクの提供など)、ダウンストリームの評価タスクで取得したコンテキストを正しく処理できるようになります。
チャット完了とツールコールスパン
CHAT_MODEL または LLM タイプのスパンは、チャット完了 API との対話を表すために使用されます
(たとえば、OpenAIのチャットの完了、
または Anthropic's messages API)。これらのスパンは、モデルが使用できる、またはモデルによって使用されるツール (関数) に関する情報もキャプチャできます。
プロバイダは API に対して異なるスキーマを持つことができるため、生の LLM 呼び出し自体のスパンの入力と出力の形式に厳密な制限はありません。ただし、豊富な UI 機能 (会話の表示やツール呼び出しの視覚化など) を有効にし、評価用のデータを標準化するために、MLflow ではチャット メッセージとツール定義の特定の属性が定義されています。
上記のユーティリティ関数の使用方法の簡単なデモについては、以下の例を参照してください。
span.get_attribute() 関数を使用してそれらを取得する方法:
import mlflow
from mlflow.entities.span import SpanType # Corrected from mlflow.entities.span import SpanType
from mlflow.tracing.constant import SpanAttributeKey
from mlflow.tracing import set_span_chat_messages, set_span_chat_tools
# example messages and tools
messages = [
{
"role": "system",
"content": "please use the provided tool to answer the user's questions",
},
{"role": "user", "content": "what is 1 + 1?"},
]
tools = [
{
"type": "function",
"function": {
"name": "add",
"description": "Add two numbers",
"parameters": {
"type": "object",
"properties": {
"a": {"type": "number"},
"b": {"type": "number"},
},
"required": ["a", "b"],
},
},
}
]
@mlflow.trace(span_type=SpanType.CHAT_MODEL)
def call_chat_model(messages, tools):
# mocking a response
response = {
"role": "assistant",
"tool_calls": [
{
"id": "123",
"function": {"arguments": '{"a": 1,"b": 2}', "name": "add"},
"type": "function",
}
],
}
combined_messages = messages + [response]
span = mlflow.get_current_active_span()
set_span_chat_messages(span, combined_messages)
set_span_chat_tools(span, tools)
return response
call_chat_model(messages, tools)
trace = mlflow.get_last_active_trace()
span = trace.data.spans[0]
print("Messages: ", span.get_attribute(SpanAttributeKey.CHAT_MESSAGES))
print("Tools: ", span.get_attribute(SpanAttributeKey.CHAT_TOOLS))
次のステップ
これらの推奨アクションとチュートリアルで旅を続けてください。
- トレースを使用してアプリを計測可能にする - これらのデータ モデルの概念を適用して、アプリケーションにトレースを追加します
- SDK によるトレースのクエリ - データ モデルを使用して、プログラムでトレースを分析します
- カスタムタグ/メタデータの添付 - コンテキスト情報でトレースを充実させる
リファレンスガイド
関連する概念に関する詳細なドキュメントをご覧ください。