05 Fechar o ciclo

Material do facilitador para 05 Fechar o ciclo.

Duração

~25 minutos no total.

• 5 min — criar e promover os três registros derivados da produção.
• 5 min — iniciar experimentos pareados policy-v1 e policy-v2.
• 5 min — comparar correctness e calibrar business-policy-adherence.
• 5 min — ativar a regra protegida de observação e reproduzir quatro tipos de métrica.
• 5 min — inspecionar evidências e discutir rollback, custo e próximo ciclo.

Os dois experimentos e evaluators assíncronos podem ultrapassar esses blocos. Inicie cedo, use a espera para conceitos e ensaie a latência do provedor no dia anterior.

Preflight do instrutor

Na raiz, execute verificações não mutantes e confirme a configuração selecionada:

cd ClickHouse_Demos/workshops/agent_arena
.venv/bin/python -m scripts.promote_to_golden --help
.venv/bin/python -m scripts.provision_online_evaluators --help
.venv/bin/python -m eval.harness --help
.venv/bin/python -m scripts.verify_online_scores --help

Depois, confirme:

• o Módulo 03 tem uma raiz chat_turn com sql-execution-success=true e Boolean user-thumbs=false;
• a tarefa production-investigation-<session> do Módulo 04 está concluída, o SQL foi executado, o ID real está disponível em privado e o ID da anotação foi registrado quando exibido;
• reviewed.json virá da revisão genuína, não do fixture sintético;
• WINNER_MODEL, WINNER_PROMPT e WINNER_CONFIG_ID descrevem o mesmo vencedor;
• a conexão agent-arena-openrouter alcança o modelo judge com credenciais válidas;
• a saída categórica aceita exatamente PASS, FAIL e NOT_APPLICABLE, com raciocínio; e
• o dispatcher está saudável e recebe pontuações assíncronas.

Para cada ensaio, crie um sufixo único e mantenha o par junto:

export LOOP_RUN_SUFFIX="$(date +%Y%m%d-%H%M%S)"
export BASELINE_RUN_ID="online-loop-baseline-${LOOP_RUN_SUFFIX}"
export CANDIDATE_RUN_ID="online-loop-candidate-${LOOP_RUN_SUFFIX}"

Não reutilize IDs de sessão. O harness acrescenta versão da política e configuração; um ID base único evita comparar evidências desconexas ou sobrescritas.

Limite da anotação manual

A anotação do Módulo 04 não é automatizada. Scripts não criam a fila, preenchem julgamentos, inserem saída corrigida, aprovam nem concluem. Um fixture sintético versionado serve ao ensaio sem revisão real, mas continua source=synthetic-reviewed-fixture e não comprova ciclo humano.

Para participantes, use o reviewed.json genuíno e ignorado. A formulação original é uma pergunta real; as outras duas são paráfrases escritas pelo revisor:

How many active customers do we have?
What is our active customer count right now?
How many customers qualify as active under our business definition?

As três preservam o mesmo trace e proveniência. Diga isso para não confundirem um incidente com três traces de feedback.

Confiabilidade e proveniência da promoção

Antes da execução, inspecione reviewed.json sem projetá-lo. Ele precisa de SQL exato somente leitura, proveniência obrigatória e três IDs únicos seguros. A promoção valida o lote local e lê metadados autenticados antes de executar no ClickHouse ou fazer upsert. Falha de modo fechado se não puder ler metadados e rejeita colisão com proveniência diferente.

Promoção genuína idêntica é idempotente. Fixture sintético exige --synthetic-fixture; não pode ser caminho direto nem combinar com reviewed.json. Nunca o execute depois da promoção real. Em colisão, preserve fontes, investigue o item e escolha novo ID auditado somente se forem casos realmente distintos.

Regra de experimento versus regra de observação

Mantenha os contextos visíveis:

O provisionador instala um evaluator geral orientado pelo catálogo, não só para contagem de clientes. O catálogo policy-v2 cobre clientes ativos, receita, conversão e margem bruta; perguntas sem relação devem ser NOT_APPLICABLE.

A fase --business-policy-experiments deve indicar online rule enabled=False. Confira a interface. O comando posterior prova a existência de uma pontuação business-policy-adherence no dataset, mas não substitui a revisão completa.

Portões de calibração

Compare baseline e candidata com mesmos IDs, modelo e prompt. Há 20 perguntas YAML, mas q019 e q020 são holdouts; um projeto limpo passa de 18 a 21 itens após a promoção. O projeto compartilhado verificado tinha 22 por conter um item antigo; a execução foi de 16/22 para 19/22. Isso é evidência qualificada, não contagem obrigatória nem garantia de agregados estocásticos.

Não ative até que:

