BroadRouter
Começar

JSON mode (modo JSON)

Atualizado em

JSON mode é uma configuração de APIs de LLM, response_format {"type": "json_object"} em APIs no estilo da OpenAI, que faz a resposta do modelo ser JSON válido e parseável. Ao contrário de structured outputs com JSON Schema, ele não garante quais chaves, tipos ou valores o objeto contém.

Também chamado de: modo JSON, saída em JSON, resposta em JSON, JSON mode, json_object, JSON output mode, JSON response mode

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_schema nã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.

Perguntas frequentes

JSON mode é o mesmo que structured outputs?

Não. O guia da OpenAI diz que os dois produzem JSON válido, mas só os Structured Outputs garantem a aderência ao schema. O JSON mode pode retornar qualquer objeto válido.

Por que o JSON mode dá erro por causa da palavra JSON?

A OpenAI exige a instrução de produzir JSON em algum lugar das mensagens e retorna erro se a string "JSON" não aparecer no contexto.

O JSON mode ainda pode retornar JSON quebrado?

Sim, se a resposta for cortada por max_tokens ou pelo limite de contexto. Confira o finish_reason antes do parsing.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity