Trace Concepts

什么是追踪？

追踪是一种可观测性技术，它捕获请求在应用程序中的完整执行流程。与捕获离散事件的传统日志记录不同，追踪会创建一份详细的系统数据流转图，记录每一次操作、转换和决策点。

在 GenAI 应用的上下文中，追踪变得至关重要，因为这些系统涉及复杂的、多步骤的工作流，如果没有对其执行情况的完整可见性，将难以调试和优化。

工具调用 Agent 的追踪示例

用例

调试

追踪能够深入了解 GenAI 库抽象层之下的情况，帮助您精确地定位问题发生的位置。

质量检查

Trace 可以提供一种统一的方式来跟踪输出的质量。您可以手动审查记录在 Trace 上的输出，并为 Trace 附加反馈，以指示输出的质量。

生产监控

Trace 在每一步都会捕获延迟和 token 使用量等关键指标，帮助您识别瓶颈、监控效率并发现优化机会。

数据集收集

生产系统中的 Trace 可以捕获完美的数据，用于构建高质量的数据集，并为检索器和工具等内部组件提供精确的详细信息。

核心结构

从高层次来看，MLflow 的 Trace 由两个主要对象组成

TraceInfo：元数据，有助于解释 Trace 的来源、Trace 的状态、总执行时间信息等。这包括提供 Trace 额外上下文的标签，例如用户、会话以及开发人员提供的键:value对。标签可用于搜索或过滤 Trace。

TraceData：实际的负载，其中包含仪器化的 Span 对象，这些对象捕获应用程序从输入到输出的逐步执行情况。

MLflow Trace 架构概览

MLflow Trace 设计为与 **OpenTelemetry** 规范兼容，OpenTelemetry 是一个广泛采用的可观测性行业标准。这确保了互操作性，并允许 MLflow Trace 被导出并与其他 OpenTelemetry 兼容系统一起使用。MLflow 通过定义针对 Generative AI 用例的特定结构和属性来增强基本的 OpenTelemetry Span 模型，从而提供更丰富的上下文以及对质量和性能更深入的洞察。

TraceInfo：元数据和上下文

MLflow 追踪功能中的 TraceInfo 旨在提供关于整个 Trace 的关键数据的轻量级快照。在 Python SDK 中，TraceInfo 被设计为一个数据类对象，其中包含 Trace 的元数据。

这些元数据包括有关 Trace 的来源、状态以及用于在使用 mlflow.search_traces() 进行检索和过滤 Trace 的信息，以及在 MLflow UI 中导航 Trace 的信息。

字段	类型	描述
trace_id	str	Trace 的主标识符。
trace_location	TraceLocation	Trace 存储的位置，表示为 TraceLocation 对象。MLflow 目前支持 MLflow Experiment 作为 Trace 位置。
request_time	int	Trace 的开始时间，以毫秒为单位。
state	TraceState	Trace 的状态，表示为 TraceState 枚举。可以是 OK、ERROR、IN_PROGRESS、STATE_UNSPECIFIED 之一。
execution_duration	int	Trace 的持续时间，以毫秒为单位。
request_preview	Optional[str]	发送到模型/Agent 的请求，相当于根 Span 的输入，但经过 JSON 编码，并且可能会被截断。
response_preview	Optional[str]	从模型/Agent 返回的响应，相当于根 Span 的输出，但经过 JSON 编码，并且可能会被截断。
client_request_id	Optional[str]	客户端提供的与 Trace 关联的请求 ID。这可用于识别生成 Trace 的外部系统中的 Trace/请求，例如 Web 应用程序中的会话 ID。
trace_metadata	dict[str, str]	与 Trace 关联的键值对。它们旨在用于不可变值，例如与 Trace 关联的 run ID。
tags	dict[str, str]	标签是用于注释 Trace 的键值对。它们旨在用于可变值，可以通过 MLflow UI 或 API 在 Trace 创建后进行更新，并有助于对 Trace 进行分组和高效查询。有关标签用法的更多详细信息，请访问 设置 Trace 标签。

TraceData：Span 的容器

可以通过 trace.data 访问的 MLflow TraceData 对象是 Span 对象的容器。这就是存储实际执行详细信息的地方，包括请求和响应数据、每个步骤的延迟、到 LLM 的输入和输出消息、从向量存储中检索的文档、工具调用参数等。

Trace 中的 Span 通过父子关系形成一个层级结构。每个 Span 详细记录一个特定的工作单元。

例如，下图说明了一组在 Trace 中以树状结构组织的 Span。每条线代表一个 Span，树状结构由线之间的花括号连接形成。例如，根 Span 是“agent”，它链接到三个子 Span：2 个 LLM 调用和 1 个工具处理。

要了解有关 Span 对象及其模式的更多信息，请继续阅读 Span Concepts 页面。

存储布局

TraceInfo 是一个轻量级的元数据对象，因此可以直接存储在关系数据库中。例如，如果您在 PostgreSQL 等 SQL 数据库上运行 MLflow Tracking Server，TraceInfo 将作为 trace 表中的一行存储，并通过索引支持高效查询。例如，TraceInfo 对象中包含的数据用于填充 MLflow Tracking UI 中的 trace 视图页面。

与 TraceInfo 相比，TraceData (Span) 是相对较大的对象，因为它包含关于每个执行步骤的丰富信息，例如 LLM 调用完整的消息历史记录。因此，MLflow 将它们存储在 artifact 存储中，而不是数据库中。这使您能够以更低的成本处理大量 Trace，并最大限度地减少对 Trace 的典型过滤和分组操作性能的影响。