JSON Toolkit

O JSON do LLM veio truncado: olhe o motivo de parada antes de falar em reparo

Resumo: O modelo devolve um JSON que termina no meio do valor e o parser só informa uma coluna. Fechar as chaves faz voltar a analisar, mas cada campo faltante fica escondido nos dados. O artigo traça a fronteira entre o que um reparo de truncamento pode recuperar com honestidade e o que precisa ser reenviado: gate por stop_reason, dimensionamento do limite e ordem dos campos do schema.

Prático~5 min de leituraPublicado em 2026-11-14Atualizado em 2026-11-14
Fechamento por pilha de um JSON truncado após varredura ciente de strings

Truncamento não é erro de sintaxe, é dado faltando. Sintaxe se repara; truncamento só se recupera em parte. No instante em que uma ferramenta fecha a lacuna, o resto da lacuna deixa de ser erro de parse e passa a ser algo que ninguém vê.

Como o truncamento aparece: um número de coluna não basta

O modelo escreve JSON conforme o schema, bate no limite de saída e o texto acaba. Passe isto para o módulo json do Python 3.11:

{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"

json.loads levanta Expecting ':' delimiter, col 94. A coluna aponta a chave "qty" sem valor, mas a causa real é o documento não ter fim. Fechá-lo com uma regex gulosa mais "} falha no parse; um fechamento por pilha ciente de strings (seção seis) analisa, mas items fica com 2 registros e o terceiro parcial é descartado. O número de coluna diz onde o texto parou. Nunca diz quanto se perdeu.

Essa é a primeira diferença real em relação a um erro JSON comum. Uma vírgula final tem estado final bem definido: remova e o documento está inteiro. Truncamento não tem esse estado final. Repare e continua um fragmento.

Truncamento não é dano de sintaxe: o ponto cego dos reparadores

Reparadores como o jsonrepair existem para transformar JSON quebrado em JSON legal: tirar cercas markdown, vírgulas finais, converter aspas simples. Ali a intenção está intacta e o reparo é limpeza. Uma entrada truncada parece o mesmo JSON quebrado para a mesma ferramenta, que fecha a string, o array e o objeto abertos e devolve algo analisável. De 83 relatórios Claude truncados, a ferramenta "consertou" 79, só 4 falharam de fato. O monitoramento via uma taxa vinte vezes menor que a realidade.

Como era a saída reparada? O feedback da questão 6 parava no meio da frase, as questões 7 a 9 não existiam, o array next_steps tinha sumido. O Pydantic validou de qualquer forma, porque next_steps tinha padrão [] e a lista não tinha limite de tamanho. Cada camada fez seu trabalho. O produto entregou um relatório confiante e errado.

Coloque reparo de sintaxe num caminho de truncamento e ele desliza em silêncio da limpeza para a fabricação. A fronteira vem primeiro: um reparador só deve tratar sujeira de formato de respostas completas; uma resposta cortada nunca deve chegar até ele. Para sujeira de formato, veja o guia de reparo de JSON.

O primeiro passo é sempre o motivo de parada

Toda API grande informa por que a geração parou, nos metadados e de graça. É também a linha de código mais ignorada nas integrações de LLM. A Anthropic expõe stop_reason, a API de chat da OpenAI expõe finish_reason: max_tokens significa truncado, end_turn ou stop significa que o modelo terminou sozinho.

resp = client.messages.create(model=MODEL, max_tokens=4096, ...)
if resp.stop_reason != "end_turn":
    raise TruncatedOutput(
        f"stop_reason={resp.stop_reason}, "
        f"output_tokens={resp.usage.output_tokens}"
    )
data = json.loads(resp.content[0].text)

Com truncamento virando exceção explícita, o retry tem gatilho e o monitoramento tem fonte de alerta. Os 83 relatórios foram achados depois com uma consulta ao campo stop_reason em logs que sempre existiram e nunca eram lidos. O Gemini sinaliza length e incomplete no mesmo espírito; ao adicionar um fornecedor novo, confira a tabela de correspondência em vez de supor.

max_tokens é grade de proteção, não orçamento

A causa direta costuma ser um limite dimensionado para uma versão anterior do produto: 1500 tokens que cortam 39% dos relatórios longos assim que sessões longas entram. Aumentar o limite é gratuito. A cobrança segue os tokens realmente gerados, então 4096 num relatório de 1100 tokens custa exatamente o mesmo que 1500. O limite serve para barrar geração descontrolada, não para economizar.

Dimensione com dados: observe uma semana de distribuição real, pegue o p99, deixe folga. A equipe do incidente escolheu 4096 porque o p99 pós-correção era 2350. O outro caminho é encolher a própria saída. Chaves repetidas em arrays homogêneos consomem a maior parte dos tokens; trocar por codificação tabular antes da chamada (veja o guia do formato TOON) reduz o volume que precisa caber no limite.

A ordem dos campos define o que será cortado

Modelos escrevem JSON de cima para baixo. Quando o orçamento acaba, o que está no fim da lista some primeiro. Um schema na ordem summary, per_question_feedback, scores, next_steps perde primeiro os scores — justamente o que o usuário captura e compara toda semana. A correção é reordenar: campos curtos e críticos na frente, detalhes longos e regeneráveis depois, texto livre no fim.

O comportamento dos fornecedores também muda a consequência do mesmo truncamento:

Fornecedor Mecanismo de saída estruturada Comportamento ao truncar
OpenAI response_format com strict: true Garantia na amostragem, dialeto mais estreito; costuma recusar a geração
Anthropic input_schema em tool use Sem garantia no decode; pode devolver chaves não fechadas
Gemini responseSchema com MIME JSON No decode só enum e tipo são impostos; truncamento continua possível

"Saída estruturada ligada, validação dispensada" é ilusão. Quanto mais solta a garantia do fornecedor, mais você precisa da sua validação de schema e de um laço de retry. Como montar esse teste de contrato está em teste de contrato com JSON Schema.

Quando a recuperação parcial é realmente necessária: fechamento por pilha ciente de strings

Alguns casos obrigam a tirar algo do fragmento: pré-visualização em streaming, resposta degradada, fila de revisão humana. Aí o fechamento é o último degrau da escada de reparo e precisa de duas condições. Primeiro, a varredura de chaves deve ser ciente de strings: acompanhe estado de aspas e escapes caractere a caractere, senão um { dentro de um valor estraga a pilha. Segundo, apague pares chave-valor incompletos antes de fechar. Uma chave "qty" sem valor não vira {"qty"}; o par inteiro tem de sair.

def close_truncated(s: str) -> str:
    # 1) Varredura ciente de strings, feche a string aberta
    out, in_str, esc = [], False, False
    for ch in s:
        out.append(ch)
        if esc: esc = False; continue
        if ch == '\\' and in_str: esc = True; continue
        if ch == '"': in_str = not in_str
    text = ''.join(out) + ('"' if in_str else '')
    # 2) Remova pares parciais e dois-pontos ou vírgula pendentes
    text = re.sub(r',\s*"[^"]*"\s*$', '', text)
    text = re.sub(r'[{,]\s*"[^"]*"\s*:\s*$', '}', text)
    text = re.sub(r':\s*$', '', text)
    text = re.sub(r',\s*$', '', text)
    # 3) Revarra a pilha e feche em LIFO
    stack, in_str, esc = [], False, False
    for ch in text:
        if esc: esc = False; continue
        if ch == '\\' and in_str: esc = True; continue
        if ch == '"': in_str = not in_str; continue
        if not in_str:
            if ch in '{[': stack.append(ch)
            elif ch in '}]' and stack: stack.pop()
    return text + ''.join('}' if c == '{' else ']' for c in reversed(stack))

Com a entrada do início, isso retorna {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]} em Python 3.11 com apenas a biblioteca padrão. Analisa, e o terceiro registro se perde. No lado de modelos locais, bibliotecas dedicadas como partial-json-parser fazem o mesmo: fechar por pilha, cortar por completude.

O essencial é divulgar. A função de fechamento deve informar em que degrau o resultado foi obtido; tudo que sai do degrau truncation é resultado parcial e precisa ser marcado: perguntar de novo o escopo faltante, repetir com limite maior ou avisar o usuário de que os dados estão incompletos. Fingir que nada aconteceu é fabricar alucinação com código determinístico.

Reparar ou repetir: uma tabela de fronteira

Forma da entrada Ação correta Por quê
Cercas, vírgulas finais, aspas simples Reparador Intenção completa, só a sintaxe suja
Cortado no meio de uma string Retry ou recuperação parcial com divulgação O valor em si falta
Cortado no meio de uma estrutura Recuperação parcial com divulgação Campos prontos sobrevivem, pares parciais saem
Analisa mas parece errado Validação de negócio Não é truncamento, mas costuma vir junto

Uma equipe financeira colocou número no custo. Notas longas eram truncadas, o fechamento gerava JSON válido, o campo total ausente assumia 0, e um sistema com 98,2% de conformidade de formato produzia cerca de 200 notas erradas por mês. Ao tratar truncamento como degradação dura e adicionar verificação de identidade (total == soma dos itens), a taxa de erro monetário caiu de 0,8% para 0,02%, enquanto a conformidade de formato só subiu para 99,1%. Três meses otimizando "conformidade de formato" miravam a métrica errada. Passar no parser não é passar no negócio.

O checklist de quatro itens: verifique o motivo de parada antes de analisar; dimensione o limite pelo p99 e não como orçamento; coloque campos críticos do schema na frente; deixe o reparador ver apenas sujeira de formato de respostas completas. Com os quatro, o truncamento volta de corrupção silenciosa a falha ruidosa e repetível.

Posso só fechar as chaves e usar o resultado

Não. Fechar garante apenas legalidade sintática; os dados continuam um fragmento com frase pela metade, registros finais perdidos e valores padrão no lugar dos reais. Marque como parcial, dispare retry ou degradação e registre a taxa de recuperação.

Como diferenciar truncamento de um erro de sintaxe real

Leia o motivo de parada nos metadados: max_tokens, length ou incomplete é truncamento; end_turn ou stop com falha de parse é dano de sintaxe. Sem metadados, olhe o fim: cortado dentro de aspas ou chaves com a estrutura externa aberta quase sempre é truncamento.

Por que um truncamento reparado é mais perigoso que uma falha ruidosa

O reparador otimiza "analisa", e um truncamento fechado analisa — o monitoramento fica quieto e a validação a jusante passa por causa dos padrões. Foi assim que 83 relatórios geraram só 4 erros. A ferramenta não tem noção de intenção e não sabe o que falta, então o truncamento precisa ser barrado a montante.

Aumentar max_tokens custa mais caro

Não. A cobrança segue os tokens realmente gerados; o limite é só grade de proteção. 4096 sobre 1100 tokens gerados custa exatamente como 1500. Ajuste pelo p99 real com folga e invista em impedir geração descontrolada.

Referências

Ferramentas relacionadas

Artigos relacionados

Guia de Reparo de JSON: resgatando saídas quebradas de LLM sem perder a confiança

Saídas de LLM embrulhadas em cercas de markdown, com vírgulas finais e literais Python, não sobrevivem a um parser estrito — o mesmo vale para configs editadas à mão sem aspas. Este guia traça a fronteira real entre nove classes de erros que um reparador corrige e quatro que ninguém corrige, explica por que máquinas de estados vencem regex e entrega uma cadeia de parse pronta para produção com jsonrepair e json-repair.

Intermediário~6 min de leituraAtualizado em 2026-11-08

Guia do formato TOON: aliviar o JSON antes de entregá-lo a um LLM

Ao passar um array uniforme para um modelo de linguagem em JSON, os nomes de chave repetidos e os colchetes consomem tokens. O TOON declara a estrutura uma única vez com objetos indentados e arrays tabulares, e despeja os dados linha por linha. Benchmarks oficiais mostram cerca de 40% menos tokens com maior precisão de análise. Este guia cobre a sintaxe, quando a economia se aplica, quando não vale converter e como conectar encode e decode.

Intermediário~6 min de leituraAtualizado em 2026-11-10

Testes de contrato JSON Schema: solde as regras de validação na CI

Um schema não termina quando é escrito — é ali que começa a degradação. Um erro de digitação afrouxa a validação em silêncio, uma refatoração quebra todas as fixtures. Este guia apresenta uma arquitetura viável de teste de contrato: fixtures positivos, negativos e de snapshot, lint do próprio schema, compilação única reutilizada e quatro portões de CI que transformam quebra de contrato em build vermelho.

Intermediário~8 min de leituraAtualizado em 2026-11-05