Pular para o conteúdo principal

Rastreamento manual

Embora o rastreamento automático do MLflow ofereça observabilidade instantânea para as estruturas compatíveis, o rastreamento manual oferece controle total sobre como os aplicativos GenAI são instrumentados. Essa flexibilidade é essencial para a criação de aplicativos prontos para produção que exigem recursos detalhados de monitoramento e depuração.

Pré-requisitos​

Este guia requer o seguinte pacote:

  • mlflow[databricks]> =3.1: Funcionalidade principal do MLflow com recurso GenAI e conectividade Databricks.
  • openai > =1.0.0 : (Opcional) Somente se seu código personalizado interagir com o OpenAI; substitua por outros SDKs, se necessário.

Instale os requisitos básicos:

Python
%pip install --upgrade "mlflow[databricks]>=3.1"
# %pip install --upgrade openai>=1.0.0 # Install if needed
nota

Recomendação da versão do MLflow

Embora os recursos de rastreamento manual estejam disponíveis em MLflow 2.15.0+, é altamente recomendável instalar MLflow 3 (especificamente 3.1 ou mais recente se estiver usando mlflow[databricks] ) para obter os recursos mais recentes do GenAI, incluindo recurso de rastreamento expandido, tipos de extensão refinados, propagação de contexto aprimorada e suporte robusto.

dica

O senhor está correndo em um notebook Databricks ? O MLflow vem pré-instalado. Você só precisará instalar SDKs adicionais se seu código rastreado manualmente os usar.

Executando localmente? Você precisará instalar o mlflow[databricks] e quaisquer outros SDKs que seu código chama.

Quando usar o rastreamento manual​

O rastreamento manual é a escolha certa quando você precisa:

Estrutura de rastreamento personalizada

  • Defina exatamente quais partes do seu código devem ser rastreadas
  • Crie hierarquias personalizadas de extensões
  • O controle abrange limites e relacionamentos

Exemplo de caso de uso : rastreamento de lógica comercial específica em um pipeline RAG em que o senhor deseja medir a latência de recuperação versus geração separadamente.

Abordagens de rastreamento manual​

O MLflow oferece três níveis de abstração para o rastreamento manual, cada um adequado a diferentes casos de uso:

1. APIs de alto nível (recomendado)​

As APIs de alto nível oferecem uma maneira intuitiva de adicionar rastreamento com alterações mínimas no código. Eles tratam automaticamente o ciclo de vida do rastreamento, o acompanhamento de exceções e os relacionamentos pai-filho.

Ideal para : Rastreamento em nível de função com alterações mínimas de código

Python
import mlflow
from mlflow.entities import SpanType

@mlflow.trace(span_type=SpanType.CHAIN)
def process_request(query: str) -> str:
    # Your code here - automatically traced!
    result = generate_response(query)
    return result

@mlflow.trace(span_type=SpanType.LLM)
def generate_response(query: str) -> str:
    # Nested function - parent-child relationship handled automatically
    return llm.invoke(query)

Principais benefícios :

  • Instrumentação de uma linha
  • Tratamento automático de exceções
  • Funciona com funções assíncronas/geradoras
  • Compatível com rastreamento automático

Saiba mais sobre decoradores →

2. APIs de cliente de baixo nível (avançadas)​

Para cenários que exigem controle total sobre o ciclo de vida do rastreamento, as APIs do cliente fornecem acesso direto ao backend de rastreamento do MLflow.

Python
from mlflow import MlflowClient

client = MlflowClient()

# Start a trace
root_span = client.start_trace("complex_workflow")

# Create child spans with explicit parent relationships
child_span = client.start_span(
    name="data_retrieval",
    request_id=root_span.request_id,
    parent_id=root_span.span_id,
    inputs={"query": query}
)

# End spans explicitly
client.end_span(
    request_id=child_span.request_id,
    span_id=child_span.span_id,
    outputs={"documents": documents}
)

# End the trace
client.end_trace(request_id=root_span.request_id)

Quando usar APIs de cliente :

  • Gerenciamento de ID de rastreamento personalizado
  • Integração com sistemas de observabilidade existentes
  • Requisitos complexos do ciclo de vida do rastreamento
  • Padrões de rastreamento não padrão
atenção