• os três prod-active-* passem de FAIL e incorretos em policy-v1 a PASS e corretos em policy-v2;
• receita (q005) e conversão (q018) da candidata sejam PASS;
• a contagem simples (q001) seja NOT_APPLICABLE;
• não haja regressão 1→0 de correctness em nenhum item existente;
• a correctness agregada não regrida; e
• todo item tenha correctness, agent-arena-llm-judge e a pontuação exata business-policy-adherence com saída estruturada válida.

Um judge que chama toda contagem de PASS falhou. A sonda NOT_APPLICABLE prova que aplicabilidade é uma classificação real.

Pontuação assíncrona e solução de ausência de pontuação

Avaliações de experimentos e observações são assíncronas. O harness espera pontuações; scripts.verify_online_scores consulta traces por 180 segundos. Não atualize freneticamente, recrie regras nem ative cedo por uma pontuação pendente.

Se não aparecerem:

1. Confirme o nome: Experiments usam business-policy-adherence; serving usa agent-arena-business-policy-online.
2. Confirme dispatcher/worker saudável.
3. Verifique a conexão agent-arena-openrouter e o modelo judge. Atraso, limite ou roteamento podem deixar avaliação pendente/falha mesmo com resposta do agente.
4. Confirme regra de experimento em arena-golden e regra de observação em raízes chat_turn; o mapeamento deve expor $.question e $.sql.
5. Inspecione saída estruturada. Categoria ausente, inválida ou sem raciocínio é falha de calibração.
6. Se houver nome de regra ambíguo, resolva duplicatas exatas antes de repetir; não adivinhe qual foi atualizada.

Preserve traces e evidências falhas. Não transforme indisponibilidade em PASS inventado nem pule o portão.

Orientação para reprodução

Após ativar, reinicie explicitamente em policy-v2 e use as quatro perguntas exatas:

How many active customers do we have?
What was revenue in the last 30 days?
What is our view-to-purchase conversion rate for the last 7 days?
How many products are there?

Exija sucesso operacional em todas. Clientes ativos, receita e conversão devem ter agent-arena-business-policy-online=PASS; produtos, NOT_APPLICABLE.

A conversão tem limite estocástico verificado. Permita uma repetição com a mesma configuração, preserve IDs e outcomes e pare se ambas falharem. Falha repetida é nova evidência de produção, não motivo para repetir até ficar verde.

Amostragem, custo e confiabilidade

As regras usam amostragem 1 para todos verem evidências. Em produção, um judge LLM em toda solicitação aumenta custo, consome limite e pode pontuar após a resposta. Escolha a amostragem conforme tráfego, risco, custo/latência e cobertura. Mantenha verificações operacionais determinísticas amplas; reserve julgamento semântico caro ao tráfego em que compensa.

O evaluator monitora; não autoriza no caminho da requisição. Um judge atrasado não deve bloquear a resposta. Encaminhe pontuações ausentes, deriva de categoria e divergências a alertas ou backlog conforme os objetivos de serviço.

Rollback e redefinição

Se o judge produzir falsos resultados, saída malformada ou custo/latência inaceitável:

1. Em Evaluations, encontre agent-arena-business-policy-online e desative.
2. Confirme que novos chat_turn não recebem essa pontuação.
3. Mantenha policy-v2, sql-execution-success e 👍/👎 salvo se suas próprias evidências disserem o contrário; desativar judge ruim não deve restaurar política antiga.
4. Adicione traces afetados a uma fila humana com sufixo, melhore catálogo/prompt e dados dourados e repita a calibração antes de reativar.

Para parar serviços locais sem apagar evidências remotas:

scripts/arena.sh stop

scripts/arena.sh down também remove banco e usuário somente leitura do ClickHouse, mas não datasets, Experiments, filas ou pontuações do Langfuse. Não o use como rollback do evaluator.

Roteiro de fala: o ciclo permanece aberto

• O evaluator original aprovou porque seu contrato era apenas “SQL executou”. O 👎 revelou falha de valor fora dele.
• A revisão humana transformou sinal incerto em diagnóstico e correção testados.
• A proveniência tornou o incidente auditável no conjunto dourado; paráfrases ampliaram cobertura sem inventar traces.
• Experimentos pareados isolaram a mudança de política e testaram o judge geral antes da produção.
• Um PASS online não torna feedback obsoleto. agent-arena-business-policy-online=PASS junto de user-thumbs=false deve reiniciar a investigação.

Portão de conclusão

Não encerre sem seis artefatos:

1. trace de produção com aprovação operacional e sinal negativo;
2. anotação concluída e SQL corrigido verificado;
3. três itens dourados com proveniência genuína;
4. evidência baseline/candidata no mesmo dataset sem regressão;
5. evidências calibradas FAIL, PASS e NOT_APPLICABLE; e
6. pontuações ao vivo habilitadas para clientes ativos, receita, conversão e contagem simples, mantendo 👍/👎 para o próximo ciclo.