Pular para o conteúdo principal

tutorial: Avalie e melhore sua aplicação

Este tutorial mostra como usar o conjunto de dados de avaliação para avaliar a qualidade, identificar problemas e melhorar seu aplicativo iterativamente.

Este guia usa rastros de um aplicativo prático para criar o dataset de avaliação. O mesmo fluxo de trabalho se aplica independentemente de como o dataset de avaliação foi criado. Para outras abordagens para criar um dataset de avaliação, consulte o guia de criação de conjunto de dados de avaliação.

Este guia o ajudará a avaliar um aplicativo de geração email que recupera informações de clientes de um banco de dados e gera e-mails de acompanhamento personalizados com base nas informações recuperadas. Inclui os seguintes passos:

  • Criar um conjunto de dados de avaliação a partir do uso real.
  • Avalie a qualidade com os avaliadores predefinidos do MLflow usando o chicote de avaliação.
  • Interprete os resultados para identificar problemas de qualidade.
  • Melhore seu aplicativo com base nos resultados da avaliação.
  • Compare as versões para verificar se as melhorias funcionaram e não causaram regressões.

Pré-requisitos​

  1. Instale o site MLflow e o pacote necessário

    Bash
    pip install --upgrade "mlflow[databricks]>=3.1.0" openai

  2. Crie um experimento MLflow seguindo o início rápido de configuração do ambiente.

  3. Para criar uma avaliação dataset, o senhor deve ter acesso a um esquema em Unity Catalog e ter permissões CREATE TABLE nesse esquema.

    Se estiver usando uma avaliaçãoDatabricks account , o senhor tem permissões CREATE TABLE no esquema Unity Catalog workspace.default.

nota

Executar um agente complexo pode levar muito tempo. Para configurar a paralelização, consulte (Opcional) Configurar paralelização.

Etapa 1: Crie seu aplicativo​

O primeiro passo é criar o aplicativo de geração email . O componente de recuperação é marcado com span_type="RETRIEVER" para habilitar os pontuadores específicos de recuperação do MLflow.

  1. Inicialize um cliente OpenAI para se conectar a LLMs hospedados pela Databricks ou LLMs hospedados pela OpenAI.

Use o MLflow para obter um cliente OpenAI que se conecta aos LLMs hospedados pela Databricks. Selecione um modelo dentre os modelos de base disponíveis.

Python
import mlflow
from databricks.sdk import WorkspaceClient

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client that is connected to Databricks-hosted LLMs
w = WorkspaceClient()
client = w.serving_endpoints.get_open_ai_client()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

  1. Crie o aplicativo de geração de " email ":

    Python
    from mlflow.entities import Document
    from typing import List, Dict

    # Simulated customer relationship management database
    CRM_DATA = {
        "Acme Corp": {
            "contact_name": "Alice Chen",
            "recent_meeting": "Product demo on Monday, very interested in enterprise features. They asked about: advanced analytics, real-time dashboards, API integrations, custom reporting, multi-user support, SSO authentication, data export capabilities, and pricing for 500+ users",
            "support_tickets": ["Ticket #123: API latency issue (resolved last week)", "Ticket #124: Feature request for bulk import", "Ticket #125: Question about GDPR compliance"],
            "account_manager": "Sarah Johnson"
        },
        "TechStart": {
            "contact_name": "Bob Martinez",
            "recent_meeting": "Initial sales call last Thursday, requested pricing",
            "support_tickets": ["Ticket #456: Login issues (open - critical)", "Ticket #457: Performance degradation reported", "Ticket #458: Integration failing with their CRM"],
            "account_manager": "Mike Thompson"
        },
        "Global Retail": {
            "contact_name": "Carol Wang",
            "recent_meeting": "Quarterly review yesterday, happy with platform performance",
            "support_tickets": [],
            "account_manager": "Sarah Johnson"
        }
    }

    # Use a retriever span to enable MLflow's predefined RetrievalGroundedness scorer to work
    @mlflow.trace(span_type="RETRIEVER")
    def retrieve_customer_info(customer_name: str) -> List[Document]:
        """Retrieve customer information from CRM database"""
        if customer_name in CRM_DATA:
            data = CRM_DATA[customer_name]
            return [
                Document(
                    id=f"{customer_name}_meeting",
                    page_content=f"Recent meeting: {data['recent_meeting']}",
                    metadata={"type": "meeting_notes"}
                ),
                Document(
                    id=f"{customer_name}_tickets",
                    page_content=f"Support tickets: {', '.join(data['support_tickets']) if data['support_tickets'] else 'No open tickets'}",
                    metadata={"type": "support_status"}
                ),
                Document(
                    id=f"{customer_name}_contact",
                    page_content=f"Contact: {data['contact_name']}, Account Manager: {data['account_manager']}",
                    metadata={"type": "contact_info"}
                )
            ]
        return []

    @mlflow.trace
    def generate_sales_email(customer_name: str, user_instructions: str) -> Dict[str, str]:
        """Generate personalized sales email based on customer data & a sale's rep's instructions."""
        # Retrieve customer information
        customer_docs = retrieve_customer_info(customer_name)

        # Combine retrieved context
        context = "\n".join([doc.page_content for doc in customer_docs])

        # Generate email using retrieved context
        prompt = f"""You are a sales representative. Based on the customer information below,
        write a brief follow-up email that addresses their request.

        Customer Information:
        {context}

        User instructions: {user_instructions}

        Keep the email concise and personalized."""

        response = client.chat.completions.create(
            model=model_name, # This example uses a Databricks hosted LLM - you can replace this with any AI Gateway or Model Serving endpoint. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
            messages=[
                {"role": "system", "content": "You are a helpful sales assistant."},
                {"role": "user", "content": prompt}
            ],
            max_tokens=2000
        )

        return {"email": response.choices[0].message.content}

    # Test the application
    result = generate_sales_email("Acme Corp", "Follow up after product demo")
    print(result["email"])

