向跟踪添加上下文

通过向跟踪添加上下文，可以跟踪执行详细信息、分析用户行为、跨环境调试问题以及监视应用程序性能。 MLflow 为常见上下文类型提供标准化的元数据字段，以及添加特定于应用程序的自定义元数据的灵活性。

要求

根据环境安装用于跟踪的相应包：

生产

对于生产部署，请安装 mlflow-tracing 包：

pip install --upgrade mlflow-tracing

该 mlflow-tracing 包针对生产用途进行优化，具有最少的依赖项和更好的性能特征。

开发

对于开发环境，请使用 Databricks 附加组件安装完整的 MLflow 包：

pip install --upgrade "mlflow[databricks]>=3.1"

完整 mlflow[databricks] 包包括 Databricks 本地开发和试验所需的所有功能。

注释

上下文跟踪需要 MLflow 3。由于性能限制和缺少生产用途所必需的功能，不支持 MLflow 2.x。

Implementation

若要向跟踪添加元数据和标记，请执行以下操作：

跟踪应用程序。通常，你会使用 @mlflow.trace 修饰器自动追踪函数。
在应用程序执行过程中，通过调用 mlflow.update_current_trace() 将上下文添加到使用 tags 或 metadata 的跟踪中。应用程序完成并记录跟踪后， tags 可变，但在 metadata 记录的跟踪中是不可变的。
```
import mlflow
mlflow.update_current_trace(
    metadata={
        "mlflow.trace.user": user_id,
        "mlflow.trace.session": session_id,
    },
    tags={
        "query_category": "chat",  # Example of a custom tag
    },
)
```

若要访问跟踪日志中的元数据和标记，可以使用由metadata返回的pandas DataFrame中的字段tags和mlflow.search_traces()，或者使用Trace.info.trace_metadata对象中的字段Trace.info.tags和Trace。

有关完整教程，请参阅教程：跟踪和分析用户和环境。

上下文元数据的类型

生产应用程序需要同时跟踪多个上下文片段。 MLflow 已标准化元数据字段来捕获重要的上下文信息：

上下文类型	用例	MLflow 字段
客户端请求 ID	将跟踪链接到用于端到端调试的特定客户端请求或 API 调用	`TraceInfo` 参数 `client_request_id`
用户会话 ID	从多轮次对话对跟踪进行分组，使你能够分析完整的聊天流	`mlflow.trace.session` 元数据
用户 ID	将跟踪与特定用户相关联，以便进行个性化、队列分析和用户特定的调试	`mlflow.trace.user` 元数据
环境数据	跟踪部署上下文（环境、版本、区域），以便跨不同部署进行作见解和调试	自动元数据和自定义元数据
自定义元数据	为了组织、搜索和筛选跟踪，添加特定于应用程序的元数据。	（元数据密钥）

跟踪用户和会话

跟踪 GenAI 应用程序中的用户和会话提供了了解用户行为、分析聊天流和改进个性化的基本上下文。

为什么跟踪用户和会话？

用户和会话跟踪可实现强大的分析和改进：

用户行为分析 - 了解不同用户与应用程序交互的方式
对话流程跟踪 - 分析多回合对话和上下文保留
个性化见解 - 确定用于改进用户特定体验的模式
每个用户的质量 - 跟踪不同用户细分的性能指标
会话连续性 - 在多项交互中维持上下文

用户和会话的标准元数据字段

MLflow 为会话和用户跟踪提供两个标准元数据字段：

mlflow.trace.user - 将跟踪与特定用户相关联
mlflow.trace.session - 对属于多回合对话的跟踪进行分组

使用这些标准元数据字段时，MLflow 会自动在 UI 中启用筛选和分组。与标记不同，在记录跟踪后，元数据无法更新，因此非常适合不可变标识符（如用户和会话 ID）。

跟踪环境和版本

通过跟踪 GenAI 应用程序的执行环境和应用程序版本，可以针对代码相关的性能和质量问题进行调试。此元数据允许：

在、development和staging之间进行production
跨应用版本的性能/质量跟踪和回归检测
问题发生时更快地进行根本原因分析

对于部署元数据（如环境和版本），应用程序通常应从环境变量中提取元数据，而不是将元数据硬编码到应用程序中。环境变量简化了部署过程。例如：

import mlflow
import os

# In your application logic
mlflow.update_current_trace(
    metadata={
        "mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"),  # Override default
    }
)

注释

有关版本控制工作原理的全面概述，请参阅版本跟踪。

自动填充的元数据

MLflow 根据执行环境自动设置某些标准元数据字段。

可以通过 mlflow.update_current_trace() 覆盖任何自动填充的元数据字段。当自动检测不满足要求时，这非常有用。例如，使用 mlflow.update_current_trace(metadata={"mlflow.source.name": "custom_name"}) 重写执行环境值。

类别	元数据字段	Description	自动设置逻辑
执行环境	`mlflow.source.name`	生成跟踪的入口点或脚本。	自动使用 Python 脚本的文件名和 Databricks/Jupyter 笔记本的名称进行填充。
	`mlflow.source.git.commit`	Git 提交哈希。	如果从 Git 存储库运行，则会自动检测并填充提交哈希。
	`mlflow.source.git.branch`	Git 分支。	如果从 Git 存储库运行，则会自动检测和填充当前分支名称。
	`mlflow.source.git.repoURL`	Git 存储库 URL。	如果从 Git 存储库运行，则会自动检测并填充存储库 URL。
	`mlflow.source.type`	捕获执行环境。	在 Jupyter 或 Databricks 笔记本中运行时，自动设置为 `NOTEBOOK`；在本地 Python 脚本中运行时，为 `LOCAL`；否则为 `UNKNOWN`（自动检测到）。在已部署的应用中，我们建议根据环境（例如，`PRODUCTIONSTAGING`等）更新此变量。
	`mlflow.sourceRun`	生成跟踪的源运行的运行 ID。	自动设置为生成跟踪的源运行的运行 ID。
应用程序版本	`metadata.mlflow.modelId`	MLflow LoggedModel 的 ID。	自动设置为环境变量 `MLFLOW_ACTIVE_MODEL_ID` 中的模型 ID 值或通过 `mlflow.set_active_model()` 函数设置的模型 ID 值。

添加自定义元数据

使用自定义 metadata 键捕获任何其他特定于应用程序的上下文。例如，你可能想要附加如下信息：

应用程序版本
部署识别号
部署区域
功能标志

最佳做法

一致的 ID 格式 - 在应用程序中对用户和会话 ID 使用标准化格式
会话边界 - 定义会话开始和结束时间的明确规则
环境变量 - 从环境变量填充元数据，而不是硬编码值
组合上下文类型 - 将用户、会话和环境上下文结合在一起，以实现完整的可跟踪性
常规分析 - 设置仪表板以监视用户行为、会话模式和版本性能
谨慎地覆盖默认设置 - 只有在必要时才修改自动填充的元数据

后续步骤

教程：跟踪和分析用户和环境 - 请参阅将用户、会话、环境和应用版本元数据添加到跟踪的完整示例。
以编程方式搜索日志 - 了解有关使用 mlflow.search_traces() 的详细信息。
分析跟踪 - 请参阅跟踪分析的示例。

Last updated on 2025-12-31

通过