BroadRouter

Como corrigir JSON inválido de um LLM: causas, reparo e retry

Pela equipe da BroadNet Inference · 7 min de leitura · Publicado em · Atualizado em

Confira primeiro o finish_reason: uma resposta cortada em max_tokens não pode ser reparada com segurança, então aumente o limite e reenvie. Fora isso, remova code fences e o texto em volta, decodifique o primeiro valor JSON e corrija só erros sem ambiguidade, como vírgulas finais. Valide contra um schema e, se falhar, devolva o erro exato uma ou duas vezes. Saída estruturada evita quase tudo isso onde é suportada.

Seu código chama json.loads() na resposta de um modelo e recebe JSONDecodeError: Expecting value: line 1 column 1. Ou o parse funciona, mas um campo vem como string onde você queria um número. Este post organiza as causas pelo que dá para fazer com segurança em cada uma, traz uma função Python testada que repara só os casos sem ambiguidade e mostra um loop de retry que sabe quando uma nova tentativa não vai ajudar.

A escolha entre JSON mode e json_schema está em JSON mode vs json_schema. Este post trata do que fazer com a resposta que você de fato recebeu.

Por que LLMs retornam JSON inválido?

Um modelo escreve texto um token por vez. A menos que o servidor restrinja a decodificação, nada o impede de acrescentar uma frase simpática ou de ficar sem espaço. As falhas mais comuns:

O que você vê Causa Dá para reparar no código com segurança?
```json … ``` em volta do objeto Hábito de formatação de chat Sim: remova a fence
“Here is the JSON:” antes, “Let me know…” depois Mesmo hábito Sim: leia só o primeiro valor
<think>...</think> antes do objeto Texto de raciocínio no campo content em alguns servidores Sim: remova o bloco
Termina no meio de uma string, colchetes abertos Atingiu max_tokens Não: reenvie com mais espaço
Content vazio O raciocínio usou todo o orçamento Não: reenvie com mais espaço
{"a": 1,} Vírgula final; JavaScript aceita, a RFC 8259 não Sim: um único significado
{'a': True, 'b': None} Sintaxe Python Sim: ast.literal_eval lê com segurança
NaN, Infinity Não é JSON; o Python aceita por padrão Não: rejeite
JSON válido, tipos errados ou campos ausentes Schema não imposto Não: peça de novo com o erro

A linha divisória é a ambiguidade. Se o modelo só poderia ter querido dizer uma coisa, corrija no código e registre que corrigiu. Se você teria que adivinhar, rejeite a resposta.

Por que não reparar JSON truncado?

Porque a versão reparada parece certa e não está. Rodamos o json_repair 0.64.9, uma biblioteca popular com licença MIT, em uma resposta cortada no meio de uma palavra:

'{"name": "Omar", "city": "Jed'  ->  {'name': 'Omar', 'city': 'Jed'}

Ele retornou JSON válido com a cidade “Jed”. O README dele é franco sobre isso: “automatically completes missing values in JSON fields with reasonable defaults” (tradução: completa automaticamente valores ausentes em campos JSON com padrões razoáveis). Isso é útil para ler logs. Para dados que você armazena ou usa para agir, transforma uma falha visível em uma falha silenciosa.

Confira o finish_reason antes do parse. "length" significa que a resposta atingiu max_tokens. Reenviar a mesma requisição com o mesmo limite falha do mesmo jeito, então dobre o limite ou peça menos por chamada. Modelos de raciocínio deixam isso mais comum: a referência da API da BroadNet diz que DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e o raciocínio conta em max_tokens. Com um limite pequeno, a resposta pode voltar vazia. Deixe 1.000 tokens ou mais, ou defina reasoning_effort como low; o post sobre orçamento de raciocínio tem os números.

Uma função de reparo que só corrige os casos seguros

Ela usa só a biblioteca padrão. Retorna o valor parseado e uma lista dos reparos feitos, para você poder contá-los.

import ast, json, re

class Truncated(Exception): pass
class NotJSON(Exception): pass

FENCE = re.compile(r"```(?:json|JSON)?\s*\n(.*?)```", re.S)
THINK = re.compile(r"<think>.*?</think>", re.S)

def _reject_constant(name):                 # NaN, Infinity: Python accepts them, JSON does not
    raise NotJSON(f"non-standard constant {name}")