Rastreamento do aplicativo de

Etapa 2: simular o tráfego de produção​

Esta etapa simula o tráfego para fins de demonstração. Na prática, o senhor usaria traços de uso real para criar sua avaliação dataset.

Python
# Simulate beta testing traffic with scenarios designed to fail guidelines
test_requests = [
    {"customer_name": "Acme Corp", "user_instructions": "Follow up after product demo"},
    {"customer_name": "TechStart", "user_instructions": "Check on support ticket status"},
    {"customer_name": "Global Retail", "user_instructions": "Send quarterly review summary"},
    {"customer_name": "Acme Corp", "user_instructions": "Write a very detailed email explaining all our product features, pricing tiers, implementation timeline, and support options"},
    {"customer_name": "TechStart", "user_instructions": "Send an enthusiastic thank you for their business!"},
    {"customer_name": "Global Retail", "user_instructions": "Send a follow-up email"},
    {"customer_name": "Acme Corp", "user_instructions": "Just check in to see how things are going"},
]

# Run requests and capture traces
print("Simulating production traffic...")
for req in test_requests:
    try:
        result = generate_sales_email(**req)
        print(f"✓ Generated email for {req['customer_name']}")
    except Exception as e:
        print(f"✗ Error for {req['customer_name']}: {e}")

Etapa 3: Criar avaliação dataset​

Neste passo você converte os rastros em um dataset de avaliação. Armazenar os rastros em um dataset de avaliação permite que você vincule os resultados da avaliação ao dataset para que você possa rastrear alterações no dataset ao longo do tempo e ver todos os resultados da avaliação gerados usando esse dataset.

Siga a gravação abaixo para usar a IU para:

  1. Crie uma avaliação dataset.
  2. Adicione os traços de produção simulados da etapa 2 ao site dataset.

Crie uma avaliação dataset e adicione rastreamentos.

Etapa 4: avaliação da execução com pontuadores predefinidos​

Este passo mostra como usar os pontuadores predefinidos do MLflow para avaliar automaticamente diferentes aspectos da qualidade do aplicativo GenAI. Para saber mais, consulte Pontuadores baseados em LLM e Pontuadores baseados em código.

nota

Você também pode rastrear versões de aplicativos e prompts com o MLflow. Veja as versões do aplicativo de rastreamento e do prompt.

Python
from mlflow.genai.scorers import (
    RetrievalGroundedness,
    RelevanceToQuery,
    Safety,
    Guidelines,
)

# Save the scorers as a variable so you can re-use them in step 7

email_scorers = [
        RetrievalGroundedness(),  # Checks if email content is grounded in retrieved data
        Guidelines(
            name="follows_instructions",
            guidelines="The generated email must follow the user_instructions in the request.",
        ),
        Guidelines(
            name="concise_communication",
            guidelines="The email MUST be concise and to the point. The email should communicate the key message efficiently without being overly brief or losing important context.",
        ),
        Guidelines(
            name="mentions_contact_name",
            guidelines="The email MUST explicitly mention the customer contact's first name (e.g., Alice, Bob, Carol) in the greeting. Generic greetings like 'Hello' or 'Dear Customer' are not acceptable.",
        ),
        Guidelines(
            name="professional_tone",
            guidelines="The email must be in a professional tone.",
        ),
        Guidelines(
            name="includes_next_steps",
            guidelines="The email MUST end with a specific, actionable next step that includes a concrete timeline.",
        ),
        RelevanceToQuery(),  # Checks if email addresses the user's request
        Safety(),  # Checks for harmful or inappropriate content
    ]

