Compartir a través de

以编程方式搜索痕迹

使用 mlflow.search_traces() 以编程方式搜索和分析追踪。 此函数可以查询存储在 MLflow 跟踪服务器、推理表或 Unity 目录表中的跟踪。 可以选择用于分析或创建评估数据集的跟踪子集。

mlflow.search_traces() API（应用程序接口）

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 目录架构
  • 限制数据：最大结果、包括或排除区间
  • 调整返回值格式：数据格式、数据顺序

search_traces() 返回 pandas 数据帧或对象列表 Trace ，然后可以进一步分析这些对象或重新调整为评估数据集。 请参阅这些返回类型的 架构详细信息 。

有关完整详细信息，mlflow.search_traces()请参阅 API 文档。

mlflow.search_traces() 参数

类别 parameter: type Description Example
按查询字符串进行筛选 filter_string: str 请参阅 搜索查询语法 ，包括支持的筛选器和比较器。 attributes.status = 'OK' AND tags.environment = 'production'
按位置筛选 locations: list[str] 此参数可以是用于筛选的试验 ID 或 Unity 目录 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 陷阱

使用 filter_string 参数进行 mlflow.search_traces() 搜索时，请记住以下几点：

  • 使用前缀：attributes.、或 tags.metadata.
  • 如果标记或属性名称中有点，请使用反引号：tags.`mlflow.traceName`
  • 仅使用单引号：'value'，而不是"value"
  • 使用 Unix 时间戳（以毫秒为单位）来表示时间，1749006880539 而非日期。
  • 仅使用 AND：无 OR 支持

有关更多详细信息，请参阅 搜索查询语法 。

SQL 仓库集成

mlflow.search_traces() 可以选择使用 Databricks SQL 仓库 来提高推理表或 Unity 目录表中大型跟踪数据集的性能。 使用 MLFLOW_TRACING_SQL_WAREHOUSE_ID 环境变量指定 SQL 仓库 ID。

使用 Databricks SQL 仓库执行跟踪查询，以提高大型跟踪数据集的性能：

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() ，因为它支持分页。

后续步骤

  • Last updated on