_decoder = json.JSONDecoder(parse_constant=_reject_constant)

def _first_value(s):
    """Decode the first JSON object or array in s, ignoring prose before and after it."""
    for i, ch in enumerate(s):
        if ch in "{[":
            try:
                return _decoder.raw_decode(s, i)[0]
            except json.JSONDecodeError:
                continue                    # a stray brace in prose; try the next one
    raise NotJSON("no JSON object or array found")

def _scan(s):
    """Drop commas before } or ] outside strings; report brackets left open."""
    out, stack, in_str, esc = [], [], False, False
    for i, ch in enumerate(s):
        if in_str:
            if esc:
                esc = False
            elif ch == "\\":
                esc = True
            elif ch == '"':
                in_str = False
        elif ch == '"':
            in_str = True
        elif ch in "{[":
            stack.append(ch)
        elif ch in "}]" and stack:
            stack.pop()
        elif ch == ",":
            rest = s[i + 1:].lstrip()
            if rest[:1] in ("}", "]"):
                continue                    # trailing comma: skip it
        out.append(ch)
    return "".join(out), len(stack) + (1 if in_str else 0)

def _python_literal(s):
    """Output in Python syntax: single quotes, True/False/None, trailing commas."""
    start = min((i for i in (s.find("{"), s.find("[")) if i >= 0), default=-1)
    end = max(s.rfind("}"), s.rfind("]"))
    if start < 0 or end <= start:
        raise NotJSON("no braces")
    value = ast.literal_eval(s[start:end + 1])       # literals only; never runs code
    if not isinstance(value, (dict, list)):
        raise NotJSON("not an object or array")
    json.dumps(value, allow_nan=False)               # must round-trip as strict JSON
    return value

def parse_llm_json(content, finish_reason=None):
    """Return (value, repairs). Raises Truncated or NotJSON."""
    if finish_reason == "length":
        raise Truncated("hit max_tokens; raise the limit or shorten the output")
    if not content or not content.strip():
        raise NotJSON("empty content (reasoning may have used the whole budget)")
    repairs = []
    s = content.strip().lstrip("\ufeff")
    if THINK.search(s):
        s = THINK.sub("", s).strip(); repairs.append("removed <think> block")
    m = FENCE.search(s)
    if m:
        s = m.group(1).strip(); repairs.append("removed code fence")
    try:
        value = _decoder.decode(s)
        return value, repairs
    except json.JSONDecodeError:
        pass
    try:
        value = _first_value(s); repairs.append("ignored text around JSON")
        return value, repairs
    except NotJSON:
        pass
    fixed, open_count = _scan(s)
    if open_count:
        raise NotJSON(f"incomplete JSON, {open_count} bracket(s) or string left open: treat as truncated")
    if fixed != s:
        try:
            value = _first_value(fixed); repairs.append("removed trailing commas")
            return value, repairs
        except NotJSON:
            pass
    try:
        value = _python_literal(s); repairs.append("parsed Python-style literal")
        return value, repairs
    except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, NotJSON) as e:
        raise NotJSON(f"unrepairable: {e}") from None

Como cada etapa funciona:

  1. Truncamento e respostas vazias levantam exceção antes de qualquer parse, então nunca viram dados.
  2. Fences e blocos de raciocínio são removidos com duas expressões regulares.
  3. raw_decode é a ferramenta-chave. A documentação do Python diz que ele decodifica um documento “from a string that may have extraneous data at the end” (tradução: de uma string que pode ter dados estranhos no final) e retorna onde parou. Começando no primeiro { ou [, ele pula o texto antes do objeto e ignora o texto depois. Se uma chave no meio do texto não decodifica, ele tenta a próxima.
  4. A varredura de colchetes percorre o texto acompanhando strings e escapes. Colchetes que ficaram abertos significam que a resposta foi cortada mesmo que o finish_reason não diga; isso levanta exceção. Vírgulas logo antes de } ou ] fora de strings são removidas.
  5. ast.literal_eval lê saída no estilo Python com aspas simples, True e None. Ele só avalia literais e nunca executa código. O resultado depois precisa serializar como JSON estrito.
  6. NaN e Infinity levantam exceção, via parse_constant. O json do Python os aceita por padrão; a RFC 8259 diz que eles “are not permitted” (tradução: não são permitidos), e o JSON.parse do JavaScript os rejeita.

