---
title: "JSON mode vs JSON Schema: saída estruturada, com código"
description: "O JSON mode garante JSON válido; o json_schema garante o seu formato. Como pedir cada um em modelos compatíveis com a OpenAI, validar com Pydantic e corrigir."
url: https://broadrouter.com/pt/blog/structured-output-json-schema/
lang: pt-BR
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/blog/structured-output-json-schema/) (atualizado em 2026-11-14).

# JSON mode vs json\_schema: saída estruturada que não quebra

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em 2026-11-14

O JSON mode (response\_format json\_object) só garante JSON válido. A saída estruturada (response\_format json\_schema) garante também os seus campos e tipos, quando o provedor aplica o schema. Nos dois casos, confira o finish\_reason, faça o parse e valide contra um schema, como um modelo Pydantic. Se a validação falhar, devolva o erro e peça de novo, com um limite fixo de tentativas.

## Pontos principais

-   O guia da OpenAI: os dois modos produzem JSON válido, mas "only Structured Outputs ensure schema adherence" (tradução: só os Structured Outputs garantem a aderência ao schema).
-   O suporte varia entre provedores compatíveis com a OpenAI. Teste primeiro o json\_schema, depois recorra ao json\_object e, por fim, só ao prompt.
-   Valide toda resposta. Uma resposta cortada por max\_tokens é JSON quebrado, diga o schema o que disser.
-   Loops de correção funcionam quando você devolve o erro de validação exato. Limite-os a duas ou três tentativas.
-   Na BroadNet Inference, o GLM 5.3 e o Qwen3.8 27B listam suporte a saída estruturada.

**Nesta página**

1.  Qual é a diferença entre JSON mode e json\_schema?
2.  Como pedir json\_schema?
3.  Qual modo o seu provedor suporta?
4.  Como validar e corrigir uma saída ruim?
5.  Quais recursos de schema dão problema?
6.  Como monitorar a saída estruturada em produção?
7.  Quando usar uma ferramenta em vez disso?
8.  Onde a BroadNet Inference se encaixa

