Pular para o conteúdo principal
Última atualização em

tutorial: Avaliar e melhorar um aplicativo GenAI

Este tutorial mostra como usar um conjunto de dados de avaliação para avaliar a qualidade, identificar problemas e aprimorar iterativamente um aplicativo AI generativa.

Este guia o ajudará a avaliar um aplicativo de geração de email que usa Geração Aumentada de Recuperação (RAG). O aplicativo simula a recuperação de informações do cliente de um banco de dados e gera e-mails de acompanhamento personalizados com base nas informações recuperadas.

Para uma introdução mais curta à avaliação, veja a demonstração de 10 minutos: Avaliar um aplicativo GenAI.

Este tutorial inclui os seguintes passos:

O tutorial utiliza rastreamentos de um aplicativo implantado para criar o dataset de avaliação, mas o mesmo fluxo de trabalho se aplica independentemente de como você criou seu dataset de avaliação. Para outras abordagens na criação de um dataset de avaliação, consulte Construindo um conjunto de dados de avaliação MLflow. Para obter informações sobre rastreamento, consulte MLflow Tracing - GenAI observability.

Diagrama de fluxo de trabalho de monitoramento offline

Pré-requisitos​

  1. Instale o pacote necessário:

    Python
    %pip install -q --upgrade "mlflow[databricks]>=3.1.0" openai
    dbutils.library.restartPython()

  2. Crie um experimento MLflow. Se você estiver usando um Databricks Notebook, pode pular esta etapa e usar o experimento default do Notebook. Caso contrário, siga o início rápido de configuração do ambiente para criar o experimento e conectar-se ao servidor de acompanhamento MLflow .

  3. Para criar um dataset de avaliação, você deve ter permissões CREATE TABLE em um esquema no Unity Catalog.

    Se você estiver usando uma accountde testeDatabricks, deverá ter 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 está marcado com span_type="RETRIEVER" para habilitar os juízes LLM 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 databricks-openai para obter um cliente OpenAI que se conecta a LLMs hospedados no Databricks. Selecione um modelo dentre os modelos de fundação disponíveis.

Python
import mlflow
from databricks_openai import DatabricksOpenAI

# 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
client = DatabricksOpenAI()

# 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 judge 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​

Este passo simula tráfego para fins de demonstração. Na prática, você usaria registros de uso real para criar seu dataset de avaliação.

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​

Nesta etapa, você salva os rastros em um dataset de avaliação. Armazenar os registros em um dataset de avaliação permite vincular os resultados da avaliação ao dataset dataset possibilitando o acompanhamento das alterações ao longo do tempo e a visualização de todos os resultados de avaliação gerados com esse dataset.

  1. Clique em Experimentos na barra lateral para exibir a página de Experimentos.

  2. Clique no nome do seu experimento para abri-lo.

    Experimento aberto

  3. Na barra lateral esquerda, clique em Vestígios .

  4. Use as caixas de seleção no lado esquerdo da lista de rastreamento para selecionar os rastreamentos que deseja adicionar. Para selecionar todos os rastreamentos na página atual, clique na caixa de seleção ao lado de ID do rastreamento no cabeçalho da coluna.

    Selecionar traços

  5. Ações de clique. O rótulo do botão mostra o número de rastros selecionados, por exemplo , Ações (3) .

    Menu de ações

  6. Em " Usar para avaliação" , selecione " Adicionar ao datasetde avaliação" . A caixa de diálogo Adicionar traços ao datasetde avaliação é aberta.

  7. Se não existir um conjunto de dados de avaliação para este experimento, ou se você quiser adicionar traços a um novo dataset, siga estes passos para criar um novo dataset de avaliação:

    1. Clique em Criar novo dataset .
    2. Selecione o esquema Unity Catalog para armazenar o novo dataset.
    3. Insira um nome para o dataset e clique em Criar conjunto de dados .
    4. Clique em Exportar e depois em Concluído .

    Adicionar caixa de diálogo de rastreamento se não existir nenhum conjunto de dados de avaliação.

    Se já existir um conjunto de dados de avaliação para o experimento, clique em Exportar à direita do dataset ao qual deseja adicionar os traços. Você pode exportar para mais de um dataset. Quando terminar de exportar, clique em Concluído .

    Adicionar caixa de diálogo de rastreamento se houver um conjunto de dados de avaliação existente.

o passo 4: avaliação de execução com juízes LLM​

Neste passo, você usa os juízes LLM integrados do MLflow para avaliar automaticamente diferentes aspectos da qualidade do aplicativo GenAI. Para saber mais, consulte Juízes de LLM e avaliadores baseados em código.

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

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

