Limitações do Modo JSON e Gestão de Erros
Nesta página
Válido Não Significa Correto
O Modo JSON garante JSON sintaticamente válido, não JSON semanticamente correto. Esta distinção pode parecer subtil durante o desenvolvimento, mas torna-se crítica em produção. Um JSON que é analisado sem erros, mas que contém chaves inesperadas, cria exatamente o tipo de erro que leva dias a detetar, pois nenhuma exceção é acionada no momento exato em que o problema ocorre.
Sem Garantias de Esquema
O mecanismo nada sabe sobre o seu esquema: nunca viu a estrutura que o seu código espera. O modelo pode omitir um campo necessário, adicionar um que não pediu, renomear uma chave — firstName em vez de first_name — ou alterar um tipo, devolvendo "42" como uma cadeia de caracteres quando esperava o número 42. Nada disto constitui JSON inválido.
# Espera isto:
# {"name": "Alice", "age": 30, "city": "Paris"}
# Mas pode receber:
# {"nom": "Alice", "âge": "trente ans", "ville": "Paris", "pays": "France"}
O JSON é válido, mas a estrutura não corresponde ao que o seu código espera. Esta é a diferença fundamental face às Saídas Estruturadas Personalizadas.
Validação Obrigatória no Lado do Cliente
Uma vez que o esquema não é garantido, a validação recai sobre si. O padrão mínimo executa três ações por ordem: tenta a análise, verifica se a raiz é um objeto (e não uma lista ou escalar) e, por fim, verifica a presença das chaves obrigatórias. Cada falha levanta um ValueError com uma mensagem que pode utilizar nos seus registos.
import json
from typing import Optional
def parse_and_validate(raw_content: str, required_keys: list[str]) -> dict:
"""Analisa o JSON e verifica as chaves obrigatórias."""
try:
data = json.loads(raw_content)
except json.JSONDecodeError as e:
raise ValueError(f"JSON inválido: {e}")
if not isinstance(data, dict):
raise ValueError(f"Esperado objeto JSON, recebido {type(data).__name__}")
missing = [k for k in required_keys if k not in data]
if missing:
raise ValueError(f"Chaves em falta: {missing}")
return data
# Utilização
try:
result = parse_and_validate(
response.choices[0].message.content,
required_keys=["name", "category", "priority"]
)
process_ticket(result)
except ValueError as e:
log_error(f"Saída inválida: {e}")
fallback_processing(raw_content)
A versão em TypeScript vai um passo além, verificando, para além da presença das chaves, se a categoria devolvida pertence à lista de valores permitidos. Esta é a verificação que falta com mais frequência e a que impede que um ticket classificado como "urgent_billing" passe silenciosamente pelo seu sistema de encaminhamento.
interface TicketClassification {
category: string;
priority: string;
sentiment: string;
summary: string;
}
function validateTicket(raw: string): TicketClassification {
const data = JSON.parse(raw);
const requiredKeys = ["category", "priority", "sentiment", "summary"];
const missing = requiredKeys.filter((k) => !(k in data));
if (missing.length > 0) {
throw new Error(`Chaves em falta: ${missing.join(", ")}`);
}
const validCategories = ["billing", "account", "technical", "feature_request", "other"];
if (!validCategories.includes(data.category)) {
throw new Error(`Categoria inválida: ${data.category}`);
}
return data as TicketClassification;
}
Três Falhas Que Vai Encontrar
A primeira é o JSON truncado. Se a resposta atingir o limite de max_tokens, será cortada a meio e tornar-se-á inválida — a chave de fecho nunca chega. Pode detetar o sintoma antes mesmo de analisar: finish_reason é igual a "length" em vez de "stop".
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
response_format={"type": "json_object"},
max_tokens=50 # Demasiado pequeno para um JSON completo
)
# response.choices[0].finish_reason será "length" em vez de "stop"
if response.choices[0].finish_reason == "length":
print("Aviso: Resposta truncada, aumente max_tokens")
Verifique sempre finish_reason: se for igual a "length", a resposta está incompleta, independentemente do que o resto do conteúdo indique.
A segunda falha diz respeito aos tipos. Uma idade pode chegar como uma cadeia de caracteres, um preço como um inteiro quando espera um float. Em vez de confiar na saída, envolva o acesso numa função auxiliar que tente a conversão e recorra a um valor padrão em caso de falha.
def safe_get_int(data: dict, key: str, default: int = 0) -> int:
"""Extrai um inteiro, com conversão se necessário."""
value = data.get(key)
if value is None:
return default
if isinstance(value, int):
return value
if isinstance(value, float):
return int(value)
if isinstance(value, str):
try:
return int(value)
except ValueError:
return default
return default
# Utilização
age = safe_get_int(data, "age", default=0)
A terceira é a renomeação de chaves. Com um prompt em francês, o modelo pode facilmente trocar phone por telephone, ou name por nom. Um mapeamento de sinónimos absorve estas variações sem o obrigar a repetir a chamada.
def normalize_keys(data: dict, key_mapping: dict) -> dict:
"""Normaliza as chaves usando um mapeamento de sinónimos."""
normalized = {}
for standard_key, aliases in key_mapping.items():
for alias in aliases:
if alias in data:
normalized[standard_key] = data[alias]
break
return normalized
# Mapeamento de sinónimos
mapping = {
"name": ["name", "nom", "full_name", "fullName"],
"email": ["email", "mail", "e-mail", "emailAddress"],
"phone": ["phone", "telephone", "tel", "phoneNumber"],
}
normalized = normalize_keys(raw_data, mapping)
Nova Tentativa com Feedback
Quando a validação falha apesar dos seus melhores esforços, a melhor resposta não é repetir exatamente a mesma chamada: é informar o modelo sobre o que correu mal. Ao reintroduzir a sua própria resposta na conversa, juntamente com a mensagem de erro, fornece-lhe o contexto necessário para se autocorrigir, geralmente na segunda tentativa.
import json
def call_with_retry(client, messages, max_retries=3):
"""Chamada com nova tentativa e feedback de erro."""
for attempt in range(max_retries):
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
response_format={"type": "json_object"},
temperature=0
)
raw = response.choices[0].message.content
try:
data = json.loads(raw)
validate_schema(data) # A sua função de validação
return data
except (json.JSONDecodeError, ValueError) as e:
if attempt < max_retries - 1:
# Adiciona feedback de erro ao contexto
messages.append({"role": "assistant", "content": raw})
messages.append({
"role": "user",
"content": f"A sua resposta é inválida: {e}. Corrija-a e devolva um JSON válido."
})
else:
raise RuntimeError(f"Falhou após {max_retries} tentativas: {e}")
O Sinal Para Mudar de Abordagem
Se se vir a escrever código de validação extensivo, isso é um forte sinal de que é altura de migrar para Saídas Estruturadas Personalizadas. Três limiares típicos confirmam isto: além de cinco campos para validar, a função de controlo torna-se mais longa do que a própria chamada; assim que os tipos se tornam complexos com listas aninhadas ou enums, a validação manual torna-se indissociável dos erros que introduz; e para qualquer pipeline de produção crítico, delegar restrições ao esquema é simplesmente mais seguro do que reconstruí-las manualmente.
Pontos-chave
- O Modo JSON garante JSON válido, não um esquema válido
- Valide sempre a saída no lado do cliente: verifique chaves obrigatórias, tipos corretos e valores dentro dos limites
- Verifique
finish_reasonpara detetar respostas truncadas - Implemente um mecanismo de nova tentativa com feedback de erro
- Se a validação se tornar complexa, migre para Saídas Estruturadas Personalizadas