追踪概念
什么是追踪?
追踪是一种可观测性技术,它捕获请求在应用程序中的完整执行流。与捕获离散事件的传统日志记录不同,追踪创建了数据如何在系统中流动的详细地图,记录了每个操作、转换和决策点。
在 GenAI 应用程序的上下文中,追踪变得至关重要,因为这些系统涉及复杂的、多步骤的工作流,如果没有对其执行的完整可见性,则难以调试和优化。

工具调用代理的追踪示例
用例
调试
追踪提供对 GenAI 库抽象层之下发生的事情的深入洞察,帮助您精确定位问题发生的位置。
质量检查
追踪提供了一种统一的方式来跟踪输出的质量。您可以手动审查追踪中记录的输出,并向追踪附加反馈以指示输出的质量。
生产监控
追踪在每个步骤捕获关键指标,如延迟和令牌使用量,帮助您识别瓶颈、监控效率并寻找优化机会。
数据集收集
来自生产系统的追踪捕获完美数据,用于构建高质量数据集,其中包含内部组件(如检索器和工具)的精确细节。
核心结构
从高层次看,MLflow 追踪由两个主要对象组成
TraceInfo:有助于解释追踪来源、追踪状态、总执行时间等信息的元数据。这包括提供追踪额外上下文的标签,例如用户、会话和开发者提供的键值对。标签可用于搜索或筛选追踪。
TraceData:实际的有效载荷,其中包含被检测的Span对象,它们捕获应用程序从输入到输出的逐步执行过程。

MLflow 追踪旨在与 OpenTelemetry 规范兼容,OpenTelemetry 是广泛采用的可观测性行业标准。这确保了互操作性,并允许 MLflow 追踪导出并与其他 OpenTelemetry 兼容系统一起使用。MLflow 通过为生成式 AI 用例定义特定的结构和属性,增强了基本的 OpenTelemetry Span 模型,为质量和性能提供了更丰富的上下文和更深入的洞察。
TraceInfo:元数据和上下文
MLflow 追踪功能中的 TraceInfo 旨在提供关于整个追踪关键数据的轻量级快照。在 Python SDK 中,TraceInfo 被设计为一个数据类对象,包含有关追踪的元数据。
此元数据包括有关追踪来源、状态以及用于与 mlflow.search_traces()
结合使用时检索和筛选追踪以及在 MLflow UI 中导航追踪的各种其他数据。
字段 | 类型 | 描述 |
---|---|---|
trace_id | str | 追踪的主要标识符。 |
trace_location | TraceLocation | 追踪的存储位置,表示为 TraceLocation 对象。MLflow 当前支持 MLflow 实验作为追踪位置。 |
request_time | int | 追踪的开始时间,以毫秒为单位。 |
state | TraceState | 追踪的状态,表示为 TraceState 枚举。可以是 OK 、ERROR 、IN_PROGRESS 、STATE_UNSPECIFIED 之一。 |
execution_duration | int | 追踪的持续时间,以毫秒为单位。 |
request_preview | Optional[str] | 对模型/代理的请求,等同于根跨度的输入,但经过 JSON 编码并可能被截断。 |
response_preview | Optional[str] | 模型/代理的响应,等同于根跨度的输出,但经过 JSON 编码并可能被截断。 |
client_request_id | Optional[str] | 与追踪关联的客户端提供的请求 ID。这可用于从产生追踪的外部系统识别追踪/请求,例如,Web 应用程序中的会话 ID。 |
trace_metadata | dict[str, str] | 与追踪关联的键值对。它们设计用于不可变的值,例如与追踪关联的运行 ID。 |
tags | dict[str, str] | 标签是可用于标注追踪的键值对。它们设计用于可变值,可以在追踪通过 MLflow UI 或 API 创建后进行更新,并且对于分组追踪和高效查询它们非常有用。有关标签用法的更多详细信息,请访问设置追踪标签。 |
TraceData:跨度容器
MLflow TraceData 对象(可通过 trace.data
访问)是 Span 对象的容器。这里存储了实际的执行细节,包括请求和响应数据、每一步的延迟、LLM 的输入和输出消息、从向量存储中检索到的文档、工具调用参数等。
追踪中的跨度通过父子连接形成层次结构。每个跨度都详细说明了一个特定的工作单元。
例如,下图展示了一组以树状结构组织在追踪中的跨度。每行代表一个跨度,树状结构由行之间的卷曲边缘形成。例如,根跨度是“agent”,它链接到三个子跨度:2 个 LLM 调用和 1 个工具处理。

要了解有关跨度对象及其模式的更多信息,请继续访问跨度概念页面。
存储布局
TraceInfo
是一个轻量级的元数据对象,因此可以直接存储在关系数据库中。例如,如果您在 PostgreSQL 等 SQL 数据库上运行 MLflow Tracking Server,TraceInfo
作为追踪表中的一行存储,并支持使用索引进行高效查询。例如,TraceInfo
对象中包含的数据用于填充 MLflow 追踪 UI 中的追踪视图页面。
TraceData
(跨度)是相对于 TraceInfo
而言较大的对象,因为它包含有关每个执行步骤的丰富信息,例如 LLM 调用的完整消息历史输入。因此,MLflow 将它们存储在工件存储中,而不是数据库中。这允许您以更低的成本处理大量的追踪,并最大限度地减少对追踪的典型筛选和分组操作性能的影响。