Rotulagem de dados e triagem com a OpenAI Decisions API

Da rotulagem de dados à triagem: defina a decisão

Pense na Decisions como um serviço de triagem com destinos predefinidos. Você fornece as evidências e a pergunta; sua aplicação decide o que fazer quando a resposta chega.

Em 11 de outubro de 2026, a API está em beta público, com disponibilidade geral prevista “nas próximas semanas”. Essa é a expectativa da OpenAI, não uma data de lançamento. gpt-6-luna é o único modelo compatível, e o endpoint é POST /v1/decisions. A OpenAI afirma que a API é “cerca de 10x mais rápida que a Responses API”. Entenda isso como uma afirmação da OpenAI, não como um resultado medido na sua aplicação. Guia da Decisions da OpenAI

Escolha o formato da resposta antes de escrever o prompt:

Em uma pontuação, os níveis começam no índice 0. O resultado pode ficar entre os níveis, pois resume a incerteza entre eles. Use uma escolha quando seu código precisar de uma única categoria. Tipos de pergunta

Como fazer cada uma das três requisições

Estes são os três exemplos de requisição cURL do guia, copiados com a formatação padronizada e comentários adicionados para separá-los. Defina OPENAI_API_KEY no ambiente do shell; o exemplo de predicado também precisa de um arquivo local product.png. Cada comando faz uma requisição independente. Os exemplos foram conferidos no guia público, mas não foram executados em uma conta autenticada. Exemplos originais de requisição

Os elementos em comum são input, com as evidências, e questions, com as decisões a tomar sobre elas. O campo name de cada pergunta identifica sua resposta no array answers retornado. Referência de requisição e resposta

# Predicate: inspect product.png for visible damage
IMAGE_BASE64="$(base64 < product.png | tr -d '\r\n')"

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "gpt-6-luna",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "Inspect the product in this photo."},
      {"type": "input_image", "image_url": "data:image/png;base64,$IMAGE_BASE64"}
    ]
  }],
  "questions": [{
    "type": "predicate",
    "name": "visible_damage",
    "instructions": "Does the product have visible damage, such as a crack, tear, or dent? Ignore shadows and damage to the packaging."
  }]
}
JSON

# Choice: route a customer complaint
curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "I was charged twice for my order.",
    "questions": [{
      "type": "choice",
      "name": "department",
      "instructions": "Which department should handle this complaint?",
      "choices": [
        {"value": "billing", "description": "Payments, invoices, and refunds."},
        {"value": "technical", "description": "Problems using the product."},
        {"value": "shipping", "description": "Delivery and tracking."},
        {"value": "other", "description": "Requests outside these categories."}
      ]
    }]
  }'

# Score: assess issue severity
curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "Export fails in Safari but works in Chrome.",
    "questions": [{
      "type": "score",
      "name": "severity",
      "instructions": "How severe is this issue?",
      "levels": [
        {"label": "Cosmetic", "description": "Appearance only; no lost functionality."},
        {"label": "Workaround available", "description": "A task fails, but another way works."},
        {"label": "Fully blocked", "description": "A task fails with no workaround."}
      ]
    }]
  }'

O exemplo de escolha já oferece um bom ponto de partida para o negócio: uma reclamação de cobrança duplicada precisa ir para uma das filas predefinidas. O exemplo de pontuação responde a outra pergunta: qual é o impacto de uma falha quando outro navegador ainda funciona? Separe a definição da equipe responsável da avaliação de gravidade. Assim, um problema de cobrança pode ser urgente sem virar um chamado técnico.

Trate a recusa antes de ler o valor. Os exemplos de SDK do guia verificam answer.type == "refusal" antes de acessar probability, choice ou score. Uma recusa é um resultado à parte: não equivale a uma resposta com baixa confiança nem à categoria other. Comportamento das recusas

Use a escolha para fazer a triagem de chamados

Na primeira versão, concentre-se na definição da fila. Uma equipe de suporte poderia enviar o assunto do chamado e a mensagem relevante do cliente, receber a escolha do departamento e deixar que o código convencional da aplicação aplique as regras de encaminhamento.

Parta das definições de fila do guia e substitua-as pelos limites reais de responsabilidade das suas equipes. Mantenha uma opção other para solicitações que não se encaixam nos departamentos listados. Um pedido de reembolso pertence à equipe de cobrança; isso não autoriza o reembolso.

Este pequeno adaptador ilustra as regras da aplicação após interpretar uma resposta JSON bem-sucedida e selecionar a resposta department. O parâmetro thresholds precisa conter os limites que você definiu a partir de chamados rotulados; se não houver um limite, o chamado fica para revisão.

QUEUES = {
    "billing": "billing",
    "technical": "technical",
    "shipping": "shipping",
}

def queue_for(answer, thresholds):
    if answer.get("type") == "refusal":
        return "manual_review"
    if answer.get("type") != "choice":
        return "manual_review"
    department = answer.get("choice")
    if department not in QUEUES:  # Includes the guide's "other" choice.
        return "manual_review"
    cutoff = thresholds.get(department)
    confidence = answer.get("confidence")
    if cutoff is None or confidence is None or confidence < cutoff:
        return "manual_review"
    return QUEUES[department]