# Run evaluation with predefined scorers
eval_results = mlflow.genai.evaluate(
    data=eval_dataset,
    predict_fn=generate_sales_email,
    scorers=email_scorers,
)

Etapa 5: visualizar e interpretar os resultados​

Executar mlflow.genai.evaluate() cria uma execução de avaliação. Para obter mais detalhes sobre a execução da avaliação, consulte Execução da avaliação.

Uma execução de avaliação é como um relatório de teste que captura tudo sobre o desempenho do seu aplicativo em um dataset específico. A execução de avaliação contém um rastreamento para cada linha no seu dataset de avaliação, juntamente com o feedback de cada avaliador.

Usando a execução de avaliação, você pode view métricas agregadas e investigar casos de teste em que seu aplicativo teve desempenho ruim.

Esta avaliação mostra vários problemas:

  • Seguimento deficiente de instruções - O agente frequentemente fornece respostas que não correspondem às solicitações do usuário, como o envio de informações detalhadas sobre o produto quando são solicitados check-ins simples ou o fornecimento de atualizações de tíquetes de suporte quando são solicitadas mensagens de agradecimento entusiasmadas.
  • Falta de concisão - A maioria dos e-mails é desnecessariamente longa e inclui detalhes excessivos que diluem a mensagem key, deixando de se comunicar de forma eficiente, apesar das instruções para manter o e-mail "conciso e personalizado".
  • Falta de próximas etapas concretas - A maioria dos e-mails não termina com próximas etapas específicas e acionáveis que incluam cronogramas concretos, o que foi identificado como um elemento necessário.

Acesse os resultados da avaliação por meio do site Evaluations tab na interface do usuário MLflow para entender o desempenho do seu aplicativo:

Resultados da avaliação

Etapa 6: criar uma versão aprimorada​

Com base nos resultados da avaliação, você pode criar uma versão aprimorada que solucione os problemas identificados.

Python
@mlflow.trace
def generate_sales_email_v2(customer_name: str, user_instructions: str) -> Dict[str, str]:
    """Generate personalized sales email based on customer data & a sale's rep's instructions."""
    # Retrieve customer information
    customer_docs = retrieve_customer_info(customer_name) # retrive_customer_info is defined in Step 1

    if not customer_docs:
        return {"error": f"No customer data found for {customer_name}"}

    # Combine retrieved context
    context = "\n".join([doc.page_content for doc in customer_docs])

    # Generate email using retrieved context with better instruction following
    prompt = f"""You are a sales representative writing an email.

MOST IMPORTANT: Follow these specific user instructions exactly:
{user_instructions}

Customer context (only use what's relevant to the instructions):
{context}

Guidelines:
1. PRIORITIZE the user instructions above all else
2. Keep the email CONCISE - only include information directly relevant to the user's request
3. End with a specific, actionable next step that includes a concrete timeline (e.g., "I'll follow up with pricing by Friday" or "Let's schedule a 15-minute call this week")
4. Only reference customer information if it's directly relevant to the user's instructions

Write a brief, focused email that satisfies the user's exact request."""

    response = client.chat.completions.create(
        model="databricks-claude-3-7-sonnet",
        messages=[
            {"role": "system", "content": "You are a helpful sales assistant who writes concise, instruction-focused emails."},
            {"role": "user", "content": prompt}
        ],
        max_tokens=2000
    )

    return {"email": response.choices[0].message.content}

# Test the application
result = generate_sales_email("Acme Corp", "Follow up after product demo")
print(result["email"])

Etapa 7: Avalie a nova versão e compare​

Execute a avaliação da versão aprimorada usando os mesmos avaliadores e o site dataset para ver se o senhor conseguiu resolver os problemas.

Python
import mlflow

# Run evaluation of the new version with the same scorers as before
# Use start_run to name the evaluation run in the UI
with mlflow.start_run(run_name="v2"):
    eval_results_v2 = mlflow.genai.evaluate(
        data=eval_dataset, # same eval dataset
        predict_fn=generate_sales_email_v2, # new app version
        scorers=email_scorers, # same scorers as step 4
    )

Etapa 8: comparar os resultados​

Compare os resultados para entender se as mudanças melhoraram a qualidade.

Navegue até a interface de usuário do MLflow para comparar os resultados da avaliação:

trace

Etapa 9: iteração contínua​

Com base nos resultados da avaliação, você pode continuar iterando para melhorar a qualidade do aplicativo e testar cada nova correção.

Exemplo de notebook​

O Notebook a seguir inclui todo o código desta página.

Avaliação de um aplicativo GenAI - Guia de início rápido

Open notebook in new tab

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