Conceitos de extensão

O objeto Span é um componente fundamental no modelo de dados Trace. Cada intervalo captura uma única etapa em um rastreamento, por exemplo, uma chamada LLM , a execução de uma ferramenta ou uma operação de recuperação.

Os intervalos (spans) são organizados hierarquicamente em um rastreamento para representar o fluxo de execução do seu aplicativo. Cada intervalo captura:

Dados de entrada e saída
Informação de horários (horários de início e término)
Status (sucesso ou erro)
Metadados e atributos sobre as operações
Relação com outros âmbitos (conexões entre pais e filhos)

Arquitetura de vãos

Esquema de objeto Span

O esquema Span do MLflow é compatível com a especificação OpenTelemetry. O esquema possui 11 propriedades principais:

Propriedade	Tipo	Descrição
`span_id`	`str`	Identificador único para este trecho no rastreamento.
`trace_id`	`str`	Os links se estendem até seu rastreamento pai.
`parent_id`	`Optional[str]`	Estabelece a relação entre pais e filhos. Defina como `None` para os intervalos raiz.
`name`	`str`	Nome do intervalo definido pelo usuário ou gerado automaticamente
`start_time_ns`	`int`	Timestamp Unix (nanossegundos) de quando o intervalo começa
`end_time_ns`	`int`	Timestamp Unix (em nanossegundos) do término do intervalo.
`status`	`SpanStatus`	Estado do trecho: `OK`, `UNSET` ou `ERROR` com descrição opcional
`inputs`	`Optional[Any]`	Dados de entrada entrando nestas operações
`outputs`	`Optional[Any]`	Dados de saída desta operação
`attributes`	`Dict[str, Any]`	Metadados por valor- keyfornecendo percepções comportamentais
`events`	`List[SpanEvent]`	Exceções no nível do sistema e informações de rastreamento de pilha

Para mais informações, consulte a referência API MLflow.

Atributos de extensão

Os atributos são pares de pares key-valor que fornecem informações sobre modificações comportamentais para chamadas de funções e métodos. Eles capturam metadados sobre a configuração e o contexto de execução das operações.

Você pode adicionar atributos específicos da plataforma para enriquecer a observabilidade. Por exemplo, você pode adicionar os objetosUnity Catalog que o span tocou, o endpointdo modelo de servir ou o recursocompute.

Por exemplo, defina atributos em um span que envolve uma chamada LLM:

Python
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,
})

Tipos de extensão

MLflow fornece valores predefinidos SpanType para operações comuns. Para casos específicos, passe um valor de string personalizado como tipo de intervalo.

Tipo	Descrição
`CHAT_MODEL`	Consulta a um modelo de chat (interação especializada em LLM)
`CHAIN`	Cadeia de operações
`AGENT`	operações de agentes autônomos
`TOOL`	Execução de ferramentas (normalmente por agentes), como consultas de pesquisa
`EMBEDDING`	operações de incorporação de texto
`RETRIEVER`	Operações de recuperação de contexto, como consultas de banco de dados vetoriais
`PARSER`	Operações de análise sintática transformam texto em formato estruturado.
`RERANKER`	Reclassificação dos contextos de ordenação de operações por relevância.
`MEMORY`	Operações de memória que persistem no contexto em armazenamento de longo prazo
`UNKNOWN`	Tipo padrão usado quando nenhum outro tipo é especificado.

Definindo tipos de intervalo

Para definir o SpanType para um span, passe span_type para o decorador ou gerenciador de contexto:

Python
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})

Pesquisando intervalos por tipo

Consultar intervalos programaticamente usando MLflow search_spans():

Python
import mlflow
from mlflow.entities import SpanType

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

Você também pode filtrar por tipo de intervalo na interface do usuário do MLflow ao visualizar os rastreamentos.

Períodos ativos vs. períodos concluídos

Um span ativo, representado por LiveSpan, é aquele que o MLflow está escrevendo no momento. Os spans ativos são produzidos por uma função decorada com @mlflow.trace ou por um gerenciador de contexto de span. Após a função decorada sair ou o gerenciador de contexto fechar, o span é finalizado e se torna um imutável Span.

Para modificar o intervalo ativo, recupere-o com mlflow.get_current_active_span().

`RETRIEVER` esquema de extensão

O tipo de span RETRIEVER representa operações que buscam dados de um armazenamento de dados, por exemplo, consultar documentos de um armazenamento vetorial. Os spans do RETRIEVER usam um esquema de saída fixo, o que desbloqueia uma renderização de interface do usuário mais rica e recursos de avaliação no MLflow. A saída deve ser uma lista de documentos, onde cada documento é um dicionário com:

page_content (str): Conteúdo textual do bloco de documento recuperado
metadata (Optional[Dict[str, Any]]): Metadados adicionais, incluindo:
- doc_uri (str): O URI de origem do documento. Ao usar a Pesquisa Vetorial no Databricks, você pode registrar caminhos de volume Unity Catalog em doc_uri para acompanhamento completo da linhagem.
- chunk_id (str): Identificador se o documento faz parte de um documento maior dividido em partes.
id (Optional[str]): Identificador único para o bloco de documento.

Use a entidade MLflowDocument para construir esta estrutura de saída.

Exemplo de implementação :

Python
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)

Próximos passos

Conceitos de traços — Compreender os conceitos e a estrutura ao nível dos traços.
Comece agora: MLflow Tracing para GenAI ( Notebook Databricks ) — Obtenha experiência prática com rastreamento em um Notebook.

Esquema de objeto Span​

Atributos de extensão​

Tipos de extensão​

Definindo tipos de intervalo​

Pesquisando intervalos por tipo​

Períodos ativos vs. períodos concluídos​

RETRIEVER esquema de extensão​

Próximos passos​