No fluxo proposto, erros de API, timeouts e respostas ausentes também deixam os chamados para revisão manual. Registre a versão da pergunta, a fila sugerida, a confiança, a fila final e eventuais correções da equipe. Garanta que a atualização da fila possa ser repetida com segurança, para que uma nova tentativa da requisição não duplique a atribuição.

Perguntas independentes sobre o mesmo chamado podem ir na mesma requisição. Se uma pergunta posterior depende de uma resposta anterior para fazer sentido, ela deve ir em outra requisição. Orientações para múltiplas perguntas

Defina os limites com dados rotulados

Escolha os limites medindo quais erros seu negócio pode tolerar. A OpenAI não publica números de calibração no guia e orienta os desenvolvedores a usar dados rotulados da própria aplicação. Um valor de confiança não garante que a resposta estará correta naquela proporção nos seus chamados. Como interpretar as respostas

Comece com chamados antigos cujo destino correto tenha sido conferido por uma pessoa responsável pelo suporte. Inclua solicitações curtas, problemas misturados, falta de contexto e reclamações que contenham instruções direcionadas ao modelo. Separe os exemplos usados para ajustar perguntas e limites de um conjunto reservado exclusivamente para a comparação final.

Meça os encaminhamentos para filas erradas, a proporção enviada para revisão e o tempo que a equipe gasta corrigindo as atribuições. Avalie cada fila separadamente. Confundir entregas com cobrança pode ter um custo operacional diferente de deixar passar um relato de comprometimento de conta.

Primeiro, execute a solução candidata em paralelo ao classificador atual, sem alterar os encaminhamentos em produção. Só a adote quando os resultados atenderem a uma regra de aceitação documentada. Mantenha o caminho anterior disponível para reverter a mudança. Estas são etapas de implantação propostas, não resultados de um teste desta API.

Seis aplicações que valem um teste, em ordem de prioridade

Os melhores usos iniciais têm categorias estáveis, erros observáveis e alguém que já cuida das exceções. A ordem abaixo reflete uma avaliação de implementação, não um ranking de precisão.

Na rotulagem, defina se cada registro pode ter mais de um tema. Uma escolha única seleciona uma categoria; perguntas separadas podem ser mais adequadas quando os rótulos se sobrepõem. Para a gravidade dos incidentes, descreva o impacto em termos operacionais, como perda de funcionalidade e disponibilidade de alternativas. Palavras como “grave” deixam margem demais para a interpretação do modelo.

O que o preço muda na prática

O preço informado no guia é de $0.10 por 1M de tokens de entrada no gpt-6-luna, sem cobrança por saída, leitura ou gravação de cache. Podem ser aplicados adicionais por processamento regional e multiplicadores de entrada para contextos longos. Essas são as tarifas da Decisions; não aplique essa regra de cobrança a chamadas convencionais do mesmo modelo. Preços da Decisions

O exemplo abaixo é um cálculo para um lote, não uma medição de uso nem um preço fixo por decisão. Considere 100,000 chamadas de classificação, cada uma com 1,000 tokens de entrada sem cache, incluindo instruções e opções. Para a chamada atual à Responses, considere também um total de 50 tokens de saída faturados por chamada. O cálculo usa os preços-base padrão para contexto curto, sem gravações de cache, adicionais regionais, novas tentativas ou outras cobranças.

As tarifas convencionais do modelo vêm da tabela de preços padrão da OpenAI. Neste exemplo, eliminar a cobrança por saída economiza $2.50 no lote inteiro. Esse valor, por si só, dificilmente justifica reescrever uma integração que funciona.

O argumento mais forte é operacional: menos espera em um fluxo sequencial, menos código para tratar respostas ou menos triagem manual, mantendo a mesma taxa de erro. Compare com sua fatura real e com a carga de revisão. Um modelo atual mais caro ou respostas geradas mais longas mudam a conta; descontos de cache já existentes também. O tempo de engenharia e os chamados encaminhados incorretamente continuam fazendo parte do orçamento da migração.

Duas ideias de produto que vale a pena desenvolver

Primeira opção: encaminhamento de chamados com revisão e histórico de correções

Uma liderança de operações de suporte poderia pagar por um conector que sugere filas predefinidas, retém casos incertos e transforma as correções da equipe em dados de avaliação. O produto útil é o fluxo completo de encaminhamento, incluindo sua manutenção.

A DataForSEO estima 170 buscas mensais no Google dos EUA por “ticket triage”, em consulta feita em 11 de outubro de 2026. É um sinal restrito de demanda informacional, não uma contagem de compradores. Produtos de helpdesk existentes também atendem a essa necessidade: o Zendesk oferece classificações de triagem inteligente e exige o complemento Copilot para usá-las em fluxos de trabalho. Guia de triagem do Zendesk

