Conceitos de extensão

O objeto Span é um componente fundamental no modelo de dados Trace. Ele serve como um contêiner para informações sobre os passos individuais de um rastreamento, como chamadas LLM , execução de ferramentas, operações de recuperação e muito mais.

Os spans se organizam hierarquicamente dentro de um trace 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 design Span do MLflow mantém a compatibilidade com as especificações do OpenTelemetry. O esquema inclui onze propriedades principais:

Propriedade	Tipo	Descrição
`span_id`	`str`	Identificador único para este trecho dentro do rastreamento.
`trace_id`	`str`	Os links se estendem até seu rastreamento pai.
`parent_id`	`Optional[str]`	Estabelece relação hierárquica; `None` para 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 obter detalhes completos, consulte a referência da API do 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, como informaçõesUnity Catalog, detalhes endpointdo modelo de serviço e metadados de infraestrutura para uma melhor observabilidade.

Atributos de exemplo para 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

O MLflow fornece dez tipos de intervalos predefinidos para categorização. Você também pode usar valores de string personalizados para operações especializadas.

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 quando nenhum outro tipo for especificado.

Definindo tipos de intervalo

Utilize o parâmetro span_type com decoradores ou gerenciadores 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

Consulte intervalos de consulta programaticamente usando o SDK:

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.

Esquemas de extensão especializados

Determinados tipos de extensão possuem esquemas de saída específicos que possibilitam recursos de interface do usuário aprimorados e capacidades de avaliação.

RETRIEVER abrange

O tipo de span RETRIEVER lida com operações que envolvem a recuperação de dados de um armazenamento de dados, como consultar documentos de um armazenamento vetorial. O resultado 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): URI de origem do documento
- chunk_id (str): Identificador se o documento faz parte de um documento fragmentado maior.
id (Optional[str]): Identificador único para o bloco de documento

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

No Databricks : Ao usar a Pesquisa Vetorial, os spans do RETRIEVER podem incluir caminhos de volume Unity Catalog nos metadados doc_uri para acompanhamento completo da linhagem.

CHAT_MODEL abrange

Os trechos do tipo CHAT_MODEL ou LLM representam interações com APIs de preenchimento automático de chat (por exemplo, o preenchimento automático de chat da OpenAI ou a API de mensagens da Anthropic).

Embora não existam requisitos de formato rígidos para entradas e saídas, MLflow fornece funções utilitárias para padronizar mensagens de chat e definições de ferramentas para visualização e avaliação de interfaces de usuário avançadas:

Python
import mlflow
from mlflow.entities import SpanType
from mlflow.tracing.constant import SpanAttributeKey
from mlflow.tracing import set_span_chat_messages, set_span_chat_tools

# Example messages and tools
messages = [
    {
        "role": "system",
        "content": "please use the provided tool to answer the user's questions",
    },
    {"role": "user", "content": "what is 1 + 1?"},
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "add",
            "description": "Add two numbers",
            "parameters": {
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"},
                },
                "required": ["a", "b"],
            },
        },
    }
]

@mlflow.trace(span_type=SpanType.CHAT_MODEL)
def call_chat_model(messages, tools):
    # Simulate a response with tool calls
    response = {
        "role": "assistant",
        "tool_calls": [
            {
                "id": "123",
                "function": {"arguments": '{"a": 1,"b": 2}', "name": "add"},
                "type": "function",
            }
        ],
    }

    combined_messages = messages + [response]

    # Use MLflow utilities to standardize the format
    span = mlflow.get_current_active_span()
    set_span_chat_messages(span, combined_messages)
    set_span_chat_tools(span, tools)

    return response

# Usage
call_chat_model(messages, tools)

# Retrieve the standardized data
trace = mlflow.get_last_active_trace()
span = trace.data.spans[0]

print("Messages:", span.get_attribute(SpanAttributeKey.CHAT_MESSAGES))
print("Tools:", span.get_attribute(SpanAttributeKey.CHAT_TOOLS))

Próximos passos

Conceitos de traços - Compreender os conceitos e a estrutura do nível de traços.
Traçando em um caderno - Obtenha experiência prática com traçado.

Esquema de objeto Span​

Atributos de extensão​

Tipos de extensão​

Definindo tipos de intervalo​

Pesquisando intervalos por tipo​

Esquemas de extensão especializados​

RETRIEVER abrange​

CHAT_MODEL abrange​

Próximos passos​