スパンの概念

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 呼び出しのset_attributes()の例:

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	他のタイプが指定されていない場合のデフォルトのタイプ

スパンタイプの設定

デコレーターまたはコンテキスト マネージャーでspan_type問題を使用して、 SpanTypeを設定します。

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.traceで装飾された関数やスパン コンテキスト マネージャーなどでアクティブにログに記録されているものです。デコレートされた関数またはコンテキスト マネージャーが終了すると、スパンは終了し、不変のSpanになります。

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

RETRIEVERスパンスキーマ

RETRIEVERスパン タイプは、ベクター ストアからのドキュメントのクエリなど、データ ストアからデータを取得する操作を処理します。このスパン タイプには、強化された UI 機能と評価機能を有効にする特定の出力スキーマがあります。出力はドキュメントのリストになります。各ドキュメントは次の内容を持つ辞書です。

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

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

  • doc_uri ( str ): ドキュメント ソース URI。Databricksで一斉検索を使用する場合、RETRIEVER スパンには、完全なリネージ追跡のために、 doc_uriメタデータにUnity Catalogボリューム パスを含めることができます。
  • 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 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 docs

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

次のステップ

• トレースの概念- トレースレベルの概念と構造を理解する
• ノートブックでトレース- トレースを実際に体験してみましょう