Pedir “responda em JSON” no prompt não cria um contrato. O modelo pode acrescentar uma frase, trocar o nome de um campo, omitir uma propriedade ou devolver um valor com tipo errado. Structured outputs reduzem esse problema ao enviar um schema junto com a requisição e pedir que a resposta siga a estrutura aceita pelo modelo.
Isso melhora a integração, mas não transforma geração em banco de dados. Um campo total pode ser número válido e ainda estar calculado errado. Uma data pode obedecer ao formato e não existir no documento. Depois de validar sintaxe e schema, a aplicação continua responsável por regras de negócio, origem e tratamento de incerteza.
Na Roteia, o contrato compatível aceita response_format nos modos de texto, objeto JSON e JSON Schema. O pedido estruturado só passa para modelos que declaram structuredOutputs no catálogo. Como laboratórios suportam subconjuntos diferentes de JSON Schema, teste o schema exato com o modelo escolhido.
Três níveis que não devem ser confundidos
O primeiro nível é texto com aparência de JSON. Ele pode funcionar em demonstração, mas não garante parse. O segundo é um modo de objeto JSON, que busca devolver sintaxe válida sem necessariamente obedecer ao conjunto de campos que seu sistema espera. O terceiro é saída estruturada com schema, onde a requisição descreve propriedades, tipos, obrigatoriedade e outras restrições suportadas.
Quanto mais forte o contrato, menos código de reparo você precisa. Ainda assim, a API pode devolver recusa, interrupção por limite, erro de validação ou falha do provedor. O consumidor precisa distinguir esses estados de uma resposta completa. Não tente consertar silenciosamente qualquer texto com expressão regular e tratá-lo como dado confiável.
Use o nível mais simples que resolve. Se a saída será exibida como texto, schema não traz benefício. Se vai alimentar uma tabela, acionar uma etapa ou ser consumida por código, estrutura explícita reduz ambiguidade e torna testes mais claros.
Desenhe um schema pequeno e sem dupla interpretação
Comece pelo consumidor. Quais campos ele realmente usa? Defina nomes estáveis, tipos e propriedades obrigatórias. Use enum para estados fechados. Quando um dado pode não existir, represente essa ausência de forma deliberada, como null quando o subconjunto suportar, em vez de permitir string vazia, “não informado” e campo ausente ao mesmo tempo.
No código consumidor, Pydantic define schemas e ajuda a validar os objetos recebidos. Isso não amplia o subconjunto aceito pelo provedor: o JSON Schema enviado na chamada ainda precisa respeitar o contrato do modelo escolhido.
Evite schemas gigantes que espelham todo o seu domínio. Eles ocupam contexto, aumentam chance de incompatibilidade e dão ao modelo decisões que deveriam ficar em código. Divida etapas: uma extração identifica os dados observados; outra regra determinística calcula imposto ou aprova operação. Não peça ao modelo para preencher campo que o documento não contém.
Descrições ajudam a desambiguar, mas não substituem validação. Explique unidade, formato e fonte esperada. Para dinheiro, prefira valor inteiro em centavos ou string decimal com regra clara; depois converta em código apropriado. Para identificadores, valide padrão e existência no sistema.
{
"model": "COLE_UM_ID_COM_JSON_DO_CATALOGO",
"messages": [{"role":"user","content":"Extraia o pedido 123, status pago."}],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "pedido",
"strict": true,
"schema": {
"type": "object",
"properties": {
"id": {"type": "string"},
"status": {"type": "string", "enum": ["aberto", "pago"]}
},
"required": ["id", "status"],
"additionalProperties": false
}
}
}
}Valide formato, domínio e evidência em camadas
Primeiro faça parse do JSON. Depois valide o schema no seu backend, mesmo que o provedor declare aderência. Isso protege troca de modelo, regressão e resposta incompleta. Em seguida, aplique regras de domínio: datas válidas, total igual à soma, status permitido naquela transição, ID pertencente ao tenant e campos coerentes entre si.
Por fim, valide evidência. Se o modelo extraiu uma cláusula, guarde o trecho ou a posição que sustenta o campo quando o caso exigir auditoria. Um resultado bem formatado sem origem é difícil de revisar. Para decisões de alto risco, use a estrutura como proposta e mantenha confirmação humana ou regra determinística.
Não use o mesmo modelo para gerar e declarar que a própria resposta está correta sem referência externa. Uma segunda chamada pode ajudar em revisão semântica, mas não substitui um cálculo, consulta ao banco ou comparação com dado de origem.
- Parse: a resposta é JSON completo?
- Schema: tipos e propriedades obedecem ao contrato?
- Domínio: valores fazem sentido juntos?
- Evidência: o dado aparece na fonte permitida?
Recusa, corte e erro não são objetos de negócio
Um modelo pode recusar uma solicitação ou terminar porque atingiu limite. A API também pode falhar antes de gerar. O cliente deve ler o estado da resposta antes de acessar o JSON. Criar um objeto padrão como {"status":"ok"} para qualquer falha é perigoso: transforma ausência de resultado em sucesso aparente.
Se a saída veio cortada, não complete chaves e campos por conta própria. Repita com contexto menor ou limite adequado, mantendo idempotência para qualquer etapa seguinte. Se o schema não é suportado, escolha outro modelo ou simplifique-o com consciência; não retire a validação apenas para fazer a chamada passar.
Registre o motivo e a versão do schema. Quando um consumidor muda, versionar evita que respostas antigas sejam lidas pelo contrato novo. Uma migração pode aceitar duas versões por um período, mas cada objeto deve indicar qual formato segue.
Structured output e tool calling resolvem problemas diferentes
Structured output formata a resposta que o seu código quer consumir: classificar lead, extrair campos ou produzir configuração. Tool calling permite que o modelo peça uma operação intermediária, como consultar estoque. No primeiro caso, o objeto é o resultado. No segundo, os argumentos são uma solicitação que o backend ainda precisa autorizar e executar.
Às vezes o fluxo usa os dois. O modelo chama uma ferramenta, recebe o resultado e depois devolve um resumo final em schema. Nem todo modelo ou provedor aceita a combinação da mesma forma. Confirme capacidade no catálogo e teste a sequência completa; sucesso isolado de cada recurso não prova que os dois funcionam juntos.
Não use tool calling apenas para obter JSON se nenhuma ferramenta será executada. Isso cria um turno conceitual falso. Da mesma forma, não use saída estruturada para representar uma ação já autorizada: o servidor precisa controlar o efeito.
Teste o contrato com casos que tentam quebrá-lo
Monte casos com campo ausente na fonte, valor ambíguo, enum desconhecido, texto malicioso, entrada longa e solicitação que deve ser recusada. Verifique parse, schema, regra de negócio e evidência separadamente. Meça também taxa de respostas interrompidas e custo; schemas grandes podem aumentar entrada.
Faça uma mutação no schema por vez. Torne um campo obrigatório, retire uma opção do enum ou proíba propriedades extras e confirme que o seu consumidor reage corretamente. Ao trocar de modelo, rode o mesmo conjunto antes de produção, mesmo quando ambos declaram structured outputs.
Na Roteia, copie do catálogo um ID com JSON estruturado declarado. A validação do gateway impede enviar json_object ou json_schema a um modelo sem a capacidade publicada. Ela não verifica os fatos do objeto nem executa suas regras de negócio; essa camada pertence à aplicação.
Dúvidas frequentes
Qual a diferença entre JSON mode e structured outputs?
JSON mode busca sintaxe JSON válida. Structured outputs acrescenta um schema para definir campos, tipos e restrições suportadas. Mesmo com schema, a aplicação deve validar valores e regras de negócio.
Um schema garante que a informação é verdadeira?
Não. Ele garante formato dentro do que o modelo e o provedor suportam. Um número pode ter o tipo correto e estar errado. Compare com a fonte, recalcule valores e valide autorização no backend.
Saída estruturada substitui chamada de ferramenta?
Não. Saída estruturada formata um resultado. Tool calling pede que a aplicação execute uma função intermediária. Um fluxo pode combinar ambos, desde que o modelo e a rota aceitem e o ciclo seja testado.
O que fazer quando o JSON vem incompleto?
Trate como falha, verifique motivo de término e não invente o restante. Ajuste contexto ou limite de saída e faça uma nova chamada quando seguro. Só entregue ao consumidor um objeto que passou por parse e validação.
Todo modelo da Roteia aceita JSON Schema?
Não. O catálogo informa structuredOutputs por modelo. A Roteia rejeita o modo estruturado quando a capacidade não está declarada, e a aplicação continua responsável por validar o conteúdo recebido.
Onde confirmar
Plataforma de terceiro muda de tela e de limite sem avisar. Confira na fonte oficial antes de tomar decisão baseada nesta página.