トレースデータモデル

このドキュメントでは、MLflow トレース データ モデルの詳細な概要について説明します。 このモデルを理解することは、生成 AI アプリケーションの可観測性と分析のために MLflow トレースを活用するための鍵となります。

MLflowトレースは、観測性のために広く採用されている業界標準である OpenTelemetry 仕様と互換性のあるものに設計されています。 これにより、相互運用性が確保され、MLflow トレースをエクスポートし、他の OpenTelemetry 互換システムと共に使用できるようになります。 MLflow は、Generateive AI ユース ケースの特定の構造と属性を定義することで、基本的な OpenTelemetry Span モデルを強化し、より豊富なコンテキストと、品質とパフォーマンスに関するより深い洞察を提供します。

トレースの構造

大まかに言えば、MLflow トレース は 2 つの主要なオブジェクトで構成されます。

1. TraceInfo:
   • トレースの発生元、トレースの状態、合計実行時間に関する情報の説明に役立つメタデータ。
   • ユーザー、セッション、開発者が指定したキーと値のペアなど、トレースの追加コンテキストを提供するタグ。 タグは、トレースの検索またはフィルター処理に使用できます。
   • 人間や LLM ジャッジ、またはグラウンドトゥルース情報からの構造化されたフィードバック ラベルを、トレースやトレース内の特定のスパンに追加できる評価。
2. TraceData:
   • 実際のペイロード。入力から出力までのアプリケーションのステップ バイ ステップ実行をキャプチャする、インストルメント化された Span オブジェクトが含まれます。

1. トレース情報

MLflow のトレース機能内の TraceInfo は、トレース全体に関する重要なデータの軽量スナップショットを提供することを目的としています。 TraceInfo は、トレースに関するメタデータを含むデータクラス オブジェクトです。

このメタデータには、トレースの配信元、状態、およびその他のさまざまなデータに関する情報が含まれます。このデータは、 mlflow.client.MlflowClient.search_traces と共に使用される場合や、MLflow UI 内のトレースのナビゲーションに使用されるトレースの取得とフィルター処理に役立ちます。 TraceInfoメタデータを検索に使用する方法の詳細については、ここで例を参照してください。

次に示すように、 TraceInfo オブジェクトに含まれるデータを使用して、MLflow 追跡 UI 内のトレース ビュー ページを設定します。

MLflow TraceInfo オブジェクトの主なコンポーネントを次に示します。

メタデータ

評価

評価は、トレースにキャプチャされた GenAI アプリケーションの動作の品質と正確性を評価するために重要です。 これにより、トレースまたはトレース内の特定のスパンに、構造化されたラベルやスコア、基底情報を添付することができます。

MLflow では、基本 Assessment の概念を継承する 2 つの主要な種類の評価が定義されています。

1. フィードバック: 操作の出力に関する定性的または定量的な判断を表します。 これは、人間のレビュー担当者、ジャッジとしての LLM、またはカスタム スコアリング関数から取得できます。
2. 期待値: 特定の操作に対する地上の真実または予想される結果を表します。多くの場合、実際の出力との直接比較に使用されます。

評価は通常、 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"
)

フィードバック

フィードバックは、トレースまたはスパン出力の品質または特性に関する判断をキャプチャします。

キー フィールド:

例:

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)

期待

期待値は、操作の基準真実またはターゲット出力を定義します。

キー フィールド:

例:

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 (省略可能[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 の tags オブジェクトの TraceInfo プロパティは、トレースの追加のコンテキストを提供するために使用されます。 これらのタグは、トレースに関する検索、フィルター処理、または追加情報の提供に使用できます。

タグはキーと値のペアであり、変更可能です。 つまり、トレースが実験に記録された後でも、いつでもタグを追加、変更、または削除できます。

カスタム メタデータをキャプチャするカスタム タグを追加する方法については、「 カスタム タグ/メタデータをアタッチする」を参照してください。

標準タグ

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. トレース データ

TraceData経由でアクセスできる MLflow Trace.data オブジェクトは、トレースのコア ペイロードを保持します。 これには主に、発生した一連の操作 (スパン) と、トレースをトリガーした最初の要求と、生成された最終的な応答が含まれます。

キー フィールド:

• spans (リスト[Span]):

  • これは、トレース内の個々のステップ、操作、または関数呼び出しを表す Span オブジェクト ( mlflow.entities.Span および OpenTelemetry 仕様に準拠) の一覧です。 各スパンでは、特定の作業単位について詳しく説明します。
  • スパンは、実行フローを表すために parent_id を介して階層的に編成されます。
  • オブジェクトの詳細な内訳については、後述のSpan」セクションを参照してください。

• request (str):

  • トレースのルート スパンの入力データを表す JSON シリアル化文字列。 これは通常、エンド ユーザーの要求、またはトレースされたアプリケーションまたはワークフローを呼び出した初期パラメーターです。
  • 例: '{"query": "What is MLflow Tracing?", "user_id": "user123"}'

• response (str):

  • トレースされたアプリケーションまたはワークフローのルートスパンからの最終的な出力データを表す JSON シリアル化された文字列。
  • 例: '{"answer": "MLflow Tracing provides observability...", "confidence": 0.95}'

概念表現:

通常、クライアントを介して取得したTraceData オブジェクト (mlflow.entities.Trace など) を介してclient.get_trace(trace_id).dataを操作しますが、概念的には次のコア コンポーネントがバンドルされます。

# 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を理解することは、GenAI アプリケーションのライフサイクル全体で発生する詳細な実行パスとデータ変換をプログラムで分析する上で重要です。

スパン

MLflow のトレース機能内の Span オブジェクトは、トレースの個々のステップに関する詳細情報を提供します。

OpenTelemetry Span 仕様に準拠しています。各 Span オブジェクトには、span_id、名前、start_time、parent_id、状態、入力、出力、属性、イベントなど、インストルメント化されるステップに関する情報が含まれます。

スパン スキーマ

スパンはトレース データの中核です。 これらは、genai アプリケーション内の各ステップに関する重要なキー データを記録します。

MLflow UI 内でトレースを表示すると、次に示すようにスパンのコレクションが表示されます。

以下のセクションでは、スパンの構造の詳細を示します。

スパンの種類

スパン型は、トレース内のスパンを分類する方法です。 既定では、トレース デコレーターを使用する場合、スパンの種類は "UNKNOWN" に設定されます。 MLflow には、一般的なユース ケース用に定義済みのスパン型のセットが用意されていますが、カスタム スパンの種類を設定することもできます。

次のスパンの種類を使用できます。 さらに、スパンの種類を開発者が指定した任意の str 値に設定できます。

スパンの種類を設定するには、 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 スパン型は、データ ストアからデータを取得する操作 (ベクター ストアからドキュメントを照会するなど) に使用されます。 RETRIEVERスパンの出力は、ドキュメントの一覧である必要があります。

リスト内の各ドキュメントはディクショナリ (または次のキーを使用してディクショナリにシリアル化できるオブジェクト) である必要があり、理想的には次のものが含まれます。

• page_content (str): 取得したドキュメント チャンクのテキスト コンテンツ。
• metadata (Optional[Dict[str, Any]]): ドキュメントに関連付けられている追加のメタデータのディクショナリ。
  • MLflow UI と評価メトリックは、このメタデータ内で doc_uri (ドキュメント ソースの文字列 URI) と chunk_id (ドキュメントがより大きなチャンクドキュメントの一部である場合は文字列識別子) を検索して、表示と機能を強化することができます。
• id (Optional[str]): ドキュメント チャンク自体の省略可能な一意識別子です。

動作中のレトリバー スパンの例:

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やmetadataなどの関連するdoc_uriを含む) に準拠すると、RETRIEVERスパンが MLflow UI で有益にレンダリングされ (ドキュメント コンテンツの表示やリンクの提供など)、ダウンストリームの評価タスクで取得されたコンテキストを正しく処理できるようになります。

チャットの完了とツールの呼び出しスパン

CHAT_MODELまたはLLMの種類のスパンは、チャット入力候補 API (OpenAI のチャット入力候補、Anthropic のメッセージ 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 を使用したトレースのクエリ - データ モデルを使用してトレースをプログラムで分析する
• カスタム タグ/メタデータをアタッチ する - コンテキスト情報を使用してトレースを強化する

リファレンス ガイド

関連する概念に関する詳細なドキュメントを確認します。

• トレースの概念 - データ モデルの背後にある高度な概念を理解する
• ログ評価 - フィードバックと期待をトレースに添付する方法について説明します
• トレースの削除 - トレースのライフサイクルとクリーンアップを管理する