A menor versão útil poderia integrar um helpdesk, importar chamados antigos, mostrar uma prévia das atribuições de fila e oferecer uma caixa de entrada para revisão com possibilidade de correção manual. A evidência de venda mais forte seria a redução dos repasses evitáveis no cliente. A dificuldade está no que a solução existente já cobre: se o helpdesk já distribui bem os chamados, outro sistema de encaminhamento aumenta a manutenção. O diferencial precisa resolver um problema específico de responsabilidade ou de repasse entre sistemas.

Segunda opção: uma ferramenta de revisão para rótulos predefinidos

Uma equipe de pesquisa ou dados poderia pagar por uma ferramenta que sugere rótulos, coleta correções e mostra quais categorias geram divergências recorrentes. A DataForSEO estima 90 buscas mensais no Google dos EUA por “automated data labeling”, na mesma consulta. Isso indica interesse na tarefa, não disposição comprovada para comprar essa implementação.

Uma primeira versão poderia receber um CSV, aplicar um conjunto versionado de rótulos, apresentar as linhas incertas para revisão e exportar os resultados corrigidos. Mantenha um conjunto de avaliação separado para comparar mudanças nos rótulos de forma justa. A dificuldade é que um modelo pode reproduzir uma taxonomia mal definida a baixo custo. O produto precisa de boas ferramentas de revisão e gestão de categorias; uma interface em torno de uma chamada de API é fácil de copiar.

O sistema de encaminhamento de chamados é a melhor opção para começar. Com equipes responsáveis por cada fila, o erro fica visível, há alguém capaz de corrigi-lo e o fluxo se repete, permitindo demonstrar valor. Converse com essa pessoa antes de criar uma plataforma genérica de decisões.

Quando manter a solução atual

Mantenha a Responses API quando precisar extrair campos para um esquema JSON próprio, obter uma explicação por escrito ou receber uma chamada de ferramenta solicitada pelo modelo, com argumentos. A Decisions atende aos tipos de resposta mais restritos descritos acima. Orientações da OpenAI para escolher a interface

Mantenha regras determinísticas quando a resposta já estiver em um campo da conta ou em uma política explícita. Um modelo acrescenta pouco a “encaminhe os clientes desta região para esta equipe”. Preserve a autorização humana e as verificações de permissão da aplicação para ações com consequências relevantes. Uma decisão de encaminhamento pode orientar um fluxo de reembolso; ela não comprova o direito do cliente nem a autoridade de quem opera o sistema.

Confira estas restrições de integração antes de agendar a migração:

• Imagens: o guia permite apenas URLs de dados em base64 incluídas diretamente na requisição, ou seja, os bytes da imagem ficam codificados no próprio envio. Pelas instruções do guia, não há suporte a URLs HTTP ou HTTPS de imagens hospedadas nem a file_id, o identificador de um arquivo enviado anteriormente. Requisitos de entrada de imagens
• Controles de dados: o guia informa suporte a Zero Data Retention, ou ZDR, e ao uso sob HIPAA para clientes elegíveis. Há suporte a residência de dados e processamento regional nos EUA e na Europa, especificamente no EEE + Suíça. Aplicam-se requisitos de elegibilidade, acordos, configurações e limitações; esses recursos não vêm automaticamente ativados nas contas. Disponibilidade da Decisions, Controles de dados da OpenAI
• Maturidade do lançamento: o beta público é motivo para manter um caminho de reversão. Se o classificador atual cumpre suas metas e a troca não traz benefício mensurável, mantenha-o.

Alternativas: Jev, Clef e Microsoft-Decision-1

Compare os candidatos com o mesmo conjunto de dados rotulados antes de trocar de fornecedor. O Jev, da TypeSafe, recebe o estado e perguntas tipadas pela System One API. O Cloudflare Clef oferece decisões tipadas no Workers AI. O Microsoft-Decision-1 está disponível no Microsoft Foundry para tarefas como classificação, encaminhamento e priorização. Guia de início rápido da TypeSafe, Documentação do Cloudflare Clef, Anúncio da Microsoft

Integrações existentes, requisitos de hospedagem, resultados de avaliação e tratamento de exceções devem orientar a seleção. Nosso guia de encaminhamento de chamados com Jev explica esse modelo de encaminhamento; O Jev Router é gratuito? esclarece a diferença entre o software de roteamento e a inferência hospedada. Trate separadamente o formato de requisição e o comportamento da confiança de cada fornecedor.

Por onde começar na segunda-feira

Escolha a chamada de classificação que encaminha chamados para um conjunto de filas já estabelecido. Peça à pessoa responsável que confira uma amostra representativa e rotulada, documente as taxas aceitáveis de erro e revisão e compare a Decisions em paralelo à chamada atual, sem alterar as atribuições. Só faça a troca depois que ela demonstrar que merece esse lugar no fluxo.

Se você precisa de um fluxo de encaminhamento integrado às ferramentas que já usa, criamos sistemas de IA para produção.