Pular para o conteúdo principal

Observabilidade da produção com rastreamento

MLflow Tracing fornece observabilidade abrangente para aplicativos GenAI de produção implantados fora do site Databricks, capturando detalhes de execução e enviando-os para o site Databricks workspace , onde o usuário pode view na interface do usuário MLflow.

Visão geral do rastreamento de produção do MLflow

Como funciona o rastreamento da produção:

  1. Seu aplicativo gera rastreamentos - Cada chamada de API cria dados de rastreamento
  2. Os rastros vão para o servidor de acompanhamento Databricks MLflow - Usando suas credenciais workspace
  3. view in MLflow UI - Analise os traços em seu Databricks workspace

Esta página aborda o rastreamento de aplicativos implantados fora do site Databricks. Se o seu aplicativo estiver implantado usando Databricks servindo modelo, consulte Rastreamento com Databricks servindo modelo.

Pré-requisitos​

nota

O rastreamento de produção requer o MLflow 3. O MLflow 2.x não é compatível com o rastreamento de produção.

Instale o pacote necessário. A tabela a seguir descreve suas opções:

tópico

mlflow-tracing

mlflow[databricks]

Caso de uso recomendado

Implantações de produção

Desenvolvimento e experimentação

Benefícios

Dependências mínimas para implantações rápidas e enxutas

desempenho otimizado para rastreamento de grandes volumes

Focado no rastreamento do lado do cliente para monitoramento da produção

Conjunto completo de recursos de experimentação MLflow (UI, LLM-as-a-judge, ferramentas de desenvolvimento e muito mais)

Inclui todas as ferramentas e utilidades de desenvolvimento

Python
## Install mlflow-tracing for production deployment tracing
%pip install --upgrade mlflow-tracing

## Install mlflow for experimentation and development
%pip install --upgrade "mlflow[databricks]>=3.1"

Configuração básica de rastreamento​

Configure a implementação do aplicativo para se conectar ao Databricks workspace para que o Databricks possa coletar traces.

Configure as seguintes variáveis de ambiente:

Bash
# Required: Set the Databricks workspace host and authentication token
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"

# Required: Set MLflow Tracking URI to "databricks" to log to Databricks
export MLFLOW_TRACKING_URI=databricks

# Required: Configure the experiment name for organizing traces (must be a workspace path)
export MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

Exemplos de implantação​

Depois que as variáveis de ambiente forem definidas, passe-as para o seu aplicativo. Clique na guia para ver como passar os detalhes da conexão para diferentes estruturas.

Para implementações em Docker, passe a variável de ambiente pela configuração do contêiner:

Dockerfile
# Dockerfile
FROM python:3.9-slim

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application code
COPY . /app
WORKDIR /app

# Set default environment variables (can be overridden at runtime)
ENV DATABRICKS_HOST=""
ENV DATABRICKS_TOKEN=""
ENV MLFLOW_TRACKING_URI=databricks
ENV MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

CMD ["python", "app.py"]

executar o contêiner com variável de ambiente:

Bash
docker run -d \
  -e DATABRICKS_HOST="https://your-workspace.cloud.databricks.com" \
  -e DATABRICKS_TOKEN="your-databricks-token" \
  -e MLFLOW_TRACKING_URI=databricks \
  -e MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app" \
  -e APP_VERSION="1.0.0" \
  your-app:latest

Verificar a coleta de traços​

Depois de implantar o aplicativo, verifique se os rastros foram coletados corretamente:

Python
import mlflow
from mlflow.client import MlflowClient
import os

# Ensure MLflow is configured for Databricks
mlflow.set_tracking_uri("databricks")

# Check connection to MLflow server
client = MlflowClient()
try:
    # List recent experiments to verify connectivity
    experiments = client.search_experiments()
    print(f"Connected to MLflow. Found {len(experiments)} experiments.")

    # Check if traces are being logged
    traces = mlflow.search_traces(
        experiment_names=[os.getenv("MLFLOW_EXPERIMENT_NAME", "/Shared/production-genai-app")],
        max_results=5
    )
    print(f"Found {len(traces)} recent traces.")
