Como escrever uma rubrica que a Decisions API aplique sempre do mesmo jeito

Fala aí, beleza? Se o mesmo conteúdo recebe notas diferentes a cada avaliação, quase sempre o problema está na rubrica, não no modelo

A OpenAI colocou a Decisions API em beta pública em 6 de outubro de 2026 (ela foi anunciada no DevDay, em 29 de setembro)

Um dos tipos de pergunta dela, o score, depende totalmente de quão claro está cada nível

Rubrica vaga deixa o modelo dividido entre dois níveis, e a nota balança 😛

Então bora montar uma rubrica que dá pra aplicar sempre do mesmo jeito: critérios observáveis, níveis com exemplo de fronteira e o corte de tudo que depende de gosto

A meta aqui é reduzir variação entre pontuações do mesmo conteúdo, beleza? Ninguém vai te prometer a mesma nota cravada em toda chamada

Antes de começar: qual Decisions API e como funciona a pergunta score

Se liga nisso primeiro, porque existem duas APIs com o mesmo nome

Este guia é sobre a Decisions API da OpenAI: endpoint dedicado POST /v1/decisions, que roda só com o gpt-6-luna e aceita entrada de texto e imagem

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

A Perplexity também tem uma Decisions API, com o modelo pplx-decider-v1-27b

Ela também tem pergunta do tipo score: rubrica ordenada em que a posição na lista é o nível, até 10 níveis, e retorno com nível esperado, probabilidade de cada nível e uma confidence

A ideia de rubrica ordenada aparece nas duas, então o raciocínio de escrita serve de base pra ambas

Os limites e campos de retorno citados daqui pra frente são os da OpenAI

Quais são os tipos de pergunta da Decisions API?

São três:

• predicate: devolve a probabilidade, de 0 a 1, de uma condição ser verdadeira
• choice: escolhe uma opção de uma lista fixa, com probabilidades
• score: devolve uma posição ponderada em níveis ordenados

A rubrica deste post vale pro score

O que a pergunta score faz exatamente?

Ela avalia a entrada contra níveis ordenados do mais baixo pro mais alto, com critérios definidos pra cada nível

Os níveis são indexados a partir de zero, ou seja, o primeiro nível é o 0

Na resposta vêm quatro campos:

• score: média dos índices dos níveis ponderada pela probabilidade (pode cair entre dois níveis)
• legend: cada índice como string, mapeado de volta pra entrada da rubrica
• probabilities: um valor por nível
• confidence

Uma coisa que tu NÃO vai ver aqui: formato de payload, autenticação ou setup

O foco é o texto da rubrica, que é o que decide se a nota faz sentido ou não 🙂

Passo a passo para escrever a rubrica

Os exemplos abaixo são a rubrica em texto, numerada pelo índice

Não é o schema da requisição, é só o conteúdo que você vai descrever em cada nível

1. Confirme que o caso pede score

Score só faz sentido quando os níveis têm uma sequência com sentido, onde subir um nível significa mais de alguma coisa (mais grave, mais completo, mais pronto)

Se não existe ordem, o caso é de choice (uma categoria entre várias) ou de predicate (sim ou não com probabilidade)

Tem ordem (score): ausente < parcial < completo
Não tem ordem (choice): financeiro, suporte técnico, comercial
É sim ou não (predicate): o ticket menciona dado pessoal?

Erro comum deste passo: usar score pra categorias sem ordem

Se tu põe financeiro como 0 e comercial como 2, um score de 1 vira uma média sem significado nenhum

2. Defina quantos níveis e em que ordem

A pergunta score aceita no mínimo 2 e no máximo 10 níveis

A ordem é sempre do mais baixo pro mais alto, com índice começando em zero

0. Nível mais baixo
1. Nível intermediário
2. Nível mais alto

Quantos níveis usar? Só os que você consegue distinguir com um critério concreto