email_judges = [
        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 LLM judges
eval_results = mlflow.genai.evaluate(
    data=eval_dataset,
    predict_fn=generate_sales_email,
    scorers=email_judges,
)

Etapa 5: visualizar e interpretar os resultados​

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

Uma execução de avaliação é como um relatório de teste que registra tudo sobre o desempenho do seu aplicativo em um dataset específico. A execução da avaliação contém um registro para cada linha do seu dataset de avaliação, com 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.

Resumo da avaliação​

  1. Clique em Experimentos na barra lateral para exibir a página de Experimentos.

  2. Clique no nome do seu experimento para abri-lo.

  3. Na barra lateral esquerda, clique em Execução da avaliação . O painel direito mostra uma tabela de traçados.

    Tabela de execução da avaliação

    Se você não visualizar as Avaliações com seus respectivos rótulos de Aprovado e Reprovado , role para a direita ou passe o cursor sobre o separador do painel e clique na seta apontando para a esquerda.

    Expandir tabela

  4. Para ver a justificativa para o rótulo "Aprovado" ou "Reprovado" , passe o cursor sobre o rótulo.

    Passe o cursor sobre o rótulo para exibir a justificativa.

Detalhes e comentários​

Para ver mais detalhes sobre cada traço:

  1. Clique no identificador da solicitação na coluna Solicitação . Aparece uma janela mostrando o rastreamento completo, incluindo entradas e saídas para cada passo.

    Janela de detalhes da solicitação

  2. À direita, você pode adicionar comentários ou expectativas a serem aplicados à resposta para esta solicitação. Se você não visualizar o painel Avaliações, clique em Botão de avaliações. Para adicionar uma nova avaliação, role para baixo e clique.Botão Adicionar nova avaliação.

  3. Você pode usar as setas em ambos os lados desta janela para navegar entre as solicitações.

    o passar pelas solicitações usando setas

Etapa 6: criar uma versão aprimorada​

Utilize os resultados da avaliação para criar uma versão melhorada que resolva os problemas identificados.

Ao criar uma versão aprimorada, concentre-se em mudanças específicas com base nos resultados da avaliação. As estratégias comuns de melhoria incluem:

  • Engenharia de prompts: Aprimore os prompts do sistema para abordar padrões de falha específicos, adicione diretrizes explícitas para casos extremos, inclua exemplos que demonstrem o tratamento correto ou ajuste o tom ou estilo.
  • Medidas de segurança: Implemente a validação dos passos na lógica da aplicação e adicione pós-processamento para verificar as saídas antes de apresentá-las aos usuários.
  • Melhorias (para aplicativos RAG): Aprimorar os mecanismos de recuperação caso documentos relevantes não sejam encontrados, examinando os intervalos de recuperação, melhorando os modelos de incorporação ou refinando as estratégias de segmentação.
  • Aprimoramentos de raciocínio: Divida tarefas complexas em múltiplos trechos, implemente técnicas de cadeia de pensamento ou adicione verificação de etapas para resultados críticos.

O código abaixo demonstra melhorias de engenharia imediatas com base nos resultados da avaliação:

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-sonnet-4-5",
        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 na versão melhorada usando os mesmos juízes e dataset para ver se você resolveu os problemas com sucesso.

Python
import mlflow

# Run evaluation of the new version with the same judges 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_judges, # same judges as step 4
    )

o passo 8: Comparar resultados​

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

  1. Clique em Experimentos na barra lateral para exibir a página de Experimentos.

  2. Clique no nome do seu experimento para abri-lo.

  3. Na barra lateral esquerda, clique em Execução da avaliação . O painel esquerdo mostra uma lista da execução da avaliação para este experimento.

    painel de execução

  4. Marque as caixas correspondentes à execução que deseja comparar.

  5. No menu suspenso Ações , selecione Comparar .

    Selecione a execução para comparar

  6. O painel direito exibe uma comparação de cada traço na execução selecionada.

    Tela de comparação de traços

  7. Para obter mais detalhes, clique no identificador da solicitação na coluna Solicitação . Uma janela é exibida mostrando os rastreamentos completos da solicitação de cada execução selecionada para comparação.

    Janela de detalhes da comparação

    Para ver os detalhes de cada avaliação, clique em Ver detalhes . Para ver os detalhes do rastreamento, clique em Ver viewdetalhada do rastreamento .

o passo 9: Continue iterando​

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

Abrir notebook em uma nova aba

Próximas etapas​

Guia de referência​