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:
- Envie
json_schemacom um prompt que convide a acrescentar um campo extra (“adicione também um comentário curto”). - Se a requisição der erro, o provedor não aceita
json_schema. Tentejson_object. - Se a resposta tiver o campo extra, o schema não está sendo aplicado. Trate como JSON mode.
- Se
json_objecttambé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_reasonprimeiro. Uma resposta que bateu emmax_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:
- Plano é melhor que aninhado. Dois níveis bastam para a maioria das extrações.
- Enums em vez de strings livres para categorias.
- Nada de objetos abertos. Campos
dictde formato livre anulam o propósito. - Nomes de campo curtos, com descrições. As descrições no schema orientam o modelo.
- 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.