Se não dá pra explicar a diferença entre o nível 4 e o 5 em uma frase objetiva, provavelmente eles são o mesmo nível

Erro comum deste passo: inverter a ordem e colocar o mais grave no índice 0

Tome cuidado com essa inversão, porque o score continua saindo e parece certo, só que de cabeça pra baixo…

3. Escreva critérios observáveis por nível

Critério observável é aquele que dá pra conferir olhando a entrada, sem adivinhar intenção nem sensação de ninguém

O exemplo oficial de severidade da OpenAI é um modelo muito massa disso:

0. Cosmetic: só aparência, nenhuma funcionalidade perdida
1. Workaround available: uma tarefa falha, mas outro caminho funciona
2. Fully blocked: uma tarefa falha sem alternativa

Se liga que cada nível responde perguntas verificáveis: alguma tarefa falhou? Existe outro caminho que funciona?

É a mesma lógica de um prompt com saída em formato fixo: quanto menos espaço pra interpretação, menos a saída varia

Erro comum deste passo: descrever sensação em vez de fato

Usuário muito irritado não é critério, é leitura de humor, e duas avaliações podem ler o humor de jeitos diferentes

4. Escreva a fronteira entre níveis vizinhos

Aqui mora a maior parte da variação

Os casos fáceis caem sozinhos no nível certo, o problema é o caso que fica bem na divisa

Então, pra cada par de níveis vizinhos, escreva o que faz um caso subir ou descer:

0. Cosmetic: só aparência, nenhuma funcionalidade perdida
   Fronteira com 1: se alguma tarefa deixa de funcionar, já não é 0,
   mesmo que a causa seja visual
   Ex.: botão desalinhado mas clicável = 0

1. Workaround available: uma tarefa falha, mas outro caminho funciona
   Fronteira com 2: existe outro caminho que entrega o mesmo resultado?
   Ex.: botão escondido, mas a mesma ação existe no menu = 1

2. Fully blocked: uma tarefa falha sem alternativa
   Ex.: botão escondido e a ação não existe em nenhum outro lugar = 2

Incluir exemplo de fronteira é boa prática geral de rubrica, não uma regra da documentação

Mas repara como o critério da fronteira vira uma pergunta de sim ou não, que é bem mais difícil de interpretar de dois jeitos

Erro comum deste passo: critérios que se sobrepõem

Se o nível 1 diz afeta poucos usuários e o nível 2 diz bloqueia uma tarefa, um bug que bloqueia uma tarefa de poucos usuários serve nos dois, e aí a nota fica dividida

5. Corte o que depende de gosto

A documentação da OpenAI diz que o score funciona quando a rubrica define operacionalmente o que cada nível significa

O exemplo dela: rótulos como serviço bloqueado e pequeno incômodo são mais testáveis do que urgente e não urgente sem definição

Antes:
0. Não urgente
1. Urgente

Depois:
0. Pequeno incômodo: tudo funciona, só incomoda
1. Serviço bloqueado: alguém não consegue concluir a tarefa

Urgente pra quem? Pro dev é uma coisa, pro cliente é outra, e o modelo não tem como saber qual dos dois você quis dizer

Erro comum deste passo: deixar palavras como bom, grave, bonito ou relevante sem critério

Se a palavra precisa de opinião pra ser aplicada, ela precisa sair ou virar uma condição concreta

6. Leia a resposta pra diagnosticar a rubrica

Agora vem a parte que transforma a resposta em ferramenta de debug da rubrica

O score é média ponderada, então pode cair entre dois níveis

No exemplo oficial de severidade, com probabilidades 0.1, 0.7 e 0.2, o score sai 1.1

Como assim 1.1, se não existe nível 1.1? É a conta: 0 × 0.1 + 1 × 0.7 + 2 × 0.2 = 1.1

Ou seja, o modelo foi majoritariamente pro nível 1, com uma parte puxando pro 2

Use os campos assim:

