Adicione metadados e feedback do usuário aos rastreamentos

O MLflow Tracing permite que os aplicativos de produção aumentem os rastros com metadados e contexto adicionais, como IDs de solicitação, IDs de sessão e de usuário e tags personalizadas. Os aplicativos também podem log o feedback do usuário juntamente com os traços. Esses metadados podem então ser usados para organizar, analisar e depurar traços.

Adicionar metadados aos rastreamentos

Após os trabalhos básicos de rastreamento, adicione metadados ou contexto aos rastreamentos para melhorar a depuração e as percepções. 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. MLflow tem os seguintes atributos e tags padronizados para capturar informações contextuais importantes:

Metadados	Casos de uso	Atributo ou tag MLflow
ID da solicitação do cliente	Vincular rastreamentos a solicitações específicas de clientes ou chamadas de API para depuração de ponta a ponta	TraceInfo Parâmetro client_request_id
ID da sessão do usuário	Rastreamentos de grupo a partir de conversas em vários turnos, permitindo que você analise todo o fluxo conversacional	mlflow.trace.session Etiqueta
ID do usuário	Associe traços a usuários específicos para personalização, análise de coorte e depuração específica do usuário	mlflow.trace.user Etiqueta
Dados do ambiente	Rastrear o contexto da implantação (ambiente, versão, região) para percepções operacionais e depuração em diferentes implantações	tags automáticas e tags personalizadas comuns
Personalizado tags	Adicione metadados personalizados, especialmente para rastreamento de organização, pesquisa e filtragem	(suas tags)

abaixo é um exemplo abrangente que mostra como rastrear tudo isso em um aplicativo FastAPI.

Python

import mlflow
import os
from fastapi import FastAPI, Request, HTTPException # HTTPException might be needed depending on full app logic
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 decorator
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,
        metadata={
            # 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,
            # Override automatically populated environment metadata
            "mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"),  # Override default LOCAL/NOTEBOOK
            # Add customer environment metadata
            "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"),
            # Add custom tags
            "my_custom_tag": "custom tag value",
        }
    )

    # --- 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 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?"}'

Para obter mais informações sobre como adicionar contexto aos traces, consulte:

• Rastreie as sessões & dos usuários
• Monitore os ambientes da versão &
• Anexar tags e metadados personalizados
• mlflow.update_current_trace() API para adicionar metadados
• Documentação do MLflow Tracing para obter uma lista de tags preenchidas automaticamente e tags padrão reservadas

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 do ID da solicitação do cliente mostrado em Adicionar metadados aos rastreamentos, o exemplo da FastAPI abaixo demonstra como fazer isso:

• Vincule o feedback a interações específicas usando o ID de solicitação do cliente para encontrar o rastreamento exato e anexar o feedback.
• Armazene feedback estruturado usando os botões log_feedback e log_expectation APIs para criar objetos de feedback estruturado que são visíveis na interface do usuário MLflow.
• Analise os padrões de qualidade consultando os traços com o feedback associado para identificar quais tipos de interações recebem avaliações positivas ou negativas.

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
    feedback = 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 feedback

# 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"
#      }'

Para obter mais informações sobre o registro de feedback do usuário, consulte:

• Colete feedback do usuário
• mlflow.log_feedback() API e log_expectation API para armazenar feedback estruturado

Rastreamentos de consulta com metadados

Depois de adicionar metadados aos traces, o senhor pode usar essas informações contextuais para analisar o comportamento da produção. Especificamente, o método MLflowClient.search_traces() permite a filtragem por tags e metadados. O exemplo abaixo encontra rastros para um usuário específico e uma sessão de usuário específica.

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
)

Para ver muitos exemplos de casos de uso de mlflow.search_traces(), consulte Pesquisar e analisar rastreamentos.

Next os passos

• Rastreie as sessões & dos usuários
• Monitore os ambientes da versão &
• Anexar tags e metadados personalizados
• Colete feedback do usuário
• Avalie e monitore seu agente usando scorers, conjunto de dados de avaliação e monitoramento de produção

referências de recursos

Para obter detalhes sobre os conceitos e recursos deste guia, consulte:

• Modelo de dados de rastreamento - Saiba mais sobre traços, extensões e atributos
• Avaliações de registro - Entenda como o feedback é armazenado e usado
• Pesquise e analise rastreamentos - Veja exemplos de consultas para muitos casos de uso comuns de mlflow.search_traces()