except Exception as e:
    print(f"Error connecting to MLflow: {e}")
    print(f"Check your authentication and connectivity")

Adicionar contexto aos traços​

Após os trabalhos básicos de rastreamento, adicione contexto para uma melhor depuração e percepção. MLflow tem as seguintes tags e atributos padronizados para capturar informações contextuais importantes:

  • Solicitação de acompanhamento - Vincule os rastros a chamadas específicas do site API para depuração de ponta a ponta
  • Sessões do usuário - Interações relacionadas ao grupo para entender as jornadas do usuário
  • Dados do ambiente - Acompanhe qual implantação, versão ou região gerou cada rastreamento
  • Feedback do usuário - Colete classificações de qualidade e vincule-as a interações específicas

Rastreie a solicitação, a sessão e o contexto do usuário​

Os aplicativos de produção precisam rastrear várias partes do contexto simultaneamente: IDs de solicitação do cliente para depuração, IDs de sessão para conversas com vários turnos, IDs de usuário para personalização e análise e metadados de ambiente para percepções operacionais. Aqui está um exemplo abrangente que mostra como rastrear tudo isso em um aplicativo FastAPI:

Python
import mlflow
import os
from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel

# Initialize FastAPI app
app = FastAPI()

class ChatRequest(BaseModel):
    message: str

@mlflow.trace # Ensure @mlflow.trace is the outermost decorator
@app.post("/chat") # FastAPI decorator should be inner
def handle_chat(request: Request, chat_request: ChatRequest):
    # Retrieve all context from request headers
    client_request_id = request.headers.get("X-Request-ID")
    session_id = request.headers.get("X-Session-ID")
    user_id = request.headers.get("X-User-ID")

    # Update the current trace with all context and environment metadata
    # The @mlflow.trace decorator ensures an active trace is available
    mlflow.update_current_trace(
        client_request_id=client_request_id,
        tags={
            # Session context - groups traces from multi-turn conversations
            "mlflow.trace.session": session_id,
            # User context - associates traces with specific users
            "mlflow.trace.user": user_id,
            # Environment metadata - tracks deployment context
            "environment": "production",
            "app_version": os.getenv("APP_VERSION", "1.0.0"),
            "deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
            "region": os.getenv("REGION", "us-east-1")
        }
    )

    # --- Your application logic for processing the chat message ---
    # For example, calling a language model with context
    # response_text = my_llm_call(
    #     message=chat_request.message,
    #     session_id=session_id,
    #     user_id=user_id
    # )
    response_text = f"Processed message: '{chat_request.message}'"
    # --- End of application logic ---

    # Return response
    return {
        "response": response_text
    }

# To run this example (requires uvicorn and fastapi):
# uvicorn your_file_name:app --reload
#
# Example curl request with all context headers:
# curl -X POST "http://127.0.0.1:8000/chat" \
#      -H "Content-Type: application/json" \
#      -H "X-Request-ID: req-abc-123-xyz-789" \
#      -H "X-Session-ID: session-def-456-uvw-012" \
#      -H "X-User-ID: user-jane-doe-12345" \
#      -d '{"message": "What is my account balance?"}'

Essa abordagem combinada oferece vários benefícios:

  • ID da solicitação do cliente : Permite a depuração de ponta a ponta, correlacionando traços com solicitações específicas de clientes em todo o sistema
  • ID da sessão (tag: mlflow.trace.session): grupos rastreiam conversas em vários turnos, permitindo que você analise todo o fluxo conversacional
  • ID do usuário (tag: mlflow.trace.user): Associa traços a usuários específicos para personalização, análise de coorte e depuração específica do usuário
  • Metadados do ambiente : Rastreia o contexto da implantação (ambiente, versão, região) para percepções operacionais e depuração em diferentes implantações

Para obter mais informações sobre como adicionar contexto aos traces, consulte a documentação sobre acompanhamento de usuários & sessions e acompanhamento de ambientes & context.

