Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Limitações do Modo JSON e Gestão de Erros

Aula 6 de 12 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Válido Não Significa Correto
  2. Sem Garantias de Esquema
  3. Validação Obrigatória no Lado do Cliente
  4. Três Falhas Que Vai Encontrar
  5. Nova Tentativa com Feedback
  6. O Sinal Para Mudar de Abordagem
  7. Pontos-chave

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_reason para 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