BroadRouter
Começar

JSON mode vs json_schema: saída estruturada que não quebra

Pela equipe da BroadNet Inference · 4 min de leitura · Publicado em

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.

O seu código precisa de dados, e os modelos escrevem texto. A saída estruturada 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?

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 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 e o Qwen3.8 27B (comparados lado a lado), 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?

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 é 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, 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.

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 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.

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. 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.

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.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity