O JSON mode responde a uma pergunta: o json.loads() vai funcionar? Ele não responde à segunda: esse é o objeto que o meu código espera?
Como funciona
Na Chat Completions API você o ativa com um único campo:
{"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Return JSON with keys name and email."},
{"role": "user", "content": "Reach me at Sara, sara@example.com"}]}
A referência da API da OpenAI o chama de “the older JSON mode, which ensures the message the model generates is valid JSON” (tradução: o JSON mode mais antigo, que garante que a mensagem gerada pelo modelo seja JSON válido). Ele vem com duas regras. Você precisa pedir JSON em uma mensagem: o guia da OpenAI diz que a API “will throw an error if the string ‘JSON’ does not appear somewhere in the context” (tradução: vai gerar um erro se a string ‘JSON’ não aparecer em algum lugar do contexto). E o formato fica a cargo do modelo. O guia afirma que o JSON mode “will not guarantee the output matches any specific schema” (tradução: não garante que a saída corresponda a nenhum schema específico).
A saída estruturada é a opção mais rígida. Ela passa um JSON Schema com {"type": "json_schema", ...}, e o modelo fica restrito a ele.
JSON mode (json_object) |
Structured outputs (json_schema) |
|
|---|---|---|
| JSON válido | sim | sim |
| Chaves e tipos obrigatórios | não | sim |
| Você fornece um schema | não | sim |
| Precisa citar “JSON” no prompt | sim (OpenAI) | não |
A OpenAI recomenda “always using Structured Outputs instead of JSON mode when possible” (tradução: sempre usar Structured Outputs em vez de JSON mode quando possível).
Por que isso importa
- A validação continua sendo sua. Com o JSON mode, uma chave faltando ou um número enviado como string passam no parsing e falham mais adiante. Valide contra um schema no código.
- Truncamento. Se a resposta atingir
max_tokens, o JSON fica incompleto. Modelos de raciocínio estão mais expostos, já que o raciocínio usa o mesmo orçamento. - Alternativa. O guia da OpenAI indica o JSON mode em modelos mais antigos em que
json_schemanão está disponível. O suporte varia por provedor e modelo, então JSON mode mais a sua própria validação é a alternativa quando um schema não é aceito.
Na BroadNet Inference
A referência da API da BroadNet lista saída estruturada para GLM 5.3 e Qwen3.8 27B. Ela não diz se o response_format suportado é json_object ou json_schema, nem se o DeepSeek V4.1 Flash e o BroadNet Gemma 4 VL 26B aceitam algum dos dois. Teste ambos no seu modelo. Para escrever o schema, use o gerador de JSON Schema. O post JSON mode vs json_schema cobre reparo e monitoramento, e o guia de faturas mostra a extração de JSON a partir de imagens.