Rodamos a função em 17 strings de teste: JSON limpo, JSON em fence, chaves e valores em árabe dentro de uma fence, texto antes e depois, um placeholder {name} no texto antes do objeto, um bloco <think>, vírgulas finais em objetos e arrays, vírgulas e colchetes dentro de strings, aspas escapadas, um caminho do Windows terminando em barra invertida, literais Python, NaN, uma resposta vazia, uma resposta cortada com e sem finish_reason: "length" e dois objetos seguidos. Todas se comportaram como diz a tabela acima. Um teste pegou um bug real: uma versão inicial invertia a flag de escape antes de checar a aspa de fechamento, então "he said \"hi,]\"" perdia a vírgula. Teste o seu código de reparo com aspas escapadas.

Dois limites para conhecer. Com dois objetos seguidos, ela retorna o primeiro; se você quer vários itens, peça um único array JSON. E saída Python com aspas simples que contém aspas duplas dentro de uma string pode ser mal lida pela varredura de colchetes e rejeitada. Rejeitar é a falha segura.

Como fazer retry quando o reparo falha?

O reparo cuida do formato. A validação cuida do conteúdo: campos certos, tipos certos, valores plausíveis. Este loop valida com o pacote jsonschema e escolhe o retry pela causa:

import json, os
from jsonschema import Draft202012Validator
from openai import OpenAI
from llm_json import parse_llm_json, Truncated, NotJSON

client = OpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
                api_key=os.environ["BROADNET_API_KEY"])
SCHEMA = {"type": "object", "additionalProperties": False,
          "required": ["name", "city", "amount"],
          "properties": {"name": {"type": "string", "minLength": 1},
                         "city": {"type": ["string", "null"]},
                         "amount": {"type": "number", "minimum": 0}}}
validator = Draft202012Validator(SCHEMA)

def extract(text, model="broadnet/qwen3.8-27b", max_tokens=1500, attempts=3, log=print):
    messages = [{"role": "system", "content": "Extract name, city and amount. Reply with one JSON object only, no code fence. "
                                              "Schema: " + json.dumps(SCHEMA)},
                {"role": "user", "content": text}]
    for attempt in range(1, attempts + 1):
        r = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens,
                                           reasoning_effort="low", temperature=0)
        c = r.choices[0]
        try:
            value, repairs = parse_llm_json(c.message.content, c.finish_reason)
            errors = [f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(value)]
            if not errors:
                log({"attempt": attempt, "repairs": repairs, "ok": True})
                return value
            problem = "The JSON does not match the schema: " + "; ".join(errors)
        except Truncated:
            log({"attempt": attempt, "ok": False, "why": "truncated"})
            max_tokens *= 2                 # same prompt, more room; a re-ask would be cut off too
            continue
        except NotJSON as e:
            problem = f"That reply was not valid JSON ({e})."
        log({"attempt": attempt, "ok": False, "why": problem})
        messages += [{"role": "assistant", "content": c.message.content or ""},
                     {"role": "user", "content": problem + " Return the corrected JSON object only."}]
    raise RuntimeError(f"no valid JSON after {attempts} attempts")

As regras desse loop:

  • Truncado: reenvie as mesmas mensagens com o dobro do limite. Acrescentar uma mensagem “por favor, corrija” deixaria o prompt maior e a saída nada menor.
  • Não é JSON, ou formato errado: devolva o erro exato. “amount: ‘1200’ is not of type ‘number’” dá ao modelo algo específico para corrigir. Um retry sem explicação muitas vezes repete o erro.
  • Limite a três tentativas. Cada retry reenvia a conversa inteira como tokens de entrada. Depois de três, registre a entrada e encaminhe para outro lugar.
  • Registre a lista de reparos. Um aumento de “removed code fence” depois de uma mudança no prompt mostra que o prompt piorou, mesmo sem nenhuma falha.

Rodamos este loop contra um servidor mock local que devolvia respostas roteirizadas. Uma resposta em fence com vírgula final e "amount": "1200" como string foi reparada, falhou na validação e foi corrigida na segunda chamada com o erro devolvido. Uma resposta cortada com finish_reason: "length" foi reenviada com max_tokens aumentado de 1.500 para 3.000 e deu certo. O mock registrou cada requisição, confirmando a quantidade de mensagens e o limite que o loop enviou. Um modelo real pode falhar de outras formas, então rode com 100 entradas suas antes de confiar nos números.

Saída estruturada torna isso desnecessário?

Elimina a maior parte. Um servidor que restringe a decodificação ao seu schema não consegue emitir uma fence, uma vírgula final ou um campo ausente. O vLLM, um servidor comum de modelos abertos, faz isso com os backends xgrammar ou guidance. Mesmo assim, duas falhas continuam: truncamento em max_tokens e recusas. A OpenAI observa que a saída em JSON mode é válida “except for in some edge cases” (tradução: exceto em alguns casos extremos) e que a sua aplicação “must detect and handle” (tradução: deve detectar e tratar) saídas que não sejam um objeto completo. Então mantenha a checagem de finish_reason e o validador, mesmo com json_schema.

O que cada abordagem evita:

Abordagem Fences e texto Erros de sintaxe Formato errado Truncamento
Só prompt (“responda em JSON”) Reduz Reduz Reduz Não
JSON mode (json_object) Sim Sim Não Não
Saída estruturada (json_schema, imposta) Sim Sim Sim Não

Com JSON mode, a OpenAI também diz que você “must always instruct the model to produce JSON” (tradução: deve sempre instruir o modelo a produzir JSON) em uma mensagem; caso contrário, ele pode emitir espaços em branco até atingir o limite de tokens. Outros servidores compatíveis com a OpenAI variam, então teste o modo no modelo que você vai colocar em produção. O teste está no post sobre saída estruturada.

Para conferir uma resposta à mão, cole-a no validador de saída JSON de LLM, ou gere um schema estrito a partir de um objeto de exemplo com o gerador de JSON schema.

Onde a BroadNet Inference se encaixa

O BroadRouter é o site da BroadNet. A referência da API da BroadNet lista saída estruturada só para o GLM 5.3 e o Qwen3.8 27B, e não nomeia o parâmetro da requisição, então teste json_schema no modelo antes de depender dele. No DeepSeek V4.1 Flash e no Gemma 4 VL 26B, use JSON pedido no prompt com a função de reparo e o validador acima. Três dos quatro modelos raciocinam antes de responder, então reserve espaço em max_tokens para isso. Para extração em lote, o post sobre o batch runner mostra como registrar o finish_reason de cada item. Prompts e respostas não são retidos depois de cada requisição.

Perguntas frequentes

Por que o meu LLM retorna o JSON dentro de um bloco de código markdown?

Modelos de chat costumam formatar código para pessoas, e a code fence é como as interfaces de chat o exibem. Peça "só JSON, sem code fence", mas remova as fences no código mesmo assim: a instrução diminui a frequência, não elimina.

Como corrigir JSONDecodeError na saída de um LLM?

Olhe primeiro o finish_reason. Se for "length", a resposta foi cortada: aumente max_tokens e reenvie. Se não, remova as code fences e decodifique o primeiro valor JSON com raw_decode, que ignora o texto depois dele. Corrija vírgulas finais e valide. Se ainda falhar, peça de novo passando o erro.

Devo usar uma biblioteca de reparo de JSON?

Para logs e depuração, sim. Para dados com os quais você vai agir, cuidado. Bibliotecas como json_repair completam valores ausentes com padrões, então uma cidade truncada "Jed" volta como um "Jed" válido. Rejeite a saída truncada e reenvie.

Por que a saída JSON do meu LLM vem cortada?

A resposta atingiu max_tokens. Em modelos de raciocínio como DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B, o raciocínio conta nesse limite, então um raciocínio longo pode deixar pouco espaço. Aumente o limite, defina reasoning_effort low ou peça menos saída por chamada.

O JSON mode garante JSON válido?

Quase. A OpenAI diz que a saída em JSON mode é JSON válido "except for in some edge cases" (tradução: exceto em alguns casos extremos), como atingir o limite de tokens, e ele não impõe o seu schema. Saída estruturada com json_schema adiciona aderência ao schema onde o provedor a impõe. Valide de qualquer forma.

Quais modelos da BroadNet suportam saída estruturada?

A referência da API da BroadNet lista saída estruturada para GLM 5.3 e Qwen3.8 27B, verificado em 15 de novembro de 2026. Não lista para DeepSeek V4.1 Flash nem para Gemma 4 VL 26B, então nesses use JSON pedido no prompt com reparo e validação.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity