Span

什么是 Span？

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

Example of a Span for a Tool Calling Agent

工具调用代理的 Span 示例

例如，上图展示了一组在追踪中以树状结构组织的 Span。每行代表一个 Span，其中树状结构由行之间的弯曲边缘形成。

Span 对象 Schema

MLflow 的 Span 对象旨在与 OpenTelemetry Span 规范兼容。它是一个 dataclass 对象，与 OpenTelemetry span 对象基本相同，但提供了一些额外的便捷访问器和方法，以支持 GenAI 用例。当导出到与 OpenTelemetry 兼容的后端时，Span 对象会被序列化为严格的 OpenTelemetry 导出格式 (OTLP)。

字段	类型	描述
`span_id`	`str`	在追踪中为每个 Span 生成的唯一标识符。
`trace_id`	`str`	将此 Span 链接到其父追踪的唯一标识符。
`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。如果 status_code 反映了发生的错误，则 span 状态对象包含一个可选的描述。
`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 类型

Span 类型是在追踪中对 Span 进行分类的一种方式。MLflow 提供了一组用于常见用例的预定义 Span 类型，同时允许您设置自定义 Span 类型。

内置类型
设置 Span 类型
按类型搜索 Span

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

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

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 类型对于在大型追踪中搜索和过滤特定 Span 非常有用。MLflow 支持通过 Span 类型进行 UI 搜索和编程搜索。

通过 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 Schema

MLflow 具有预定义的 Span 类型，某些 Span 类型具有启用 UI 中附加功能以及评估等下游任务所需的属性。

Retriever Span

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 对象 Schema​

Span Attributes​

Span 类型​

专用 Span Schema​

Retriever Span​

示例用法​