Conceitos de alcance

O objeto Span é um bloco fundamental no modelo de dados Trace. Serve como um contentor para informações sobre etapas individuais de um rastreamento, como chamadas de LLM, execução de ferramentas, operações de recuperação, entre outros.

Os spans estão organizados hierarquicamente num traço para representar o fluxo de execução da sua aplicação. Cada intervalo captura:

• Dados de entrada e saída
• Informação de horários (horas de início e fim)
• Estado (sucesso ou erro)
• Metadados e atributos sobre a operação
• Relação com outros períodos (ligações entre pais e filhos)

Esquema de objetos Span

O design Span do MLflow mantém a compatibilidade com as especificações do OpenTelemetry. O esquema inclui onze propriedades principais:

Propriedade	Tipo	Description
span_id	str	Identificador único para este intervalo no trilho
trace_id	str	As ligações abrangem até ao seu rastreio pai
parent_id	Optional[str]	Estabelece uma relação hierárquica; None para vãos radiculares
name	str	Nome do span definido pelo utilizador ou gerado automaticamente
start_time_ns	int	Carimbo temporal Unix (nanossegundos) em que o span começou
end_time_ns	int	Carimbo temporal Unix (nanossegundos) quando o span terminava
status	SpanStatus	Estado da faixa: OK, UNSET, ou ERROR com descrição opcional
inputs	Optional[Any]	Dados de entrada que entram nesta operação
outputs	Optional[Any]	Dados de saída ao sair desta operação
attributes	Dict[str, Any]	Pares de metadados-chave-valor que fornecem insights comportamentais
events	List[SpanEvent]	Exceções ao nível do sistema e informação de rastreio de pilha

Para detalhes completos, consulte a referência da API do MLflow.

Atributos de amplitude

Os atributos são pares-chave-valor que fornecem informações sobre modificações comportamentais para chamadas de funções e métodos. Capturam metadados sobre o contexto de configuração e execução da operação.

Pode adicionar atributos específicos da plataforma, como informação do Unity Catalog, detalhes de endpoints que servem modelos e metadados de infraestrutura para melhorar a observabilidade.

Exemplo de set_attributes() para uma chamada LLM

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 intervalo

O MLflow fornece valores pré-definidos SpanType para categorização. Também podes usar valores de string personalizados para operações especializadas.

Tipo	Description
CHAT_MODEL	Consulta para um modelo de chat (interação especializada em LLM)
CHAIN	Cadeia de operações
AGENT	Operação por agente autónomo
TOOL	Execução de ferramentas (tipicamente por agentes), como consultas de pesquisa
EMBEDDING	Operação de incorporação de texto
RETRIEVER	Operação de recuperação de contexto, como consultas de base de dados vetorial
PARSER	Operação de análise sintática que transforma texto para formato estruturado
RERANKER	Reclassificação dos contextos de ordenação de operações por relevância
MEMORY	Operação de memória persistindo contexto em armazenamento a longo prazo
UNKNOWN	Tipo padrão quando não seja especificado outro tipo

Configuração de tipos de vãos

Use o span_type parâmetro com decoradores ou gestores de contexto para definir SpanType:

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

Procurar intervalos por tipo

A consulta abrange programáticamente usando 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)

Também podes filtrar por tipo de span na interface do MLflow ao visualizar traços.

Períodos ativos vs. concluídos

Um span ativo ou LiveSpan é um que está a ser registado ativamente, como numa função decorada com @mlflow.trace ou num gestor de contexto de span. Uma vez que a função decorada ou o gestor de contexto concluam a execução, o trecho termina e torna-se um imutável Span.

Para modificar o intervalo ativo, obtenha uma referência para o intervalo usando mlflow.get_current_active_span().

RETRIEVER Esquema de Span

O RETRIEVER tipo span trata de operações que envolvem a recuperação de dados de um armazenamento de dados, como consultar documentos de um armazenamento vetorial. Este tipo de span tem um esquema de saída específico que permite funcionalidades melhoradas da interface e capacidades de avaliação. O resultado deve ser uma lista de documentos, onde cada documento é um dicionário com:

• page_content (str): Conteúdo de texto do bloco do documento recuperado
• metadata (Optional[Dict[str, Any]]): Metadados adicionais, incluindo:
  • doc_uri (str): URI da fonte do documento. Ao utilizar a Pesquisa Vetorial em Databricks, os spans RETRIEVER podem incluir caminhos de volume do Unity Catalog nos doc_uri metadados para rastreamento completo da linhagem.
  • chunk_id (str): Identificador se o documento faz parte de um documento em blocos maiores
• id (Optional[str]): Identificador único para o bloco do documento

A entidade MLflow Document ajuda a construir esta estrutura de saída.

Exemplo de implementação:

import mlflow
from mlflow.entities import SpanType, Document

def search_store(query: str) -> list[tuple[str, str]]:
    # Simulate retrieving documents 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 docs

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

Próximos passos

• Conceitos de traço - Compreender conceitos e estrutura ao nível de traço
• Traçar num caderno - Ganhe experiência prática com traçado