01 Selecionar o modelo base

Guia do facilitador para a lição 01 Selecionar o modelo base.

Tempo

~20 minutos com o subconjunto recomendado; 45 a 60 minutos para executar a grade completa ao vivo.

• 8 min — configuração dos evaluators do Langfuse: LLM Connection, evaluator de código correctness e definição de LLM-as-a-judge llm_judge, que emite agent-arena-llm-judge. Demonstre ao vivo no seu projetor, em vez de apenas apontar para o README — é a etapa mais delicada da sessão.
• 8 min — execute um subconjunto de dois modelos e um prompt. Explique durante a espera por que usamos custo por resposta correta. Uma grade completa costuma levar 35 a 45 minutos e deve ser pré-executada ou deixada para o trabalho autoguiado.
• 4 min — abra o Leaderboard, leia o vencedor e diga o config_id.

Roteiro

• Apresente esta como a decisão fundamental do workshop: qual modelo alimenta o agente, definido por evidências e não por um ranking público criado sobre outra carga.
• Destaque onde a avaliação acontece: dentro do Langfuse, não no harness. O harness coordena a grade e registra Experiment Items completos; o ranking os lê pela API pública do Langfuse. É o mesmo projeto conectado no Módulo 00 — nenhuma nova ferramenta ou segundo armazenamento de resultados aparece aqui.
• Esclareça a cardinalidade: o repositório tem 20 perguntas YAML; q019 e q020 são exemplos few-shot reservados, portanto um dataset de experimento arena-golden limpo tem 18 itens.
• Nomeie a métrica principal e explique por que não é precisão bruta: custo por resposta correta — qualidade por dólar nesta tarefa. O custo usa preços ao vivo do OpenRouter, atualizados no começo de cada execução, e não um valor antigo gravado em config.yaml.
• Mostre o vocabulário da grade: seis modelos, proprietários e de pesos abertos (claude-sonnet-5, gpt-5.6-luna, gemini-flash-lite / deepseek-v4-flash, qwen3.7-flash, glm-4.7-flash) × prompts (P1_zeroshot … P3_dialect); um config_id é <model>__<prompt>.
• Clique ao vivo em uma linha do Leaderboard, depois em um resultado por pergunta e no trace correspondente do Langfuse — o Módulo 02 aprofunda esse hábito de investigação.
• Pare no vencedor e diga seu config_id em voz alta — todos os módulos seguintes retornam a ele.

Falhas comuns

• Evaluators do Langfuse não configurados — o harness espera somente até --eval-timeout (180s por padrão), sai com código diferente de zero e informa as pontuações ausentes. Ele aguarda a pontuação exata agent-arena-llm-judge, emitida pela definição llm_judge. Execute python -m scripts.provision_langfuse_evaluators para esse juiz apoiado pelo OpenRouter, corrija o destino/filtro do evaluator correctness e execute uma grade pequena de dois modelos e um prompt com novo --run-id; não há fallback de resultados local porque o Langfuse é o armazenamento da avaliação.
• Placeholder OPENROUTER_API_KEY — cada chamada falha com 401. Isso deve ser confirmado no Módulo 00; se passou, aparece aqui como uma execução inteira com zero respostas corretas.
• Slug do modelo saiu do catálogo do OpenRouter — os ids em config.yaml (por exemplo, anthropic/claude-sonnet-5) refletem o catálogo na data de criação, mas o OpenRouter remove ou renomeia slugs. Em uma falha imediata de modelo inexistente, consulte https://openrouter.ai/api/v1/models e compare com config.yaml. O endpoint /api/models do dashboard reflete o catálogo atual e revela rapidamente a divergência.
• ClickHouse não preparado — se o Módulo 00 não terminou, consultas do harness às views v_* retornam vazio ou erro, e todas as configurações mostram o mesmo outcome. Execute scripts/arena.sh up novamente.
• Execução parece travada — a grade é models × prompts (6 × 3 = 18 configurações por padrão) e pode demorar. Use --models/--prompts para reduzi-la na demonstração.

Etapas de recuperação

• Confirme a preparação do ClickHouse: scripts/arena.sh up (idempotente e seguro para repetir).
• Execute um subconjunto barato: python -m eval.harness --run-id demo2 --models qwen3.7-flash,gpt-5.6-luna --prompts P1_zeroshot,P3_dialect
• Sempre use um novo --run-id (por exemplo, demo2, demo3) para criar linhas próprias no Leaderboard e um experimento próprio no Langfuse, sem mesclar execuções.
• Se os evaluators bloquearem, verifique o destino Experiments e o filtro de dataset arena-golden, depois repita o subconjunto com novo --run-id.
• Se somente o dashboard estiver travado, scripts/arena.sh stop e depois scripts/arena.sh serve reiniciam os servidores locais sem tocar nos dados preparados.