BroadRouter
Começar

Saída estruturada (structured output)

Atualizado em

Saída estruturada é um recurso de APIs de LLM que restringe a resposta de um modelo a um formato definido pelo desenvolvedor, normalmente um JSON Schema, para que o código consiga interpretá-la de forma confiável. É mais rigorosa que o JSON mode, que garante um JSON válido, mas não uma estrutura específica.

Também chamado de: saída estruturada, saídas estruturadas, saída em JSON, structured output, structured outputs, JSON schema output, response_format

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 em required, ao usar o modo strict.
  • Não conferir finish_reason antes do parsing.

Perguntas frequentes

Qual é a diferença entre JSON mode e saída estruturada?

O JSON mode só promete que a resposta pode ser interpretada como JSON. A saída estruturada com um schema também promete os campos, os tipos e as chaves obrigatórias que você definiu. O guia da OpenAI diz que só os Structured Outputs garantem a aderência ao schema.

Ainda preciso validar a saída?

Sim. A resposta ainda pode ser uma recusa ou ser cortada por max_tokens, e um schema não consegue expressar todas as regras de negócio, como um total que precisa ser igual à soma dos itens.

Uso saída estruturada ou chamada de ferramentas?

Use saída estruturada quando quiser a resposta final em um formato fixo. Use chamada de ferramentas (tool calling) quando o modelo precisar pedir ao seu código para fazer algo e depois continuar.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity