スパンの概念

Spanオブジェクトは、Traceデータモデルにおける基本的な構成要素です。各スパンは、トレースにおける単一のステップを捉えます。例えば、LLM呼び出し、ツール実行、または取得操作などです。

スパンはトレース内で階層的に編成され、アプリケーションの実行フローを表します。各スパンは次のものをキャプチャします:

• 入力データと出力データ
• 時間情報（開始時間と終了時間）
• ステータス（成功またはエラー）
• 操作に関するメタデータと属性
• 他のスパンとの関係（親子関係）

スパンオブジェクトスキーマ

MLflow SpanスキーマはOpenTelemetry仕様と互換性があります。このスキーマには11個のコアプロパティがあります。

属性	Type	説明
span_id	str	トレース内のこのスパンの一意の識別子
trace_id	str	リンクは親トレースにまたがる
parent_id	Optional[str]	親子関係を確立する。ルートスパンの場合はNoneに設定します。
name	str	ユーザー定義または自動生成されたスパン名
start_time_ns	int	span が開始されたときの Unix タイムスタンプ (ナノ秒)
end_time_ns	int	スパンが終了したときの Unix タイムスタンプ (ナノ秒)
status	SpanStatus	スパンのステータス: OK 、 UNSET 、またはERROR （オプションの説明付き）
inputs	Optional[Any]	この操作に入る入力データ
outputs	Optional[Any]	この操作から出力されるデータ
attributes	Dict[str, Any]	行動に関する知識を提供するメタデータ キーと値のペア
events	List[SpanEvent]	システムレベルの例外とスタックトレース情報

詳細については、 MLflow APIリファレンスを参照してください。

スパン属性

属性はキーと値のペアであり、関数およびメソッド呼び出しの動作変更に関する情報を提供します。 操作の構成と実行コンテキストに関するメタデータをキャプチャします。

プラットフォーム固有の属性を追加することで、可観測性を向上させることができます。たとえば、スパンが接続したUnity Catalogオブジェクト、モデルサービング エンドポイント、またはコンピュートリソースを追加できます。

例えば、LLM呼び出しをラップするspan要素に属性を設定します。

Python

span.set_attributes({
    "ai.model.name": "claude-3-5-sonnet-20250122",
    "ai.model.version": "2025-01-22",
    "ai.model.provider": "anthropic",
    "ai.model.temperature": 0.7,
    "ai.model.max_tokens": 1000,
})

スパンの種類

MLflowは、一般的な操作に対して定義済みのSpanType値を提供します。特殊なケースでは、スパンタイプとしてカスタム文字列値を渡してください。

Type	説明
CHAT_MODEL	チャットモデルへのクエリ（特殊な LLM インタラクション）
CHAIN	一連の操作
AGENT	自律エージェント操作
TOOL	検索クエリなどのツール実行（通常はエージェントによる）
EMBEDDING	テキスト埋め込み操作
RETRIEVER	ベクトルデータベースクエリなどのコンテキスト検索操作
PARSER	テキストを構造化形式に変換する解析操作
RERANKER	関連性に基づいてコンテキストを順序付ける再ランク付け操作
MEMORY	長期記憶におけるコンテキストの永続化
UNKNOWN	他の型が指定されていない場合に使用されるデフォルトの型

スパンタイプの設定

スパンのSpanTypeを設定するには、 span_typeデコレータまたはコンテキストマネージャに渡します。

Python

import mlflow
from mlflow.entities import SpanType

# Using a built-in span type
@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_documents(query: str):
    ...

# Using a custom span type
@mlflow.trace(span_type="ROUTER")
def route_request(request):
    ...

# With context manager
with mlflow.start_span(name="process", span_type=SpanType.TOOL) as span:
    span.set_inputs({"data": data})
    result = process_data(data)
    span.set_outputs({"result": result})

タイプによるスパンの検索

MLflow search_spans()を使用してプログラムでクエリ範囲を実行します。

Python

import mlflow
from mlflow.entities import SpanType

trace = mlflow.get_trace("<trace_id>")
retriever_spans = trace.search_spans(span_type=SpanType.RETRIEVER)

トレースを表示するときに、MLflow UI でスパンの種類別にフィルターすることもできます。

アクティブスパンと終了スパン

アクティブなスパン（ LiveSpanで表される）は、MLflowが現在書き込みを行っているスパンです。アクティブなスパンは、 @mlflow.traceで装飾された関数、またはスパンコンテキストマネージャによって生成されます。装飾された関数が終了するか、コンテキストマネージャが閉じられると、スパンは終了し、不変のSpanになります。

アクティブなスパンを変更するには、 mlflow.get_current_active_span()を使用してそれを取得します。

RETRIEVERスパンスキーマ

RETRIEVERスパン型は、データストアからデータを取得する操作を表します。たとえば、ベクターストアからドキュメントを照会する操作などです。RETRIEVER スパンは固定出力スキーマを使用するため、MLflow のより豊富な UI レンダリングおよび評価機能が利用可能になります。出力はドキュメントのリストでなければならず、各ドキュメントは以下の内容を含む辞書である。

• page_content ( str ): 取得したドキュメントチャンクのテキストコンテンツ

• metadata ( Optional[Dict[str, Any]] ): 次のような追加のメタデータ:

  • doc_uri ( str ): ドキュメントのソース URI。 Databricksで共通検索を使用すると、完全なリネージ追跡のためにUnity Catalogボリューム パスをdoc_uriに記録できます。
  • chunk_id ( str ): ドキュメントがより大きなチャンク化されたドキュメントの一部である場合の識別子。

• id ( Optional[str] ): ドキュメントチャンクの一意の識別子。

この出力構造を構築するには、MLflow Documentエンティティを使用します。

実装例 :

Python

import mlflow
from mlflow.entities import SpanType, Document

def search_store(query: str) -> list[tuple[str, str]]:
    # Simulate retrieving documents (content, doc_uri pairs) 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):
    docs = search_store(query)
    span = mlflow.get_current_active_span()

    # Set outputs in the expected format
    outputs = [
        Document(page_content=doc, metadata={"doc_uri": uri})
        for doc, uri in docs
    ]
    span.set_outputs(outputs)

    # Return the raw tuples for the caller; the trace records the structured Document objects.
    return docs

# Usage
user_query = "MLflow Tracing benefits"
retrieved_docs = retrieve_relevant_documents(user_query)

次のステップ

• トレースの概念— トレースレベルの概念と構造を理解する。
• はじめに: MLflow Tracing for GenAI ( Databricksノートブック) — ノートブックでトレースを実際に体験してください。