スパンの概念

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 呼び出しの属性の例:

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 は、分類用に 10 個の定義済みスパンタイプを提供します。特殊な操作にはカスタム文字列値を使用することもできます。

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

スパンタイプの設定

デコレーターまたはコンテキストマネージャーで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})

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

SDK を使用してプログラムで範囲をクエリします。

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 でスパンの種類別にフィルターすることもできます。

特殊なスパンスキーマ

特定のスパンの種類には、強化された UI 機能と評価機能を有効にする特定の出力スキーマがあります。

RETRIEVERスパン

RETRIEVERスパンタイプは、ベクターストアからのドキュメントのクエリなど、データストアからデータを取得する操作を処理します。出力はドキュメントのリストになります。各ドキュメントは次の内容を持つ辞書です。

page_content ( str ): 取得したドキュメントチャンクのテキストコンテンツ
metadata ( Optional[Dict[str, Any]] ): 次のような追加のメタデータ:
- doc_uri ( str ): ドキュメントソース URI
- chunk_id ( str ): ドキュメントがより大きなチャンク化されたドキュメントの一部である場合の識別子
id ( Optional[str] ): ドキュメントチャンクの一意の識別子

実装例 :

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)

Databricks :一斉検索を使用する場合、完全なリネージ追跡のために、RETRIEVER スパンのdoc_uriメタデータにUnity Catalogボリュームパスを含めることができます。

CHAT_MODELスパン

タイプCHAT_MODELまたはLLMのスパンは、チャット補完APIs (たとえば、 OpenAIのチャット補完やAnthropicのメッセージAPI ) とのやり取りを表します。

入力と出力には厳密な形式要件はありませんが、MLflow は、豊富な UI の視覚化と評価のためにチャットメッセージとツール定義を標準化するユーティリティ関数を提供します。

Python
import mlflow
from mlflow.entities 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):
    # Simulate a response with tool calls
    response = {
        "role": "assistant",
        "tool_calls": [
            {
                "id": "123",
                "function": {"arguments": '{"a": 1,"b": 2}', "name": "add"},
                "type": "function",
            }
        ],
    }

    combined_messages = messages + [response]

    # Use MLflow utilities to standardize the format
    span = mlflow.get_current_active_span()
    set_span_chat_messages(span, combined_messages)
    set_span_chat_tools(span, tools)

    return response

# Usage
call_chat_model(messages, tools)

# Retrieve the standardized data
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))

次のステップ

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

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

スパン属性​

スパンの種類​

スパンタイプの設定​

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

特殊なスパンスキーマ​

RETRIEVERスパン​

CHAT_MODELスパン​

次のステップ​