メインコンテンツまでスキップ
に最終更新

プログラムでトレースを検索する

mlflow.search_traces()を使用して、プログラムでトレースを検索および分析します。この関数は、 MLflowトラッキング サーバー、推論テーブル、またはUnity Catalogテーブルに保存されているトレースをクエリできます。 トレースのサブセットを選択して分析したり、評価データセットを作成したりできます。

mlflow.search_traces() API​

Python
def mlflow.search_traces(
    experiment_ids: list[str] | None = None,
    filter_string: str | None = None,
    max_results: int | None = None,
    order_by: list[str] | None = None,
    extract_fields: list[str] | None = None,
    run_id: str | None = None,
    return_type: Literal['pandas', 'list'] | None = None,
    model_id: str | None = None,
    sql_warehouse_id: str | None = None,
    include_spans: bool = True,
    locations: list[str] | None = None,
) -> pandas.DataFrame | list[Trace]

mlflow.search_traces()使用すると、いくつかのディメンションに沿ってデータをフィルタリングおよび選択できます。

  • クエリ文字列でフィルタリングする
  • 場所によるフィルター: 体験、実行、モデル、またはUnity Catalogスキーマ
  • データの制限: 結果の最大数、範囲を含めるか除外するか
  • 戻り値の形式を調整する: データ形式、データの順序

search_traces() Pandas DataFrameまたはTraceオブジェクトのリストを返します。これをさらに分析したり、評価データセットに再構成したりできます。 これらの戻り値の型のスキーマの詳細を参照してください。

詳細については、 mlflow.search_traces() API ドキュメントを参照してください。

mlflow.search_traces()問題​

カテゴリー

parameter: type

説明

例

クエリ文字列でフィルタリング

filter_string: str

サポートされているフィルターや比較演算子を含む検索クエリ構文を参照してください。

attributes.status = 'OK' AND tags.environment = 'production'

場所でフィルタリング

locations: list[str]

この引数には、フィルタリング用のエクスペリメント ID またはUnity Catalog catalog.schemaの場所のリストを指定できます。 これを使用して、推論テーブルまたはUnity Catalogテーブルに保存されているトレースを検索します。

['591498498138889', '782498488231546'] または ['my_catalog.my_schema']

run_id: str

MLflow 実行 ID

35464a26b0144533b09d8acbb4681985

model_id: str

MLflow モデル ID

acc4c426-5dd7-4a3a-85de-da1b22ce05f1

データを制限する

max_results: int

返されるトレースの最大数（行）

100

include_spans: bool

結果にスパンを含めるか除外します。スパンはトレースの詳細を含み、結果のサイズがはるかに大きくなる可能性があります。

True

戻り値の形式

order_by: list[str]

構文とサポートされているキーを参照してください。

["timestamp_ms DESC", "status ASC"]

return_type: Literal['pandas', 'list']

この関数は、 Pandas DataFrameまたはTraceオブジェクトのリストのいずれかを返すことができます。 スキーマの詳細を参照してください。

'pandas'

非推奨

experiment_ids: list[str]

代わりにlocationsを使用してください。

extract_fields: list[str]

代わりに、返された DataFrame 内のフィールドを選択するか、オブジェクトをトレースします。

sql_warehouse_id: str

代わりにMLFLOW_TRACING_SQL_WAREHOUSE_ID環境変数を使用してください。

おすすめの方法​

キーワード引数​

mlflow.search_traces()では常にキーワード (名前付き) 引数を使用します。位置引数は許可されますが、関数引数は進化しています。

良い実践例: mlflow.search_traces(filter_string="attributes.status = 'OK'")

悪い習慣: mlflow.search_traces([], "attributes.status = 'OK'")

filter_string落とし穴​

mlflow.search_traces()のfilter_string引数を使用して検索する場合は、次の点に注意してください。

  • 接頭辞を使用する: attributes. 、 tags. 、または metadata.
  • タグ名または属性名にドットが含まれている場合はバッククォートを使用します: tags.`mlflow.traceName`
  • 一重引用符のみを使用してください: 'value'使用しないでください "value"
  • 時刻には日付ではなく Unix タイムスタンプ (ミリ秒) を使用します: 1749006880539
  • ANDのみ使用: ORはサポートされません

詳細については、検索クエリ構文を参照してください。

SQLウェアハウス統合​

mlflow.search_traces() オプションでDatabricks SQLウェアハウスを使用して、推論テーブルまたはUnity Catalogテーブルの大規模なトレース データセットのパフォーマンスを向上させることができます。 MLFLOW_TRACING_SQL_WAREHOUSE_ID環境変数を使用してSQLウェアハウス ID を指定します。

大規模なトレース データセットのパフォーマンスを向上させるために、Databricks SQL ウェアハウスを使用してトレース クエリを実行します。

Python
import os

os.environ['MLFLOW_TRACING_SQL_WAREHOUSE_ID'] = 'fa92bea7022e81fb'

# Use SQL warehouse for better performance
traces = mlflow.search_traces(
    filter_string="attributes.status = 'OK'",
    locations=['my_catalog.my_schema'],
)

ページネーション​

mlflow.search_traces() 結果をメモリ内に返すので、結果セットが小さい場合に適しています。大きな結果セットを処理するには、ページ区切りをサポートしているMlflowClient.search_traces()を使用します。

次のステップ​