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

Gestão de erros e mecanismos de fallback

Aula 4 de 20 Programador
Nesta página
  1. Gestão de erros e mecanismos de fallback
  2. Devolução de erros ao modelo
  3. Nova tentativa com espera exponencial (Exponential Backoff)
  4. Timeouts por função
  5. Fallback entre funções
  6. Disjuntor (Circuit Breaker)
  7. Ciclo completo robusto
  8. Pontos-chave

Gestão de erros e mecanismos de fallback

A chamada de funções introduz um desafio que o código clássico não enfrenta: quando a sua função falha, existem dois destinatários para esse erro. A sua aplicação, como é habitual, e o modelo, que está à espera de um resultado para continuar. Esquecer isto cria o sintoma mais desconcertante em produção: uma conversa que para abruptamente sem explicação, porque uma exceção foi engolida no lado do servidor e o modelo continua à espera.

A regra que estrutura toda esta lição é: devolva sempre um function_call_output, mesmo em caso de falha. Um modelo informado de que uma API está indisponível pode propor uma alternativa, pedir esclarecimentos ou explicar a situação ao utilizador. Um modelo que não recebe nada não pode fazer nada.

Devolução de erros ao modelo

O formato do erro é tão importante quanto o seu envio. Um simples “Erro” não ensina nada ao modelo; um objeto JSON que distingue o tipo de erro, se é transitório ou permanente, e os próximos passos, permite ao modelo decidir. Isto é contra-intuitivo: está a escrever mensagens de erro destinadas a ser lidas por uma máquina de raciocínio, e não registadas para humanos.

import json
from openai import OpenAI

client = OpenAI()

def execute_function(name: str, arguments: str, call_id: str) -> dict:
    try:
        args = json.loads(arguments)
        result = dispatcher[name](**args)
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except KeyError:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "unknown_function",
                "message": f"The function '{name}' does not exist"
            })
        }
    except json.JSONDecodeError:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "invalid_arguments",
                "message": "The JSON arguments are malformed"
            })
        }
    except Exception as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "internal_error",
                "message": str(e)
            })
        }

Nova tentativa com espera exponencial (Exponential Backoff)

A nova tentativa só faz sentido para problemas que possam resolver-se numa segunda tentativa: cortes de rede, códigos de estado 429 ou indisponibilidades temporárias. Tentar novamente um pedido rejeitado devido a autenticação inválida ou parâmetros incorretos apenas adia a falha enquanto multiplica as chamadas. É por isso que o código abaixo filtra explicitamente os erros — a filtragem faz o trabalho, enquanto o backoff é apenas a cortesia que deve ao serviço remoto.

import time
import random

def execute_with_retry(func, args, max_retries=3, base_delay=1.0):
    """Retry with exponential backoff and jitter."""
    for attempt in range(max_retries + 1):
        try:
            return func(**args)
        except (ConnectionError, TimeoutError) as e:
            if attempt == max_retries:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(delay)
        except ValueError:
            # Data error: do not retry
            raise

def execute_function_robust(name, arguments, call_id):
    args = json.loads(arguments)
    try:
        result = execute_with_retry(dispatcher[name], args)
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except Exception as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": type(e).__name__,
                "message": str(e),
                "retries_performed": 3
            })
        }

Timeouts por função

Um único timeout para todas as funções está sempre mal configurado: se for demasiado curto, mata o processamento pesado; se for demasiado longo, faz o utilizador esperar numa simples consulta de cache. Baseie cada valor nas durações observadas em condições normais, com uma margem — e não no pior caso imaginável, o que equivaleria efetivamente a não ter timeout nenhum.

import signal
from functools import wraps

TIMEOUTS = {
    "search_client": 5,
    "generate_report": 30,
    "send_email": 10,
}

def with_timeout(func, timeout_seconds):
    """Executes a function with a timeout."""
    import concurrent.futures
    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
        future = executor.submit(func)
        try:
            return future.result(timeout=timeout_seconds)
        except concurrent.futures.TimeoutError:
            raise TimeoutError(
                f"Function interrupted after {timeout_seconds}s"
            )