O seu código precisa de dados, e os modelos escrevem texto. A [saída estruturada](https://broadrouter.com/pt/glossary/structured-output/) fecha essa lacuna, mas “o modelo devolve JSON” pode significar três coisas diferentes, dependendo de como você pede. Este post compara as opções em modelos abertos compatíveis com a OpenAI, mostra como pedir cada uma e traz um loop de validação e correção que você pode colocar em produção.

## Qual é a diferença entre JSON mode e json\_schema?

| Método | Requisição | O que é garantido |
| --- | --- | --- |
| Só o prompt | “Responda em JSON com os campos…” | Nada; normalmente JSON, às vezes com texto extra |
| JSON mode | `response_format: {"type": "json_object"}` | JSON válido, em qualquer formato |
| Saída estruturada | `response_format: {"type": "json_schema", ...}` | JSON que segue o seu schema, quando aplicado |

O guia de Structured Outputs da OpenAI é direto: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (tradução: embora os dois garantam que seja produzido JSON válido, só os Structured Outputs garantem a aderência ao schema). Ele recomenda a saída estruturada em vez do JSON mode sempre que possível.

Em provedores de modelos abertos, a garantia depende de como o servidor a implementa. Muitos usam constrained decoding, que bloqueia os tokens que quebrariam o schema. Alguns aceitam o campo, mas não o aplicam. Por isso o código abaixo valida de qualquer jeito.

## Como pedir json\_schema?

```python
import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}
```

O Pydantic gera o JSON Schema a partir da sua classe, então o schema e o validador nunca se desencontram. Se você não usa Pydantic, o [gerador de JSON Schema](https://broadrouter.com/tools/json-schema-generator/) cria um schema em strict mode a partir de um objeto de exemplo. No strict mode, a OpenAI exige `additionalProperties: false` e todas as propriedades listadas como obrigatórias.

## Qual modo o seu provedor suporta?

Rode este teste uma vez por modelo antes de construir em cima dele:

1.  Envie `json_schema` com um prompt que convide a acrescentar um campo extra (“adicione também um comentário curto”).
2.  Se a requisição der erro, o provedor não aceita `json_schema`. Tente `json_object`.
3.  Se a resposta tiver o campo extra, o schema não está sendo aplicado. Trate como JSON mode.
4.  Se `json_object` também der erro, use só o prompt, com validação.

Na BroadNet Inference, a documentação lista saída estruturada para o [GLM 5.3](https://broadrouter.com/pt/models/glm-5.3/) e o [Qwen3.8 27B](https://broadrouter.com/pt/models/qwen3.8-27b/) ([comparados lado a lado](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)), mas não informa o parâmetro da requisição. Rode o teste acima no modelo que você vai colocar em produção.

## Como validar e corrigir uma saída ruim?

```python
import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")
```

O que faz este loop funcionar:

-   **Confira o `finish_reason` primeiro.** Uma resposta que bateu em [`max_tokens`](https://broadrouter.com/pt/glossary/max-tokens/) é JSON truncado. Tentar de novo com o mesmo limite falha do mesmo jeito. Os dois modelos citados acima raciocinam antes de responder, e [o raciocínio conta para o limite](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/), então deixe folga.
-   **Trate recusas à parte.** O guia da OpenAI observa que uma recusa “does not necessarily follow the schema you have supplied” (tradução: não segue necessariamente o schema que você forneceu).
-   **Devolva o erro exato.** Uma nova tentativa às cegas costuma repetir o mesmo erro. “line\_items: field required” dá ao modelo algo para corrigir.
-   **Verifique regras de negócio no código.** Um schema não consegue dizer que um total deve ser igual à soma dos itens. A verificação acima consegue.
-   **Limite as tentativas.** Cada tentativa reenvia o prompt inteiro como [tokens de entrada](https://broadrouter.com/pt/glossary/input-and-output-tokens/).

## Quais recursos de schema dão problema?

Mantenha os schemas sem graça:

1.  **Plano é melhor que aninhado.** Dois níveis bastam para a maioria das extrações.
2.  **Enums em vez de strings livres** para categorias.
3.  **Nada de objetos abertos.** Campos `dict` de formato livre anulam o propósito.
4.  **Nomes de campo curtos, com descrições.** As descrições no schema orientam o modelo.
5.  **Campos opcionais como nullable.** No strict mode, liste todo campo como obrigatório e permita `null`.

O guia da OpenAI observa que alguns recursos do JSON Schema não são suportados no strict mode. Servidores de modelos abertos têm os próprios limites. Se um schema for rejeitado, simplifique-o antes de trocar de modo.

## Como monitorar a saída estruturada em produção?

Um loop que corrige em silêncio pode esconder um problema que custa tokens todos os dias. Registre três números por ponto de chamada:

| Métrica | O que ela mostra |
| --- | --- |
| Taxa de sucesso na primeira tentativa | Quão bem modelo e schema combinam; uma queda costuma vir depois de uma mudança de prompt ou de modelo |
| Média de tentativas por sucesso | O custo em tokens das correções |
| Falhas finais | Entradas que o seu pipeline não consegue tratar; revise-as à mão |

Se o sucesso na primeira tentativa cair abaixo do habitual, simplifique o schema ou teste outro modelo antes de acrescentar mais tentativas. Guarde uma amostra das respostas brutas que falharam, para testar as correções em casos reais.

## Quando usar uma ferramenta em vez disso?

Use saída estruturada para a **resposta final**: uma extração, uma classificação, um plano. Use [tool calling](https://broadrouter.com/pt/blog/tool-calling-open-models/) quando o modelo precisa que o seu código **faça** algo e depois continue. Muitos agentes usam os dois: ferramentas durante o loop e um schema no último passo. Para um exemplo de imagem para JSON, veja [ler notas fiscais em árabe com um modelo de visão](https://broadrouter.com/pt/guides/read-arabic-invoices-with-vision/).

## Onde a BroadNet Inference se encaixa

A BroadNet Inference lista saída estruturada para o GLM 5.3 e o Qwen3.8 27B, no formato padrão de chat completions, então o código acima roda sem mudanças com o [SDK Python da OpenAI](https://broadrouter.com/pt/guides/openai-python-sdk/). O Qwen3.8 27B também aceita imagens, o que combina com extração de documentos. A documentação da BroadNet não informa saída estruturada para o DeepSeek V4.1 Flash nem para o Gemma 4 VL 26B, então use nesses modelos o caminho só com prompt e validação. Compare os preços por token na [página de preços](https://broadrouter.com/pt/pricing/).

Ferramentas gratuitas sobre o tema (em inglês)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Ferramentas gratuitas (em inglês)](https://broadrouter.com/tools/)

## Termos neste artigo

[Saída estruturada (structured output)](https://broadrouter.com/pt/glossary/structured-output/)

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.

[Token](https://broadrouter.com/pt/glossary/token/)

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[JSON Schema](https://broadrouter.com/pt/glossary/json-schema/)

JSON Schema é um vocabulário, escrito em JSON, para descrever e validar a estrutura de dados JSON: tipos, campos obrigatórios, valores permitidos e aninhamento. A versão atual é a 2020-12. APIs de LLM o usam para definir parâmetros de tools e o formato exato que uma saída estruturada deve seguir.

[JSON mode (modo JSON)](https://broadrouter.com/pt/glossary/json-mode/)

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.

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Chat Completions API](https://broadrouter.com/pt/glossary/chat-completions-api/)

A Chat Completions API é o endpoint HTTP da OpenAI, POST /v1/chat/completions, que recebe o nome de um modelo e uma lista de mensagens marcadas com papéis e devolve a próxima mensagem do modelo. O formato da requisição e da resposta virou o padrão comum que provedores e SDKs compatíveis com a OpenAI reutilizam.

[Modelo de visão e linguagem (VLM)](https://broadrouter.com/pt/glossary/vision-language-model/)

Um modelo de visão e linguagem (VLM, vision-language model) é um modelo que recebe imagens e texto juntos como entrada e produz texto, então consegue descrever fotos, responder perguntas sobre elas e ler documentos, gráficos ou capturas de tela. VLMs também são chamados de modelos image-text-to-text ou multimodais.

[Tokens de entrada e de saída](https://broadrouter.com/pt/glossary/input-and-output-tokens/)

Tokens de entrada são os tokens que um modelo de linguagem lê em uma requisição, incluindo o system prompt, o histórico da conversa, as definições de ferramentas e as imagens. Tokens de saída são os que ele gera na resposta, incluindo o raciocínio. As APIs de LLM costumam cobrá-los separadamente, e a saída costuma custar mais.

## Perguntas frequentes

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

O JSON mode, response\_format do tipo json\_object, só garante que a resposta seja um JSON válido. A saída estruturada, do tipo json\_schema, garante também os campos e tipos que você definiu, quando o provedor aplica o schema. A OpenAI recomenda a saída estruturada em vez do JSON mode sempre que possível.

### Modelos abertos suportam response\_format json\_schema?

Depende do provedor. Alguns aceitam json\_schema, outros só json\_object, e alguns ignoram o campo. Envie uma requisição de teste com um schema e um prompt que tente o modelo a acrescentar um campo extra, e depois confira a resposta.

### Ainda preciso validar a saída estruturada?

Sim. Respostas podem ser cortadas por max\_tokens, podem ser recusas e podem violar regras de negócio que um schema não consegue expressar, como totais que precisam bater.

### Quantas vezes devo tentar de novo quando o JSON é inválido?

Duas ou três tentativas com o erro de validação incluído costumam bastar. Depois disso, registre a entrada e encaminhe para um fallback, um modelo mais forte ou uma pessoa. Loops sem limite desperdiçam tokens.

### Devo usar saída estruturada ou tool calling?

Use saída estruturada quando você quer a resposta final num formato fixo. Use tool calling quando o modelo precisa que o seu código faça algo e depois continue.

## Continue lendo

-   [Classificação de texto em árabe com LLM: sentimento, intenção, triagem](https://broadrouter.com/pt/blog/arabic-text-classification-llm/)
-   [Tool calling com modelos abertos: schemas, chamadas paralelas, retry](https://broadrouter.com/pt/blog/tool-calling-open-models/)
-   [Migrar para uma API compatível com a OpenAI: checklist de migração](https://broadrouter.com/pt/blog/openai-compatible-api-migration-checklist/)
-   [AI Agent do n8n num LLM barato: setup, modelo e custo por execução](https://broadrouter.com/pt/blog/n8n-ai-agent-cheap-llm/)
-   [Como corrigir JSON inválido de um LLM: causas, reparo e retry](https://broadrouter.com/pt/blog/fix-invalid-json-from-llm/)
-   [Extrair entidades nomeadas em árabe com LLM: JSON, datas e checagens](https://broadrouter.com/pt/blog/arabic-named-entity-extraction-llm/)
-   [Hardware de GPU e serving da BroadNet, segundo a própria BroadNet](https://broadrouter.com/pt/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache de respostas de LLM para cortar custo: um cache exato em Python](https://broadrouter.com/pt/blog/cache-llm-responses-cut-cost/)
-   [Guia: Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)
-   [Guia: Ler notas fiscais e recibos em árabe com um modelo de visão](https://broadrouter.com/pt/guides/read-arabic-invoices-with-vision/)
-   [Guia: Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-structured-output-json-schema&utm_content=page-cta) ·

**Fontes**

-   [OpenAI, guia de Structured Outputs (conferido em 2026-11-14)](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [Referência da API da OpenAI, criar chat completion (response\_format)](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [Documentação do Pydantic, JSON Schema e validação](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [Referência da API da BroadNet Inference, modelos (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-structured-output-json-schema&utm_content=sources#models)
