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.

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.