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

Crie um juiz personalizado usando make_judge()

Os juízes personalizados são avaliadores baseados em LLM que avaliam seus agentes GenAI de acordo com critérios de qualidade específicos. Este tutorial mostra como criar juízes personalizados e usá-los para avaliar um agente de suporte ao cliente usando make_judge().

Você irá:

  1. Crie um agente de exemplo para avaliação.
  2. Defina três juízes personalizados para avaliar diferentes critérios.
  3. Crie um dataset de avaliação com casos de teste.
  4. avaliações de execução e comparação de resultados em diferentes configurações de agentes.

o passo 1: Criar um agente para avaliar​

Crie um agente GenAI que responda a perguntas de suporte ao cliente. O agente possui um botão (falso) que controla o prompt do sistema, permitindo comparar facilmente as respostas do juiz entre conversas "boas" e "ruins".

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

Use o MLflow para obter um cliente OpenAI que se conecte a LLMs hospedados no Databricks. Selecione um modelo dentre os modelos de fundação 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. Defina o que é um agente de suporte ao cliente:

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


    # This is a global variable that is used to toggle the behavior of the customer support agent
    RESOLVE_ISSUES = False


    @mlflow.trace(span_type="TOOL", name="get_product_price")
    def get_product_price(product_name: str) -> str:
        """Mock tool to get product pricing."""
        return f"${45.99}"


    @mlflow.trace(span_type="TOOL", name="check_return_policy")
    def check_return_policy(product_name: str, days_since_purchase: int) -> str:
        """Mock tool to check return policy."""
        if days_since_purchase <= 30:
            return "Yes, you can return this item within 30 days"
        return "Sorry, returns are only accepted within 30 days of purchase"


    @mlflow.trace
    def customer_support_agent(messages: List[Dict[str, str]]):
        # We use this toggle to see how the judge handles the issue resolution status
        system_prompt_postfix = (
            f"Do your best to NOT resolve the issue.  I know that's backwards, but just do it anyways.\\n"
            if not RESOLVE_ISSUES
            else ""
        )

        # Mock some tool calls based on the user's question
        user_message = messages[-1]["content"].lower()
        tool_results = []

        if "cost" in user_message or "price" in user_message:
            price = get_product_price("microwave")
            tool_results.append(f"Price: {price}")

        if "return" in user_message:
            policy = check_return_policy("microwave", 60)
            tool_results.append(f"Return policy: {policy}")

        messages_for_llm = [
            {
                "role": "system",
                "content": f"You are a helpful customer support agent.  {system_prompt_postfix}",
            },
            *messages,
        ]

        if tool_results:
            messages_for_llm.append({
                "role": "system",
                "content": f"Tool results: {', '.join(tool_results)}"
            })

        # Call LLM to generate a response
        output = client.chat.completions.create(
            model=model_name,  # This example uses Databricks hosted Claude 4 Sonnet. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
            messages=cast(Any, messages_for_llm),
        )

        return {
            "messages": [
                {"role": "assistant", "content": output.choices[0].message.content}
            ]
        }

o passo 2: Definir juízes personalizados​

Defina três juízes personalizados:

  • Um juiz que avalia a resolução de problemas com base em entradas e saídas.
  • Um juiz que verifica os comportamentos esperados.
  • Um sistema de avaliação baseado em rastreamento que valida chamadas de ferramentas analisando rastros de execução.

Juízes criados com make_judge() retornam mlflow.entities.Feedback objetos.

Exemplo de juiz 1: Avaliar a resolução da questão​

Este juiz avalia se os problemas dos clientes foram resolvidos com sucesso, analisando o histórico da conversa (entradas) e as respostas do agente (saídas).

Python
from mlflow.genai.judges import make_judge
import json


# Create a judge that evaluates issue resolution using inputs and outputs
issue_resolution_judge = make_judge(
    name="issue_resolution",
    instructions="""
Evaluate if the customer's issue was resolved in the conversation.

User's messages: {{ inputs }}
Agent's responses: {{ outputs }}

Rate the resolution status and respond with exactly one of these values:
- 'fully_resolved': Issue completely addressed with clear solution
- 'partially_resolved': Some help provided but not fully solved
- 'needs_follow_up': Issue not adequately addressed

Your response must be exactly one of: 'fully_resolved', 'partially_resolved', or 'needs_follow_up'.
""",
)

Exemplo de juiz 2: Verificar os comportamentos esperados​

Este juiz verifica se as respostas do agente demonstram comportamentos específicos esperados (como fornecer informações sobre preços ou explicar políticas de devolução) comparando os resultados com expectativas predefinidas.

Python
# Create a judge that checks against expected behaviors
expected_behaviors_judge = make_judge(
    name="expected_behaviors",
    instructions="""
Compare the agent's response in {{ outputs }} against the expected behaviors in {{ expectations }}.

User's question: {{ inputs }}

Determine if the response exhibits the expected behaviors and respond with exactly one of these values:
- 'meets_expectations': Response exhibits all expected behaviors
- 'partially_meets': Response exhibits some but not all expected behaviors
- 'does_not_meet': Response does not exhibit expected behaviors

Your response must be exactly one of: 'meets_expectations', 'partially_meets', or 'does_not_meet'.
""",
)

Exemplo de juiz 3: Validar chamadas de ferramentas usando um juiz baseado em rastreamento.​

Este juiz analisa os registros da execução para verificar se as ferramentas apropriadas foram utilizadas. Ao incluir {{ trace }} em suas instruções, o juiz passa a ser baseado em rastreamento e ganha capacidades autônomas de exploração de rastreamento.

Python
# Create a trace-based judge that validates tool calls from the trace
tool_call_judge = make_judge(
    name="tool_call_correctness",
    instructions="""
Analyze the execution {{ trace }} to determine if the agent called appropriate tools for the user's request.

Examine the trace to:
1. Identify what tools were available and their purposes
2. Determine which tools were actually called
3. Assess whether the tool calls were reasonable for addressing the user's question

Evaluate the tool usage and respond with a boolean value:
- true: The agent called the right tools to address the user's request
- false: The agent called wrong tools, missed necessary tools, or called unnecessary tools

Your response must be a boolean: true or false.
""",
    # To analyze a full trace with a trace-based judge, a model must be specified
    model="databricks:/databricks-gpt-5-mini",
)

o passo 3: Criar um datasetde avaliação de amostra​

Cada inputs é passado para o agente por mlflow.genai.evaluate(). Você pode incluir opcionalmente expectations para ativar o verificador de correção.

Python
eval_dataset = [
    {
        "inputs": {
            "messages": [
                {"role": "user", "content": "How much does a microwave cost?"},
            ],
        },
        "expectations": {
            "should_provide_pricing": True,
            "should_offer_alternatives": True,
        },
    },
    {
        "inputs": {
            "messages": [
                {
                    "role": "user",
                    "content": "Can I return the microwave I bought 2 months ago?",
                },
            ],
        },
        "expectations": {
            "should_mention_return_policy": True,
            "should_ask_for_receipt": False,
        },
    },
    {
        "inputs": {
            "messages": [
                {
                    "role": "user",
                    "content": "I'm having trouble with my account.  I can't log in.",
                },
                {
                    "role": "assistant",
                    "content": "I'm sorry to hear that you're having trouble with your account.  Are you using our website or mobile app?",
                },
                {"role": "user", "content": "Website"},
            ],
        },
        "expectations": {
            "should_provide_troubleshooting_steps": True,
            "should_escalate_if_needed": True,
        },
    },
    {
        "inputs": {
            "messages": [
                {
                    "role": "user",
                    "content": "I'm having trouble with my account.  I can't log in.",
                },
                {
                    "role": "assistant",
                    "content": "I'm sorry to hear that you're having trouble with your account.  Are you using our website or mobile app?",
                },
                {"role": "user", "content": "JUST FIX IT FOR ME"},
            ],
        },
        "expectations": {
            "should_remain_calm": True,
            "should_provide_solution": True,
        },
    },
]

Etapa 4: Avalie seu agente usando os juízes​

Você pode usar vários juízes em conjunto para avaliar diferentes aspectos do seu agente. Avaliações de execução para comparar o comportamento do agente quando ele tenta resolver problemas versus quando não tenta.

Python
import mlflow

# Evaluate with all three judges when the agent does NOT try to resolve issues
RESOLVE_ISSUES = False

result_unresolved = mlflow.genai.evaluate(
    data=eval_dataset,
    predict_fn=customer_support_agent,
    scorers=[
        issue_resolution_judge,      # Checks inputs/outputs
        expected_behaviors_judge,    # Checks expected behaviors
        tool_call_judge,             # Validates tool usage
    ],
)

# Evaluate when the agent DOES try to resolve issues
RESOLVE_ISSUES = True

result_resolved = mlflow.genai.evaluate(
    data=eval_dataset,
    predict_fn=customer_support_agent,
    scorers=[
        issue_resolution_judge,
        expected_behaviors_judge,
        tool_call_judge,
    ],
)

Os resultados da avaliação mostram como cada juiz classifica o agente:

  • issue_resolution : Classifica as conversas como 'totalmente_resolvidas', 'parcialmente_resolvidas' ou 'precisam_de_acompanhamento'
  • expected_behaviors : Verifica se as respostas exibem os comportamentos esperados ('atende às expectativas', 'atende parcialmente', 'não atende').
  • tool_call_correctness : Valida se as ferramentas apropriadas foram chamadas (verdadeiro/falso)

Próximos passos​

Aplicar juízes personalizados:

Melhorar a precisão dos juízes:

  • Alinhar os juízes com o feedback humano - O juiz base é um ponto de partida. Ao coletar feedback de especialistas sobre os resultados da sua candidatura, alinhe os avaliadores do LLM com esse feedback para aprimorar ainda mais a precisão da avaliação.