Span

什么是 Span？

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

Example of a Span for a Tool Calling Agent

工具调用代理的 Span 示例

例如，上图说明了一组在 trace 中以树状结构组织的 spans。每一行代表一个 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 的名称，可以是用户定义的，也可以是根据正在 instrumented 的函数或方法自动生成的。
`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。这些事件包含有关 instrumented 调用中抛出的异常以及堆栈跟踪的信息。

Span Attributes

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

python
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
Setting Span Types
按类型搜索 Spans

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

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

python
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 类型进行 span 搜索。

通过 SDK 搜索 spans

python
import mlflow
from mlflow.entities import SpanType

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

在 UI 上搜索 spans

Search Spans by Type

专用 Span Schemas

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])：文档块本身的可选唯一标识符。

示例用法

python
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 Schemas​

Retriever Spans​

示例用法​