• probabilities: mostra entre quais níveis o modelo se dividiu
• legend: liga cada índice de volta ao nível da sua rubrica, pra você saber qual texto revisar
• confidence: mais um sinal pra olhar junto, mas não trate como garantia

Erro comum deste passo: arredondar o score e ignorar a divisão de probabilidade entre níveis vizinhos

Quando a probabilidade se espalha entre dois níveis vizinhos, isso costuma apontar uma fronteira mal escrita, e é exatamente ela que você volta no passo 4 pra reescrever

Exemplos de rubrica: do vago ao aplicável

Bora ver na prática? Três pares de antes e depois, curtinhos

Como escrever uma rubrica de severidade de bug?

Antes:
0. Leve
1. Médio
2. Grave

Depois:
0. Cosmetic: só aparência, nenhuma funcionalidade perdida
1. Workaround available: uma tarefa falha, mas outro caminho funciona
2. Fully blocked: uma tarefa falha sem alternativa

Por que reduz variação? Leve, médio e grave pedem opinião, já tarefa falhou e existe alternativa são fatos que dá pra conferir na entrada

Como avaliar a completude dos passos de reprodução?

Essa ideia vem da documentação da Perplexity, que usa os passos de reprodução como exemplo de quando faz sentido usar score: ausentes, parciais e completos têm uma sequência clara

Antes:
0. Ticket ruim
1. Ticket ok
2. Ticket bom

Depois:
0. Ausentes: não há nenhuma descrição de como chegar no erro
1. Parciais: há alguns passos, mas falta algo pra repetir o erro
   (ambiente, dado de entrada ou ação final)
2. Completos: dá pra seguir os passos do início até o erro
   sem precisar perguntar nada

Por que reduz variação? Ticket bom mistura escrita, tom e conteúdo, enquanto dá pra repetir o erro só com o que está escrito é um teste só

A mesma doc da Perplexity mostra o efeito de ficar na divisa: um ticket dividido igualmente entre os níveis 2 e 3 dá score de cerca de 2.5

Como trocar urgente e não urgente por níveis operacionais?

Antes:
0. Não urgente
1. Urgente

Depois:
0. Pequeno incômodo: tudo funciona, o problema só atrapalha
1. Tarefa com alternativa: uma tarefa falha, mas dá pra concluir
   por outro caminho
2. Serviço bloqueado: uma tarefa falha e não há outro caminho

Por que reduz variação? Urgente depende de quem lê, enquanto o novo texto pergunta se a tarefa falhou e se existe outro caminho

E ainda ganhou um nível do meio, o que deixa o score mais informativo que um sim ou não

Quanto custa reavaliar o mesmo conteúdo?

Na beta, a entrada custa US$ 0,10 por 1 milhão de tokens, e leitura e escrita de cache e tokens de saída não são cobrados

Isso deixa barato rodar o mesmo lote de conteúdo com a rubrica antiga e com a nova pra comparar onde as probabilidades se dividem

A OpenAI também afirma que a API é cerca de 10x mais rápida que a Responses API pra produzir essas respostas (afirmação dela), o que ajuda nesse ciclo de ajuste

Checklist final e próximo passo

Antes de colocar a rubrica em produção, confere:

• Os níveis estão do mais baixo pro mais alto, com o primeiro no índice 0?
• Tem entre 2 e 10 níveis?
• Cada nível tem um critério observável na entrada?
• A fronteira entre cada par de vizinhos está escrita, de preferência com exemplo?
• Sobrou algum rótulo que depende de gosto (urgente, bom, grave, bonito)?

O próximo passo é simples: pega uma rubrica que você já usa, reescreve os níveis seguindo os passos acima e acompanha em probabilities onde o modelo ainda se divide

Cada divisão entre vizinhos é uma pista de qual fronteira reescrever 😀

E lembra que a Decisions API ainda está em beta, com a disponibilidade geral prevista pras próximas semanas e sem data definida

Até o próximo post!