范围概念

Span 对象是跟踪数据模型中的基本构建基块。 每个范围捕获跟踪中的单个步骤，例如 LLM 调用、工具执行或检索操作。

跨度在跟踪中分层组织，以表示应用程序的执行流。 每个区段捕捉：

  • 输入和输出数据
  • 计时信息（开始和结束时间）
  • 状态（成功或错误）
  • 有关操作的元数据和属性
  • 与其他跨度的关系（父子连接）

Span 体系结构

Span 对象架构

MLflow Span 架构与 OpenTelemetry 规范兼容。 架构有 11 个核心属性：

资产 类型 Description
span_id str 追踪中此区段的唯一标识符
trace_id str 链接跨度到其父追踪
parent_id Optional[str] 建立父子关系。 对于根跨度，设置为 None。
name str 用户定义的或自动生成的跨度名称
start_time_ns int 跨度开始时的 Unix 时间戳（纳秒）
end_time_ns int 跨度结束时的 Unix 时间戳（纳秒）
status SpanStatus 跨度状态： OK、 UNSET或 ERROR 具有可选说明
inputs Optional[Any] 输入此操作的数据
outputs Optional[Any] 输出从该操作生成的数据
attributes Dict[str, Any] 提供行为见解的元数据键值对
events List[SpanEvent] 系统级异常和堆栈跟踪信息

有关详细信息，请参阅 MLflow API 参考。

Span 属性

属性是键值对，用于深入了解函数和方法调用的行为修改。 它们捕获有关操作配置和执行上下文的元数据。

可以添加特定于平台的属性来丰富可观测性。 例如，您可以添加该跨度涉及到的 Unity Catalog 对象 或 计算资源。

例如，在包裹 LLM 调用的 span 上设置属性：

span.set_attributes({
    "ai.model.name": "claude-3-5-sonnet-20250122",
    "ai.model.version": "2025-01-22",
    "ai.model.provider": "anthropic",
    "ai.model.temperature": 0.7,
    "ai.model.max_tokens": 1000,
})

范围类型

MLflow 为常见操作提供预定义 SpanType 值。 对于特殊情况，请将自定义字符串值作为范围类型传递。

类型 Description
CHAT_MODEL 查询聊天模型（专用 LLM 交互）
CHAIN 操作链
AGENT 自主代理操作
TOOL 工具执行（通常由代理执行），例如搜索查询
EMBEDDING 文本嵌入操作
RETRIEVER 上下文检索操作，例如矢量数据库查询
PARSER 解析操作将文本转换为结构化格式
RERANKER 按相关性对上下文重新排序
MEMORY 将内存操作的上下文持久化到长期存储中
UNKNOWN 未指定其他类型时使用的默认类型

设置跨度类型

若要为 span 设置 SpanType，请将 span_type 传递给修饰器或上下文管理器：

import mlflow
from mlflow.entities import SpanType

# Using a built-in span type
@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_documents(query: str):
    ...

# Using a custom span type
@mlflow.trace(span_type="ROUTER")
def route_request(request):
    ...

# With context manager
with mlflow.start_span(name="process", span_type=SpanType.TOOL) as span:
    span.set_inputs({"data": data})
    result = process_data(data)
    span.set_outputs({"result": result})

按类型搜索范围

使用 MLflow search_spans()以编程方式进行查询：

import mlflow
from mlflow.entities import SpanType

trace = mlflow.get_trace("<trace_id>")
retriever_spans = trace.search_spans(span_type=SpanType.RETRIEVER)

还可以在查看跟踪时按 MLflow UI 中的范围类型进行筛选。

活动中与已完成的时间段

活动 Span（由 LiveSpan 表示）是 MLflow 当前正在写入的 Span。 活动跨度由带有 @mlflow.trace 装饰器的函数或由 跨度上下文管理器 创建。 修饰函数退出或上下文管理器关闭后，范围将完成并变为不可变 Span。

若要修改活动范围，请使用 mlflow.get_current_active_span().

RETRIEVER span 架构

RETRIEVER 跨度类型表示从数据存储中获取数据的操作，例如从向量存储中查询文档。 RETRIEVER 范围使用固定的输出架构，该架构可解锁 MLflow 中更丰富的 UI 呈现和评估功能。 输出必须是文档列表，其中每个文档都是一个字典，其中包含：

  • page_content （str）：检索到的文档区块的文本内容

  • metadata （Optional[Dict[str, Any]]）：其他元数据，包括：

    • doc_uri （str）：文档源 URI。
    • chunk_id（str）：如果该文档是更大的分块文档的一部分，则为其标识符。

  • id （Optional[str]）：文档区块的唯一标识符。

使用 MLflow Document 实体 构造此输出结构。

示例实现：

import mlflow
from mlflow.entities import SpanType, Document

def search_store(query: str) -> list[tuple[str, str]]:
    # Simulate retrieving documents (content, doc_uri pairs) from a vector database.
    return [
        ("MLflow Tracing helps debug GenAI applications...", "docs/mlflow/tracing_intro.md"),
        ("Key components of a trace include spans...", "docs/mlflow/tracing_datamodel.md"),
        ("MLflow provides automatic instrumentation...", "docs/mlflow/auto_trace.md"),
    ]

@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_relevant_documents(query: str):
    docs = search_store(query)
    span = mlflow.get_current_active_span()

    # Set outputs in the expected format
    outputs = [
        Document(page_content=doc, metadata={"doc_uri": uri})
        for doc, uri in docs
    ]
    span.set_outputs(outputs)

    # Return the raw tuples for the caller; the trace records the structured Document objects.
    return docs

# Usage
user_query = "MLflow Tracing benefits"
retrieved_docs = retrieve_relevant_documents(user_query)

后续步骤

  • Last updated on