Loops de reparo para saídas malformadas
Se o JSON não puder ser analisado, envie o erro de volta ao modelo e peça que ele corrija a saída.
Loops de reparo para saídas malformadas é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.
Partes desta aula ainda não foram traduzidas e aparecem em inglês.
Até os modos estritos falham às vezes
Modelos antigos, casos extremos ou provedores não estritos ocasionalmente retornam JSON malformado. Agentes robustos se recuperam pedindo ao modelo que repare sua saída.
Basic Repair Loop
from pydantic import ValidationError
import json
def call_with_repair(messages, schema, max_attempts=3):
for attempt in range(max_attempts):
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=messages,
response_format={'type': 'json_object'}
)
raw = response.choices[0].message.content
try:
return schema.model_validate_json(raw)
except (json.JSONDecodeError, ValidationError) as e:
messages.append({'role': 'assistant', 'content': raw})
messages.append({
'role': 'user',
'content': f'That output failed to validate: {e}.\nReturn ONLY valid JSON that matches the schema. No prose, no markdown fences.'
})
raise RuntimeError('Could not get valid output after repair attempts.')Por que funciona
O modelo vê a mensagem de erro e geralmente corrige o problema no turno seguinte. Adicione instruções explícitas:
- "Sem prosa"
- "Sem delimitadores de Markdown"
- "Corresponda exatamente a esta estrutura: ..."
Remover delimitadores de Markdown
Os modelos frequentemente envolvem o JSON em ```json ... ```. Remova os delimitadores antes de analisar:
import re
def extract_json(text):
m = re.search(r'```(?:json)?\s*(.*?)```', text, re.S)
if m:
return m.group(1).strip()
return text.strip()
sample = '```json\n{"name": "Alice"}\n```'
print(extract_json(sample))
Recorte a partir da primeira chave
Se houver prosa excedente, recorte da primeira { até a última } correspondente:
def find_json_slice(text):
start = text.find('{')
if start == -1:
return None
depth = 0
for i, c in enumerate(text[start:], start):
if c == '{': depth += 1
if c == '}':
depth -= 1
if depth == 0:
return text[start:i+1]
return None
sample = 'Here is your answer: {"name": "Alice", "age": 30} - hope that helps!'
print(find_json_slice(sample))
Ferramentas que fazem isso por você
- Instructor — combina Pydantic, ciclos de reparo e novas tentativas
- Outlines — saída estruturada garantida por meio de decodificação guiada
- jsonformer — imposição de JSON token a token (modelos HF)
Prompts de reparo que funcionam
Inclua a mensagem de erro específica e um breve lembrete do formato:
repair_prompt = f'''
Your previous output had this error: {error}
Fix the output. Requirements:
- Valid JSON only
- Match this schema: {json.dumps(schema)}
- No prose, no markdown fences
'''Custo dos ciclos de reparo
Cada reparo é outra chamada ao LLM. Limite as novas tentativas (2-3 são suficientes — além disso, é improvável que o modelo se recupere) e registre as taxas de reparo como métrica de qualidade.
Reparo como sinal de qualidade
Se sua taxa de reparo for > 5%, há algo errado: o prompt não está claro, o esquema é complexo demais ou o modelo é pequeno demais. Investigue.
Alternativa: decodificação restringida
Modelos de código aberto oferecem decodificação restringida por gramática — o modelo não consegue produzir uma saída inválida. Outlines, jsonformer e as gramáticas de llama.cpp fazem isso.
Alternativa: funções em vez de esquema
Forçar uma chamada de ferramenta com modo estrito é uma alternativa mais limpa ao modo JSON + reparo. Use-a sempre que o provedor oferecer suporte.
Registrando saídas inválidas
Registre toda saída reparada para que você possa analisar os padrões:
log.warning('Repaired output', extra={'raw': raw, 'error': str(e), 'attempt': attempt})Quando desistir
Se, após N tentativas de reparo, a saída ainda for inválida, retorne um erro ao usuário — não invente um fallback. Uma falha honesta é melhor que uma corrupção silenciosa.
Padrão de ciclo de reparo
Qual é o primeiro passo mais simples em um ciclo de reparo?
Recapitulação
Detecte erros de análise, anexe-os como uma mensagem de ferramenta/usuário e peça ao modelo que faça o reparo. Limite as novas tentativas. Prefira chamadas de ferramentas no modo estrito para eliminar totalmente essa necessidade.
Aprenda AI Agents com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 60
- Aulas
- 239
Perguntas Frequentes
A aula “Loops de reparo para saídas malformadas” é grátis?
Sim — o texto completo de “Loops de reparo para saídas malformadas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.
O que vou aprender em “Loops de reparo para saídas malformadas”?
Se o JSON não puder ser analisado, envie o erro de volta ao modelo e peça que ele corrija a saída. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Agents?
Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.
Quanto tempo leva a aula “Loops de reparo para saídas malformadas”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Agents?
Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Modo JSON e saídas de chamadas de ferramentas
- Validação de esquemas com Pydantic
- Loops de reparo para saídas malformadas
- Instructor / Outlines para estrutura garantida