Duas respostas com o mesmo valor podem merecer ações opostas. “O usuário quer aprovar a transferência” com a distribuição concentrada em uma opção e a mesma frase com a distribuição espalhada entre três são a mesma string e dois fatos diferentes. O roteamento por confiança é o padrão que trata isso como um eixo próprio da decisão, e não como detalhe de log.
A formulação oficial é curta: a resposta diz o quê, a confiança diz se você deve agir.
O segundo eixo, na prática
Cada resposta de Choice e de Score traz uma distribuição de probabilidades e um número de 0 a 1 que resume a forma dessa distribuição. Concentrada significa confiança alta; espalhada significa confiança baixa. O conceito em si está em confiança; aqui interessa o que a arquitetura faz com ele.
A documentação sugere três faixas, e o valor de cada uma é a ação, não o número:
- Alta: agir automaticamente. O código segue sem gente.
- Média: seguir com cautela. Confirmar com o usuário, marcar para revisão ou buscar mais informação antes de agir.
- Baixa: não agir. Mandar para uma pessoa, pedir esclarecimento ou usar outro caminho.
O erro mais comum na primeira implementação é escrever if confianca > 0.8 uma
vez, em um arquivo de configuração, e aplicar a todas as decisões do sistema.
Isso confunde duas coisas: a dúvida do modelo e o risco da ação.
O limiar acompanha o risco
O exemplo oficial é uma interface bancária por voz, com um Choice de intenção entre consultar saldo, aprovar transferência e outro. O código do exemplo usa dois números diferentes:
| Situação | Corte do exemplo | Ação |
|---|---|---|
| Confiança abaixo do piso | 0,6 | vai para atendente humano |
| Consultar saldo | acima de 0,6 | mostra o saldo |
| Aprovar transferência | acima de 0,85 | executa sozinho |
| Aprovar transferência | entre 0,6 e 0,85 | pede confirmação ao usuário |
A lógica por trás dos números é a única parte que se transporta para o seu sistema: consultar saldo errado custa um incômodo; aprovar uma transferência errada custa dinheiro de outra pessoa. O piso protege contra dúvida genuína; o corte alto protege contra a ação irreversível.
Vale registrar uma divergência das próprias fontes. A página de confiança descreve o mesmo cenário com piso 0,5 e 0,9 para a operação destrutiva. Os dois pares são exemplos, e o fato de a documentação usar valores diferentes na mesma ideia é o melhor argumento contra copiar qualquer um deles.
acao = resposta.answers["intencao"]
if acao.confidence < PISO: # dúvida genuína
fila_humana(conta_id)
elif acao.choice == "consultar_saldo": # ação reversível
mostrar_saldo(conta_id)
elif acao.choice == "aprovar_transferencia":
if acao.confidence > CORTE_ALTO: # ação irreversível
aprovar(conta_id)
else:
pedir_confirmacao(conta_id)
O que este padrão obriga a arquitetura a ter
Uma tabela de risco por ação, não um número global. Se o seu sistema tem doze ações, ele tem até doze cortes. Eles pertencem ao código do domínio, junto da definição da ação, e não a uma variável de ambiente solta.
Registro da distribuição, não só da decisão. Guardar apenas “aprovado” faz o sistema perder a única evidência de que a decisão era defensável. No Brasil isso tem um motivo extra: o artigo 20 da Lei 13.709/2018 dá ao titular o direito de pedir revisão de decisão tomada unicamente por tratamento automatizado que afete seus interesses. Guardar probabilidade e confiança junto com a ação é o que torna essa revisão possível de verdade.
Um lugar para onde a incerteza vai. Uma faixa baixa sem fila é um if que
nunca é exercido. O padrão só funciona quando existe destino: pessoa, segundo
estágio ou pergunta ao usuário.
Limiar versionado com o modelo. A página de modelos avisa que um alias como
jev-latest se move quando sai uma versão nova. Se você calibrou cortes contra
uma versão, fixe o identificador dela e mude de versão no seu ritmo.
Quando não usar
Quando não existe destino para a incerteza. Se não há pessoa, fila nem caminho alternativo, gatilho de confiança baixa só produz um caso travado. Sem destino, é melhor assumir a decisão automática e medir o erro.
Quando a pergunta é Noul. Noul não devolve confiança. A dúvida aparece na própria probabilidade, e o desenho muda: em vez de um corte, uma banda central. A receita de classificar com confiança mostra o caso de Choice, e a leitura de Noul está em probabilidade não é confiança.
Quando o volume da faixa média é maior que a capacidade de revisão. Um corte generoso demais transforma o padrão em um gargalo humano. Se 40% dos casos caem na fila, ou o corte está errado, ou a pergunta está mal escrita — veja critérios que separam.
Quando a confiança baixa é sintoma, não informação. Confiança baixa em quase tudo costuma significar que as opções se sobrepõem, que o state não contém a resposta ou que a pergunta pede vários julgamentos ao mesmo tempo. Ajustar o limiar nesse caso é esconder o problema.
Por onde continuar
Este padrão é o vizinho natural do fan-out especulativo: um manda todas as perguntas, o outro decide o que fazer com as respostas incertas. Quando a decisão da faixa baixa é uma pessoa, o desenho da fila está em revisão humana no lugar certo. O índice dos padrões fica em padrões.
Perguntas frequentes
Qual limiar de confiança eu devo usar?
Não existe um. A documentação oficial é explícita: o limiar depende do domínio e do desempenho do modelo no seu caso, e a recomendação é começar conservador, testar com os seus dados e ajustar. Os números dos exemplos oficiais são ilustrações, não recomendações.
Por que a página de padrões e a página de confiança usam números diferentes?
Porque são dois exemplos do mesmo cenário. A página de roteamento por confiança usa piso 0,6 e 0,85 para a operação de risco; a página de confiança usa piso 0,5 e 0,9. As duas descrevem a mesma ideia com valores diferentes, o que já é um aviso de que o número não é a parte importante.
Noul tem confiança?
Não. A confiança é derivada da distribuição de probabilidades, e só Choice e Score devolvem distribuição. Com Noul, o que você tem é a própria probabilidade, e uma faixa central perto de 0,5 é o sinal de dúvida. A receita oficial de autoconsistência usa uma banda de 0,30 a 0,70 para isso.
Confiança alta significa que a resposta está certa?
Não. A documentação diz que a calibração é medida em grupos de previsões e não garante que uma resposta individual esteja correta. Confiança alta significa que a distribuição está concentrada, e em um modelo calibrado isso corresponde a uma taxa de acerto maior no agregado.
Onde eu coloco a revisão humana neste padrão?
Na faixa baixa e, quando a ação é irreversível, também na média. O desenho da fila, o que o revisor vê e o que fazer com a discordância estão em revisão humana no lugar certo.