Código precisa de entradas previsíveis. A saída estruturada transforma o texto livre de um modelo em dados em que o seu programa pode confiar.
Como funciona
Há três níveis de controle:
| Método | O que você recebe |
|---|---|
| Pedir no prompt | Normalmente JSON, às vezes com texto extra ou campos faltando |
| JSON mode | JSON válido, em qualquer formato |
| Saída estruturada com schema | JSON que segue o seu schema |
No formato da OpenAI, o JSON mode é response_format: {"type": "json_object"}. A saída estruturada passa um schema:
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "invoice",
"strict": true,
"schema": {
"type": "object",
"properties": {
"vendor": { "type": "string" },
"total": { "type": "number" }
},
"required": ["vendor", "total"],
"additionalProperties": false
}
}
}
A referência da OpenAI diz que o tipo json_schema “ensures the model will match your supplied JSON schema” (tradução: garante que o modelo vai seguir o JSON Schema fornecido). Muitos provedores fazem isso com decodificação restrita: limitam quais tokens o modelo pode produzir a cada passo, de modo que uma saída que quebre o schema não possa ser gerada.
Por que importa
- Menos erros de parsing. Pipelines de extração, classificadores e agentes podem ler os campos diretamente.
- Prompts mais simples. O schema substitui longas instruções de formato.
- Não é garantia total. O guia da OpenAI diz que o seu app ainda precisa lidar com recusas, respostas incompletas e erros. Uma resposta cortada por
max_tokensé um JSON quebrado, não importa o que o schema diga.
O suporte varia entre APIs compatíveis com a OpenAI. Algumas aceitam só json_schema, outras só json_object, e outras ignoram o campo. Confira antes de depender disso.
Na BroadNet Inference
A documentação da BroadNet lista saída estruturada para o GLM 5.3 e o Qwen3.8 27B. A documentação não cita o parâmetro da requisição, então teste response_format no seu modelo e, de qualquer forma, mantenha um parser de JSON com tratamento de erros. O validador de saída JSON de LLM mostra onde uma resposta quebra e a confere com o seu schema. Os dois modelos raciocinam antes, então deixe espaço em max_tokens para o raciocínio mais o JSON.
A saída estruturada combina bem com modelos de visão. O guia de notas fiscais em árabe envia uma imagem e pede os campos em JSON. Para ações em vez de respostas, use chamada de ferramentas.
Erros comuns
- Esquecer
additionalProperties: false, ou não listar todos os campos emrequired, ao usar o modo strict. - Não conferir
finish_reasonantes do parsing.