以编程方式搜索痕迹

使用 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 文档。

注释

Databricks 托管的 MLflow 和开源软件 MLflow 共享大多数搜索查询语法，但存在一些字段级差异。 有关详细信息 ，请参阅 OSS MLflow 之间的差异 。

mlflow.search_traces() 参数

类别 parameter: type Description Example
按查询字符串进行筛选 filter_string: str 有关支持的筛选器和比较器，请参阅 搜索查询语法 。 trace.status = 'OK' AND tag.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 环境变量 。

搜索查询语法

该 filter_string 参数使用类似于 SQL 的查询语言来筛选跟踪。 字符串值必须用单引号（例如）trace.status = 'OK'包装，数值不得用引号括起来（例如）。 trace.execution_time_ms > 1000 将条件组合与 AND。 运算符OR不受支持。

支持的筛选器和比较器

Databricks 管理的 MLflow 支持以下字段和比较器。

注释

仅支持标记为(UC only)的筛选器用于存储在 Unity 目录中的 MLflow 跟踪。

字段类型 Fields 比较器 Example
跟踪状态 trace.status =、!= trace.status = 'OK'
跟踪时间戳 trace.timestamp_ms trace.execution_time_ms 、trace.end_time_ms（仅限 UC） =、!=、>、<、>=、<= trace.end_time_ms > 1762408895531
跟踪 ID trace.run_id = trace.run_id = 'run_id'
字符串字段 trace.client_request_id （仅限 UC）， trace.name =、!=、LIKE、ILIKE、RLIKE trace.name LIKE '%Generate%'
请求和响应内容 （仅限 UC） trace.request、trace.response =、!=、LIKE、ILIKE、RLIKE trace.request LIKE '%weather%'
令牌计数 （仅限 UC） trace.token_count =、!=、>、<、>=、<= trace.token_count > 1000
关联提示 prompt = （格式： 'name/version'） prompt = 'qa-system-prompt/4'
范围名称、类型和状态 （仅限 UC） span.name、span.type、span.status =、!=、LIKE、ILIKE、RLIKE span.type RLIKE '^LLM'
OTel span 属性 （仅限 UC） span.attributes.<key> =、!=、LIKE、ILIKE、RLIKE、IS NULL、IS NOT NULL span.attributes.gen_ai.request.model = 'gpt-4'
Tags tag.<key> =、!=、LIKE、ILIKE、RLIKE、IS NULL、IS NOT NULL
对于存储在试验中的 MLflow 跟踪（不在 Unity 目录中），仅支持 = 和 !=。		 tag.environment = 'production'
Metadata metadata.<key> =、!=、LIKE、ILIKE、RLIKE、IS NULL、IS NOT NULL
对于存储在试验中的 MLflow 跟踪（不在 Unity 目录中），仅支持 = 和 !=。		 metadata.`mlflow.trace.user` = 'user_123'
反馈 （仅限 UC） feedback.<name> =、!=、LIKE、ILIKE、RLIKE feedback.rating = 'excellent'
期望 （仅限 UC） expectation.<name> =、!=、LIKE、ILIKE、RLIKE expectation.result = 'pass'

与 OSS MLflow 的差异

Databricks 托管 MLflow 上的搜索查询语法密切跟踪 OSS MLflow，但存在以下差异：

领域 Databricks 托管的 MLflow OSS MLflow 备注
trace.request、trace.response 支持（UC 专用） 不支持 使用这些字段筛选序列化的请求和响应内容。
trace.token_count 支持（UC 专用） 不支持 按令牌总数筛选跟踪。
span.attributes.<key> 支持（UC 专用） 不支持 按 OpenTelemetry 范围属性筛选跟踪。
trace.text 不支持 支持 （仅限 SQLAlchemy 存储） OSS 将 trace.text 公开用于跨跟踪内容的全文搜索。 在 Databricks 上，改用 trace.request 和 trace.response 筛选跟踪内容。
trace.prompt 不支持 支持（映射到链接提示标记） 在 Databricks 上，使用顶级 prompt 字段。
trace.request_id 不支持 Supported 在 Databricks 上，请改用 trace.client_request_id 。
issue.id 不支持 Supported 筛选与特定问题 ID 相关的跟踪记录。

搜索第三方 OpenTelemetry 范围

若要搜索从第三方 OpenTelemetry 工具（如 Langfuse）引入的跟踪，请改用 span.attributes.* 前缀。 请参阅按 OTel span 属性搜索追踪。

最佳做法

关键字参数

始终使用关键字（命名）参数与 mlflow.search_traces()。 它允许位置参数，但函数参数正在演变。

最佳做法： mlflow.search_traces(filter_string="trace.status = 'OK'")

不良做法： mlflow.search_traces([], "trace.status = 'OK'")

filter_string 陷阱

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

  • 使用前缀：trace.、或 tag.metadata.
  • 如果标记或属性名称中有点，请使用反引号：tag.`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="trace.status = 'OK'",
    locations=['my_catalog.my_schema'],
)

分页

mlflow.search_traces() 返回内存中的结果，这适用于较小的结果集。 若要处理大型结果集，请使用 MlflowClient.search_traces() ，因为它支持分页。

后续步骤

  • Last updated on