Colete feedback do usuário​

Capturar o feedback do usuário sobre interações específicas é essencial para entender a qualidade e melhorar seu aplicativo GenAI. Com base no acompanhamento da ID da solicitação do cliente mostrado na seção anterior, este exemplo demonstra como usar essa ID para vincular o feedback a traços específicos.

Aqui está um exemplo de implementação da coleta de feedback no FastAPI:

Python
import mlflow
from mlflow.client import MlflowClient
from fastapi import FastAPI, Query, Request
from pydantic import BaseModel
from typing import Optional
from mlflow.entities import AssessmentSource

# Initialize FastAPI app
app = FastAPI()

class FeedbackRequest(BaseModel):
    is_correct: bool  # True for correct, False for incorrect
    comment: Optional[str] = None

@app.post("/chat_feedback")
def handle_chat_feedback(
    request: Request,
    client_request_id: str = Query(..., description="The client request ID from the original chat request"),
    feedback: FeedbackRequest = ...
):
    """
    Collect user feedback for a specific chat interaction identified by client_request_id.
    """
    # Search for the trace with the matching client_request_id
    client = MlflowClient()
    # Get the experiment by name (using Databricks workspace path)
    experiment = client.get_experiment_by_name("/Shared/production-app")
    traces = client.search_traces(
        experiment_ids=[experiment.experiment_id],
        filter_string=f"attributes.client_request_id = '{client_request_id}'",
        max_results=1
    )

    if not traces:
        return {
            "status": "error",
            "message": f"Unable to find data for client request ID: {client_request_id}"
        }, 500

    # Log feedback using MLflow's log_feedback API
    mlflow.log_feedback(
        trace_id=traces[0].info.trace_id,
        name="response_is_correct",
        value=feedback.is_correct,
        source=AssessmentSource(
            source_type="HUMAN",
            source_id=request.headers.get("X-User-ID")
        ),
        rationale=feedback.comment
    )

    return {
        "status": "success",
        "message": "Feedback recorded successfully",
        "trace_id": traces[0].info.trace_id,
        "client_request_id": client_request_id,
        "feedback_by": request.headers.get("X-User-ID")
    }

# Example usage:
# After a chat interaction returns a response, the client can submit feedback:
#
# curl -X POST "http://127.0.0.1:8000/chat_feedback?client_request_id=req-abc-123-xyz-789" \
#      -H "Content-Type: application/json" \
#      -H "X-User-ID: user-jane-doe-12345" \
#      -d '{
#        "is_correct": true,
#        "comment": "The response was accurate and helpful"
#      }'

Essa abordagem de coleta de feedback permite que você:

  • Vincule o feedback a interações específicas : use o ID de solicitação do cliente para encontrar o rastreamento exato e anexar feedback
  • Armazenar feedback estruturado : A API log_feedback cria objetos de avaliação adequados que são visíveis na interface do usuário do MLflow
  • Analise os padrões de qualidade : consulte os rastreamentos com o feedback associado para identificar quais tipos de interações recebem avaliações positivas ou negativas

Posteriormente, o senhor pode consultar os traços com feedback usando a interface do usuário do MLflow ou de forma programática para analisar padrões e melhorar seu aplicativo.

Rastreamentos de consulta com contexto​

Use as informações contextuais para analisar o comportamento da produção:

Python
import mlflow
from mlflow.client import MlflowClient
import pandas as pd

client = MlflowClient()
experiment = client.get_experiment_by_name("/Shared/production-app")

# Query traces by user
user_traces = client.search_traces(
    experiment_ids=[experiment.experiment_id],
    filter_string="tags.`mlflow.trace.user` = 'user-jane-doe-12345'",
    max_results=100
)

# Query traces by session
session_traces = client.search_traces(
    experiment_ids=[experiment.experiment_id],
    filter_string="tags.`mlflow.trace.session` = 'session-123'",
    max_results=100
)

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.

Última atualização em