Por que os aplicativos de IA precisam de saídas estruturadas?
Aplicativos de IA precisam de saídas estruturadas porque um programa não consegue interpretar de forma confiável um parágrafo em linguagem informal; ele precisa dos mesmos campos, com os mesmos nomes e tipos, todas as vezes. Uma frase extra ou um campo ausente pode interromper a próxima etapa do seu aplicativo.
Imagine uma startup fictícia de logística com 12 pessoas, a Parcelwise. Sua desenvolvedora, Sana, está criando uma ferramenta que lê emails de clientes e preenche um formulário de alteração de entrega: referência do pedido, data solicitada, novo endereço e se o cliente está pedindo reembolso. Um email típico diz: 'Oi, pedido PW-88213, não vou estar em casa na quinta, podem entregar no sábado? Ou deixar no nº 14. Se não der, cancelem e reembolsem, por favor.' A primeira versão pede ao modelo para 'responder em JSON'. A maioria das respostas pode ser processada, mas algumas começam com 'Claro, aqui está o JSON', algumas chamam o campo de 'date' em vez de 'requested_date', e uma retorna a data como 'sábado'.
O que é um esquema JSON e por que ele ajuda?
Um esquema JSON é uma descrição formal dos dados que você espera: quais campos existem, quais são obrigatórios, qual é o tipo de cada um e quais valores são permitidos. Fornecer um esquema ao modelo transforma 'por favor, responda em JSON' em um contrato que seu código pode verificar.
Para Sana, o esquema determina: order_reference é uma cadeia de texto obrigatória; requested_date é uma cadeia de texto obrigatória em formato de data, ou null se nenhuma data tiver sido informada; new_address é uma cadeia de texto ou null; refund_requested é um valor booleano obrigatório; e nenhum outro campo é permitido. Essa última regra impede que o modelo acrescente campos de comentários.
Como as APIs de modelos permitem gerar respostas estruturadas?
As APIs dos principais modelos permitem enviar um esquema JSON junto com a solicitação, e a saída do modelo é restringida para corresponder a esse esquema.
OpenAI
O recurso de saídas estruturadas da OpenAI restringe as respostas a um esquema JSON fornecido quando o modo estrito está ativado. A documentação diferencia esse recurso do modo JSON anterior, que garante apenas um JSON válido, não a conformidade com seu esquema, e recomenda usar saídas estruturadas quando disponíveis.
Anthropic
A API do Claude oferece resultados em JSON que seguem um esquema fornecido por você, além de uma opção de validação estrita nas definições de ferramentas, para que as entradas sejam validadas de acordo com o esquema da ferramenta. A documentação informa quais recursos de esquema são aceitos e quais retornam um erro.
A API do Gemini aceita um esquema JSON para as respostas e oferece suporte a um subconjunto definido de palavras-chave do esquema. A documentação informa que, embora a saída seja um JSON sintaticamente correto, você ainda deve validar os valores na sua aplicação.
Por que você ainda precisa de validação e novas tentativas?
Você ainda precisa validar os dados porque um esquema controla sua estrutura, não se os valores estão corretos. Uma resposta perfeitamente estruturada ainda pode conter uma data errada, uma referência de pedido inventada ou uma indicação de reembolso que o cliente nunca solicitou.
Valide em duas camadas. Primeiro, confira a estrutura com uma biblioteca de validação de esquemas, como Pydantic em Python ou Zod em JavaScript, que aparecem nos exemplos das documentações da OpenAI, da Anthropic e do Google. Depois, confira as regras de negócio: a referência do pedido segue o padrão e existe no sistema, a data é futura e corresponde a um dia de entrega, e o endereço está em uma área atendida? Trate também os casos documentados pelos provedores: uma recusa, que pode não seguir seu esquema, e uma resposta interrompida pelo limite máximo de tokens, que deixa o JSON incompleto.
Tente novamente com cuidado. Se uma verificação falhar, faça uma nova tentativa incluindo o erro específico, como 'requested_date deve ser uma data; o e-mail diz sábado, e a data do pedido é 14 de outubro'. Limite as novas tentativas a uma ou duas e, depois, encaminhe o e-mail para uma pessoa.
Como é uma saída estruturada fraca e uma robusta?
Versão fraca: a instrução diz 'Extraia os detalhes e responda em JSON.' O aplicativo lê qualquer resposta que receber. Para o e-mail acima, ele recebe campos chamados order e date, uma data com o valor 'sábado' e um valor de reembolso igual a true, porque o modelo interpretou 'se não, é só cancelar' como um pedido definitivo. O formulário é preenchido incorretamente e o cliente recebe um reembolso que não queria.
Versão robusta: a solicitação inclui o esquema de Sana com o modo estrito, e o prompt explica cada campo, incluindo 'refund_requested só é true se o cliente pedir um reembolso sem condições'. O modelo retorna order_reference PW-88213, requested_date como a data do próximo sábado, new_address null, refund_requested false e conditional_request, um campo que Sana adicionou ao esquema exatamente para esse caso, definido como 'reembolsar se não for possível entregar no sábado ou a um vizinho'. A validação confirma que o pedido existe e que sábado é um dia de entrega. Como o e-mail contém uma solicitação condicional, as regras o encaminham a uma pessoa para a decisão final.
Quais são os erros comuns com saídas estruturadas?
O erro mais comum é confiar que um JSON válido contém dados corretos. Outros: depender apenas das instruções quando a API oferece validação obrigatória por esquema, usar nomes de campos vagos sem descrições, forçar um valor quando a resposta honesta é null, ignorar recusas e respostas truncadas e tentar novamente sem dizer ao modelo o que estava errado.
Onde a saída estruturada se encaixa no catálogo da Tosheo.ai?
Saída estruturada é uma aula de programação do curso de criação de aplicativos com IA, na categoria Criação de aplicativos com IA. A versão prática completa com código, em que você define um esquema, chama uma API, valida respostas e adiciona uma nova tentativa, está na trilha de programação após o cadastro, com feedback baseado em critérios de avaliação em cada etapa.