As APIs do cliente exigem gerenciamento manual:

  • Relações entre pais e filhos
  • Ciclo de vida do Span (começar/terminar)
  • Tratamento de exceções
  • Segurança da rosca

Saiba mais sobre as APIs do cliente → O senhor pode fazer o que quiser.

API Comparação​

Recurso

Decorador

Gerenciador de contexto

APIs de cliente

Pai-filho automático

Sim

Sim

Não - gerenciamento manual

Tratamento de exceções

Automático

Automático

Manual

Funciona com rastreamento automático

Sim

Sim

Não

Segurança da rosca

Automático

Automático

Manual

IDs de rastreamento personalizados

Não

Não

Sim

Melhor para

Rastreamento de funções

Rastreamento de blocos de código

Controle avançado

Padrões comuns​

Combinação com rastreamento automático​

O rastreamento manual se integra perfeitamente aos recursos de rastreamento automático do MLflow:

Python
import mlflow
import openai

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

@mlflow.trace(span_type="CHAIN")
def rag_pipeline(query: str):
    # Manual span for retrieval
    with mlflow.start_span(name="retrieval") as span:
        docs = retrieve_documents(query)
        span.set_outputs({"doc_count": len(docs)})

    # Auto-traced OpenAI call
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": f"Answer based on: {docs}\n\nQuery: {query}"}]
    )

    return response.choices[0].message.content

Rastreamento de fluxo de trabalho complexo​

Para fluxos de trabalho complexos com várias etapas, use vãos aninhados para capturar o fluxo de execução detalhado:

Python
@mlflow.trace(name="data_pipeline")
def process_data_pipeline(data_source: str):
    # Extract phase
    with mlflow.start_span(name="extract") as extract_span:
        raw_data = extract_from_source(data_source)
        extract_span.set_outputs({"record_count": len(raw_data)})

    # Transform phase
    with mlflow.start_span(name="transform") as transform_span:
        transformed = apply_transformations(raw_data)
        transform_span.set_outputs({"transformed_count": len(transformed)})

    # Load phase
    with mlflow.start_span(name="load") as load_span:
        result = load_to_destination(transformed)
        load_span.set_outputs({"status": "success"})

    return result

Personalizando visualizações de solicitações e respostas na interface do usuário​

A interface do usuário MLflow fornece as colunas Request e Response em Traces tab que mostram uma visualização da entrada e saída do rastreamento geral. Em default, elas são truncadas. Ao usar o rastreamento manual, especialmente com o decorador @mlflow.trace ou gerenciadores de contexto que criam a extensão raiz de um rastreamento, você pode personalizar essas visualizações usando mlflow.update_current_trace().

Isso é útil para estruturas de dados complexas em que a visualização do site default pode não ser informativa.

Python
import mlflow
import openai # Assuming openai is used, replace if not

# This example assumes you have an OpenAI client initialized and API key set up.
# client = openai.OpenAI()

@mlflow.trace
def predict(messages: list[dict]) -> str:
    # Customize the request preview to show the first and last messages
    custom_preview = f'{messages[0]["content"][:10]} ... {messages[-1]["content"][:10]}'
    mlflow.update_current_trace(request_preview=custom_preview)

    # Call the model
    # response = openai.chat.completions.create(
    #     model="gpt-4o-mini",
    #     messages=messages,
    # )
    # return response.choices[0].message.content
    return f"Response based on {len(messages)} messages."

messages = [
    {"role": "user", "content": "Hi, how are you?"},
    {"role": "assistant", "content": "I'm good, thank you!"},
    {"role": "user", "content": "What's your name?"},
    # ... (long message history)
    {"role": "assistant", "content": "Bye!"},
]
predict(messages)

Isso permite que você personalize a visualização para ser mais informativa para suas estruturas de dados específicas.

Próximas etapas​

Continue sua jornada com estas ações recomendadas e o tutorial.

Guia de referência​

Explore a documentação detalhada dos conceitos e recursos mencionados neste guia.

dica

A maioria dos usuários deve começar com as APIs de alto nível (decoradores e gerenciadores de contexto). Eles oferecem o melhor equilíbrio entre facilidade de uso e funcionalidade, mantendo a compatibilidade com o ecossistema do MLflow.

Última atualização em