Span

什么是 Span？

Span 对象是 Trace 数据模型中的基本构建块。它是 Trace 中各个步骤信息的容器，例如 LLM 调用、工具执行、检索等。Span 在单个 Trace 内形成一个分层树结构，该结构表示 Trace 的执行流程。

Example of a Span for a Tool Calling Agent

工具调用代理的 Span 示例

例如，上图说明了一组 Span，它们在 Trace 中以树状结构组织。每一行代表一个 Span，树状结构由行之间的弯曲边形成。

Span 对象架构

MLflow 的 Span 对象设计为与 OpenTelemetry Span 规范兼容。它是一个数据类对象，与 OpenTelemetry Span 对象基本相同，但具有一些额外的便捷访问器和方法来支持 GenAI 用例。当导出到与 OpenTelemetry 兼容的后端时，Span 对象会被序列化为严格的 OpenTelemetry 导出格式 (OTLP)。

字段	类型	描述
`span_id`	`str`	为 Trace 中的每个 Span 生成的唯一标识符。
`trace_id`	`str`	将此 Span 链接到其父 Trace 的唯一标识符。
`parent_id`	`Optional[str]`	用于将给定 Span 与其父 Span 建立层级关联的标识符。如果 Span 是根 Span，则此字段为 `None`。
`name`	`str`	Span 的名称，可以是用户定义的，也可以是基于被检测的函数或方法自动生成的。
`start_time_ns`	`int`	Span 开始的 Unix 时间戳（以纳秒为单位）。
`end_time_ns`	`int`	Span 结束的 Unix 时间戳（以纳秒为单位）。
`status`	`SpanStatus`	Span 的状态，值为 OK、UNSET 或 ERROR。Span 状态对象包含一个可选的描述，如果 status_code 反映了发生的错误。
`inputs`	`Optional[Any]`	传递到应用程序特定阶段的输入数据。
`输出`	`Optional[Any]`	从应用程序特定阶段传出的输出数据。
`attributes`	`Dict[str, Any]`	Attributes 是与应用程序中给定步骤相关的元数据。这些是键值对，可提供对函数和方法调用行为修改的洞察。
`events`	`List[SpanEvent]`	Events 是一个系统级属性，仅当 Span 执行过程中出现问题时才可选应用于 Span。这些事件包含有关在被检测调用中抛出的异常以及堆栈跟踪的信息。

Span Attributes

Span attributes 是键值对，可提供对函数和方法调用行为修改的洞察。

span.set_attributes(
    {
        "ai.model.name": "o3-mini",
        "ai.model.version": "2024-01-01",
        "ai.model.provider": "openai",
        "ai.model.temperature": 0.7,
        "ai.model.max_tokens": 1000,
        "infrastructure.gpu.type": "A100",
        "infrastructure.memory.used_mb": 2048,
    }
)

Span Types

Span 类型是为 Trace 中的 Span 分类的一种方式。MLflow 为常用场景提供了一组预定义的 Span 类型，同时也允许您设置自定义 Span 类型。

Built-in Types
设置 Span 类型
按类型搜索 Span

Span Type	描述
`"CHAT_MODEL"`	表示对聊天模型的查询。这是 LLM 交互的一种特殊情况。
`"CHAIN"`	表示操作链。
`"AGENT"`	表示自主代理操作。
`"TOOL"`	表示工具执行（通常由代理执行），例如查询搜索引擎。
`"EMBEDDING"`	表示文本嵌入操作。
`"RETRIEVER"`	表示上下文检索操作，例如查询向量数据库。
`"PARSER"`	表示解析操作，将文本转换为结构化格式。
`"RERANKER"`	表示重排序操作，根据相关性对检索到的上下文进行排序。
`"MEMORY"`	表示内存操作，例如将上下文持久化到长期内存数据库。
`"UNKNOWN"`	当未指定其他 Span 类型时使用的默认 Span 类型。

当您使用自动跟踪时，Span 类型将由 MLflow 自动设置。要为手动创建的 Span 设置 Span 类型，您可以将 span_type 参数传递给 mlflow.trace() 装饰器或 mlflow.start_span() 上下文管理器。当您使用自动跟踪时，Span 类型将由 MLflow 自动设置。

import mlflow
from mlflow.entities import SpanType


# Setting a span type with the decorator
@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_documents(query: str):
    ...


# Setting a span type with the context manager
with mlflow.start_span(name="add", span_type=SpanType.TOOL) as span:
    span.set_inputs({"x": x, "y": y})
    z = x + y
    span.set_outputs({"z": z})


# You can also define a custom span type string
@mlflow.trace(span_type="ROUTER")
def route_request(request):
    ...

Span 类型对于在大型 Trace 中搜索和过滤特定 Span 非常有用。MLflow 支持通过 UI 和编程方式按 Span 类型进行搜索。

通过 SDK 搜索 Span

import mlflow
from mlflow.entities import SpanType

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

在 UI 上搜索 Span

Search Spans by Type

专用 Span 架构

MLflow 具有预定义的 Span 类型，某些 Span 类型具有特定的属性，这些属性是为了在 UI 和下游任务（如评估）中启用附加功能而必需的。

Retriever Spans

RETRIEVER Span 类型用于涉及从数据存储检索数据的操作（例如，从向量存储查询文档）。RETRIEVER Span 的输出预期为文档列表。

列表中的每个文档都应为具有以下结构的字典

page_content (str): 检索到的文档块的文本内容。

metadata (Optional[Dict[str, Any]]): 与文档关联的附加元数据的字典。MLflow UI 和评估指标可能会特别查找

doc_uri (str): 文档源的字符串 URI
chunk_id (str): 如果文档是较大分块文档的一部分，则为字符串标识符

id (Optional[str]): 文档块本身的可选唯一标识符。

示例用法

import mlflow
from mlflow.entities import SpanType, Document


def search_store(query: str) -> list[tuple[str, str]]:
    # Simulate retrieving documents (e.g., 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):
    # Get documents from the search store
    docs = search_store(query)

    # Get the current active span (created by @mlflow.trace)
    span = mlflow.get_current_active_span()

    # Set the outputs of the span in accordance with the tracing schema
    outputs = [
        Document(page_content=doc, metadata={"doc_uri": uri}) for doc, uri in docs
    ]
    span.set_outputs(outputs)

    # Return the original format for downstream usage
    return docs


# Example usage
user_query = "MLflow Tracing benefits"
retrieved_docs = retrieve_relevant_documents(user_query)

什么是 Span？​

Span 对象架构​

Span Attributes​

Span Types​

专用 Span 架构​

Retriever Spans​

示例用法​