def execute_with_timeout(name, arguments, call_id):
    args = json.loads(arguments)
    timeout = TIMEOUTS.get(name, 10)  # 10s by default

    try:
        result = with_timeout(
            lambda: dispatcher[name](**args),
            timeout
        )
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except TimeoutError as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "timeout",
                "message": str(e),
                "suggestion": "Retry with more specific criteria"
            })
        }

Fallback entre funções

O fallback é uma compensação, não um reflexo: servir dados em cache com seis horas de antiguidade é melhor do que nada para um painel de controlo, e muito pior do que nada para um saldo bancário. Quando degrada o serviço, diga-o — no resultado devolvido ao modelo, para que este possa avisar o utilizador em vez de apresentar dados desatualizados como se fossem recentes.

async def search_product(term: str) -> dict:
    """Search with fallback: primary API -> cache -> local database."""
    # Attempt 1: Catalog API
    try:
        return await api_catalog.search(term)
    except Exception:
        pass

    # Attempt 2: Redis cache
    try:
        cached = await redis_client.get(f"product:{term}")
        if cached:
            result = json.loads(cached)
            result["_source"] = "cache"
            result["_warning"] = "Data may be outdated"
            return result
    except Exception:
        pass

    # Attempt 3: Local SQLite database
    try:
        row = db.execute(
            "SELECT * FROM products WHERE name LIKE ?",
            (f"%{term}%",)
        ).fetchone()
        if row:
            return {
                "name": row["name"],
                "price": row["price"],
                "_source": "local_db",
                "_warning": "Data from last synchronization"
            }
    except Exception:
        pass

    return {
        "error": "unavailable",
        "message": "No data source accessible for this search"
    }

Disjuntor (Circuit Breaker)

O disjuntor lida com aquilo que a nova tentativa não consegue: um serviço que está em baixo por um longo período. Após N falhas, ele dispara e devolve um erro imediatamente, sem sequer tentar, permitindo depois ocasionalmente a passagem de um pedido de teste para verificar a recuperação. O ganho é duplo: os seus utilizadores deixam de esperar por um timeout em cada pedido e o serviço em dificuldades não é mantido em baixo pelas suas novas tentativas.

from datetime import datetime, timedelta

class CircuitBreaker:
    def __init__(self, failure_threshold=5, open_duration=60):
        self.threshold = failure_threshold
        self.duration = open_duration
        self.failures = 0
        self.last_failure = None
        self.state = "closed"  # closed, open, half-open

    def can_execute(self) -> bool:
        if self.state == "closed":
            return True
        if self.state == "open":
            if datetime.now() - self.last_failure > timedelta(seconds=self.duration):
                self.state = "half-open"
                return True
            return False
        return True  # half-open: allow one test attempt

    def record_success(self):
        self.failures = 0
        self.state = "closed"

    def record_failure(self):
        self.failures += 1
        self.last_failure = datetime.now()
        if self.failures >= self.threshold:
            self.state = "open"

# One circuit breaker per external service
breakers = {
    "weather_api": CircuitBreaker(failure_threshold=3, open_duration=30),
    "catalog_api": CircuitBreaker(failure_threshold=5, open_duration=60),
}

Ciclo completo robusto

O padrão completo reúne os cinco mecanismos acima. Uma precaução torna-o verdadeiramente seguro e é fácil de ignorar: limite o número de iterações. Um modelo que entra num ciclo a chamar uma função cujo resultado não lhe agrada é raro, mas sem um teto máximo irá queimar o seu orçamento até à exaustão — e esse é o tipo de incidente que só descobre na fatura.

def robust_loop(prompt, tools, max_turns=10):
    messages = prompt
    for turn in range(max_turns):
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=messages,
            tools=tools
        )

        calls = [i for i in response.output if i.type == "function_call"]
        if not calls:
            return response.output_text

        results = []
        for call in calls:
            result = execute_function_robust(
                call.name, call.arguments, call.call_id
            )
            results.append(result)

        messages = response.output + results

    return "Workflow interrupted: turn limit reached"

Pontos-chave

  • Devolva sempre um function_call_output, mesmo em caso de erro
  • Estruture os erros como JSON para que o modelo os possa utilizar
  • Tente novamente apenas erros transitórios com espera exponencial (exponential backoff)
  • Implemente mecanismos de fallback entre fontes de dados
  • Utilize um disjuntor (circuit breaker) para proteger serviços em falha