追踪概念

什么是追踪？

追踪是一种可观测性技术，用于捕获请求在您的应用程序中的完整执行流程。与捕获离散事件的传统日志记录不同，追踪创建了一个详细的映射，展示数据如何在您的系统中流动，记录了每一个操作、转换和决策点。

在 GenAI 应用程序的背景下，追踪变得至关重要，因为这些系统涉及复杂的多步骤工作流，如果没有对其执行的完全可见性，将很难进行调试和优化。

工具调用代理的追踪示例

用例

调试

追踪提供了对 GenAI 库抽象层之下发生的事情的深入洞察，帮助您精确识别问题发生的位置。

质量检查

追踪提供了一种统一的方式来跟踪输出的质量。您可以手动审查追踪中记录的输出，并为您的追踪附加反馈以表明输出的质量。

生产监控

追踪捕获了每个步骤的关键指标，如延迟和令牌使用量，帮助您识别瓶颈、监控效率并寻找优化机会。

数据集收集

来自生产系统的追踪捕获了完美的数据，用于构建高质量的数据集，其中包含诸如检索器和工具等内部组件的精确细节。

核心结构

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

TraceInfo：元数据，有助于解释追踪的来源、追踪的状态、关于总执行时间的信息等。这包括为追踪提供额外上下文的标签，例如用户、会话和开发者提供的键值对。标签可用于搜索或筛选追踪。

TraceData：实际的有效载荷，其中包含被检测的 Span 对象，这些对象捕获了您应用程序从输入到输出的逐步执行过程。

MLflow 追踪架构概览

MLflow 追踪被设计为与 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：跨度（Span）的容器

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

追踪中的跨度通过父子连接形成一个层级结构。每个跨度都详细描述了一个特定的工作单元。

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

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

存储布局

TraceInfo 是一个轻量级的元数据对象，因此可以直接存储在关系数据库中。例如，如果您在 SQL 数据库（如 PostgreSQL）上运行 MLflow 跟踪服务器，TraceInfo 会在追踪表中存储为单行，并支持使用索引进行高效查询。例如，TraceInfo 对象中包含的数据用于填充 MLflow 跟踪 UI 中的追踪视图页面。

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