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

Arquitetura de produção: monitorização, alertas e escalabilidade

Aula 20 de 20 Atualizada a 3 de novembro de 2026 Avancado
Nesta página
  1. A sua aplicação em produção: os três pilares
  2. Observar: o que medir
  3. Reagir: alertas graduados
  4. Absorver: três mecanismos de resiliência
  5. Lista de verificação para implementação em produção
  6. Pontos-chave
  7. Teste os seus conhecimentos

A sua aplicação em produção: os três pilares

Colocar uma aplicação LLM em produção não se resume apenas ao código. Três pilares garantem a fiabilidade: a monitorização para observar, os alertas para reagir e a escalabilidade para absorver a carga. Eles formam uma corrente, e uma corrente é tão forte quanto o seu elo mais fraco: métricas que ninguém consulta são inúteis, alertas sem um procedimento de resposta são apenas ruído, e uma escalabilidade que atua demasiado tarde resulta apenas numa indisponibilidade. Esta última lição reúne todos os conceitos do curso numa arquitetura de produção completa.

Observar: o que medir

Quatro famílias de métricas cobrem o essencial: volume de chamadas, latência, erros e custos, desagregados por modelo. A desagregação por modelo é o que torna o painel acionável — uma taxa de erro global de 3% não lhe diz nada, enquanto esse mesmo valor concentrado num único modelo aponta imediatamente para o culpado.

A classe abaixo acumula estas métricas na memória, utilizando uma janela deslizante de 10 000 latências para impedir que o processo cresça indefinidamente. Note o uso de percentis em vez de médias: a latência média de um serviço LLM é quase sempre enganadora, porque um punhado de chamadas muito lentas desaparece na média, embora sejam exatamente essas as que causam queixas aos seus utilizadores.

import time
from dataclasses import dataclass, field
from collections import defaultdict

@dataclass
class ProductionMetrics:
    """Recolhe métricas essenciais de produção."""

    counters: dict = field(default_factory=lambda: defaultdict(int))
    latencies: dict = field(default_factory=lambda: defaultdict(list))
    errors: dict = field(default_factory=lambda: defaultdict(int))
    costs: dict = field(default_factory=lambda: defaultdict(float))

    def record_call(
        self,
        model: str,
        latency: float,
        input_tokens: int,
        output_tokens: int,
        cost: float,
        success: bool,
    ):
        self.counters[model] += 1
        self.latencies[model].append(latency)
        self.costs[model] += cost

        if not success:
            self.errors[model] += 1

        # Manter apenas as últimas 10 000 latências
        if len(self.latencies[model]) > 10_000:
            self.latencies[model] = self.latencies[model][-10_000:]

    def percentile(self, model: str, p: float) -> float:
        """Calcula um percentil de latência."""
        values = sorted(self.latencies.get(model, []))
        if not values:
            return 0.0
        idx = int(len(values) * p / 100)
        return values[min(idx, len(values) - 1)]

    def error_rate(self, model: str) -> float:
        total = self.counters.get(model, 0)
        if total == 0:
            return 0.0
        return self.errors.get(model, 0) / total

    def dashboard(self) -> dict:
        """Gera um painel de controlo completo."""
        dashboard = {}
        for model in self.counters:
            dashboard[model] = {
                "calls": self.counters[model],
                "latency_p50": f"{self.percentile(model, 50):.2f}s",
                "latency_p99": f"{self.percentile(model, 99):.2f}s",
                "error_rate": f"{self.error_rate(model):.2%}",
                "total_cost": f"${self.costs[model]:.2f}",
            }
        return dashboard

Claro que a recolha deve ser sistemática. Instrumentar manualmente cada chamada garante que se esquecerá de uma — e provavelmente daquela que causará problemas. O decorador abaixo move a medição para o nível da função de chamada: o bloco finally regista a latência e o sucesso independentemente do que aconteça, mesmo quando uma exceção é propagada.

import openai
import functools

metrics = ProductionMetrics()

def monitor(func):
    """Decorador que monitoriza cada chamada à API."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        model = kwargs.get("model", args[0] if args else "unknown")
        start = time.perf_counter()
        success = True

        try:
            result = func(*args, **kwargs)
            return result
        except Exception as e:
            success = False
            raise
        finally:
            latency = time.perf_counter() - start
            metrics.record_call(
                model=model,
                latency=latency,
                input_tokens=0,
                output_tokens=0,
                cost=0,
                success=success,
            )

    return wrapper

Os contadores de tokens e os custos permanecem a zero nesta versão porque o objeto de resposta não está disponível no momento do registo. Complete-os lendo os campos de utilização devolvidos pela API: sem esta informação, o seu painel de controlo apresentará fielmente uma coluna de custos nulos.

Reagir: alertas graduados

Um alerta só tem valor se exigir uma ação. É por isso que o sistema distingue dois limiares por métrica: um limiar de aviso, que sinaliza um desvio a examinar durante o dia, e um limiar crítico, que justifica acordar alguém. Confundir os dois produz o pior resultado possível — uma equipa que aprendeu a ignorar as notificações.

from enum import Enum

class AlertLevel(Enum):
    INFO = "info"
    WARNING = "warning"
    CRITICAL = "critical"

class AlertSystem:
    """Dispara alertas com base nas métricas."""

    def __init__(self):
        self.thresholds = {
            "error_rate": {"warning": 0.05, "critical": 0.15},
            "latency_p99": {"warning": 10.0, "critical": 30.0},
            "hourly_cost": {"warning": 50.0, "critical": 200.0},
        }
        self.sent_alerts: list[dict] = []

    def check(self, metrics: ProductionMetrics) -> list[dict]:
        """Verifica as métricas e gera alertas."""
        alerts = []

        for model in metrics.counters:
            # Taxa de erro
            rate = metrics.error_rate(model)
            if rate >= self.thresholds["error_rate"]["critical"]:
                alerts.append({
                    "level": AlertLevel.CRITICAL,
                    "message": (
                        f"Taxa de erro CRÍTICA para {model}: "
                        f"{rate:.1%}"
                    ),
                    "model": model,
                })
            elif rate >= self.thresholds["error_rate"]["warning"]:
                alerts.append({
                    "level": AlertLevel.WARNING,
                    "message": (
                        f"Taxa de erro elevada para {model}: "
                        f"{rate:.1%}"
                    ),
                    "model": model,
                })

            # Latência
            p99 = metrics.percentile(model, 99)
            if p99 >= self.thresholds["latency_p99"]["critical"]:
                alerts.append({
                    "level": AlertLevel.CRITICAL,
                    "message": (
                        f"Latência p99 CRÍTICA para {model}: "
                        f"{p99:.1f}s"
                    ),
                    "model": model,
                })

        self.sent_alerts.extend(alerts)
        return alerts

    async def notify(self, alerts: list[dict]):
        """Envia notificações (webhook, e-mail, Slack)."""
        import httpx

        for alert in alerts:
            if alert["level"] == AlertLevel.CRITICAL:
                # Notificação imediata
                async with httpx.AsyncClient() as http:
                    await http.post(
                        "https://your-webhook.example.com/alerts",
                        json={
                            "level": alert["level"].value,
                            "message": alert["message"],
                        },
                    )

Os alertas de custo horário são dos mais frequentemente esquecidos, e isso é lamentável: um ciclo de repetição ilimitado ou um trabalho em lote lançado duas vezes resulta numa fatura, não num erro. É a única rede de segurança que deteta este tipo de incidente enquanto ele ocorre.

Absorver: três mecanismos de resiliência

Quando a API devolve um erro, tentar novamente piora as coisas: adiciona carga a um serviço já em dificuldades e faz os seus utilizadores esperar em vão. O disjuntor inverte esta lógica. Após um número definido de falhas consecutivas, ele abre o circuito e rejeita imediatamente as chamadas subsequentes, tentando novamente após um atraso de reinicialização.

class CircuitBreaker:
    """Corta as chamadas quando ocorrem demasiados erros."""

    def __init__(
        self,
        open_threshold: int = 5,
        reset_delay: float = 60.0,
    ):
        self.threshold = open_threshold
        self.reset_delay = reset_delay
        self.consecutive_failures = 0
        self.opened_at: float | None = None

    @property
    def is_open(self) -> bool:
        if self.opened_at is None:
            return False
        if time.time() - self.opened_at > self.reset_delay:
            # Tentar fechar o circuito
            self.opened_at = None
            self.consecutive_failures = 0
            return False
        return True

    def record_success(self):
        self.consecutive_failures = 0
        self.opened_at = None

    def record_failure(self):
        self.consecutive_failures += 1
        if self.consecutive_failures >= self.threshold:
            self.opened_at = time.time()

    def call(self, func, *args, **kwargs):
        """Executa a função se o circuito estiver fechado."""
        if self.is_open:
            raise RuntimeError(
                "Circuito aberto — API indisponível. "
                f"Tente novamente em {self.reset_delay}s."
            )
        try:
            result = func(*args, **kwargs)
            self.record_success()
            return result
        except Exception as e:
            self.record_failure()
            raise

O disjuntor protege a sua aplicação; não a faz funcionar, contudo. Essa é a função da alternância de modelo (fallback), que tenta alternativas por ordem, ignorando aquelas cujos circuitos já estão abertos. Um ponto de design a reter: a ordem da lista é uma decisão de produto, não técnica. Coloque em primeiro lugar o modelo que entrega o serviço esperado, seguido daqueles que entregam um serviço degradado mas aceitável — uma resposta ligeiramente menos precisa é preferível a uma mensagem de indisponibilidade.

class ModelFallback:
    """Muda para um modelo de reserva em caso de falha."""

    def __init__(self):
        self.models = ["gpt-5.6-terra", "gpt-5.6-sol", "gpt-5.6-luna"]
        self.circuits = {
            m: CircuitBreaker() for m in self.models
        }

    def call(self, prompt: str) -> str:
        """Tenta cada modelo até obter uma resposta."""
        client = openai.OpenAI()

        for model in self.models:
            circuit = self.circuits[model]
            if circuit.is_open:
                continue

            try:
                response = circuit.call(
                    client.responses.create,
                    model=model,
                    input=prompt,
                )
                return response.output_text
            except Exception:
                continue

        raise RuntimeError("Todos os modelos estão indisponíveis.")

O terceiro mecanismo diz respeito ao dimensionamento. Gerir o número de trabalhadores com base no tamanho da fila em vez da carga da CPU é o reflexo correto para um serviço que passa a maior parte do tempo à espera de respostas de rede: a CPU fica ociosa enquanto a fila cresce. Note a assimetria na regra aplicada — duplicamos na escalagem ascendente e reduzimos para metade na descendente, com limiares amplamente separados (100 vs. 10). Esta diferença previne a oscilação: sem ela, o sistema passaria o tempo a criar e destruir trabalhadores em torno do ponto de viragem.

class AutoScaler:
    """Ajusta o número de trabalhadores com base na carga."""

    def __init__(
        self,
        min_workers: int = 2,
        max_workers: int = 50,
        scale_up_threshold: int = 100,
        scale_down_threshold: int = 10,
    ):
        self.min_workers = min_workers
        self.max_workers = max_workers
        self.up_threshold = scale_up_threshold
        self.down_threshold = scale_down_threshold
        self.active_workers = min_workers

    def adjust(self, queue_size: int) -> int:
        """Devolve o número recomendado de trabalhadores."""
        if queue_size > self.up_threshold:
            self.active_workers = min(
                self.active_workers * 2,
                self.max_workers,
            )
        elif queue_size < self.down_threshold:
            self.active_workers = max(
                self.active_workers // 2,
                self.min_workers,
            )

        return self.active_workers

Lista de verificação para implementação em produção

Este curso termina com a lista de verificação a percorrer antes de abrir a sua aplicação ao público. Cada item remete para uma lição que cobriu; se algum parecer pouco claro, releia essa lição antes de implementar.

  • Monitorização da latência (p50, p95, p99) e das taxas de erro
  • Alertas configurados em limiares críticos
  • Disjuntor para proteger contra falhas da API
  • Alternância de modelo (fallback) configurada
  • Moderação de entrada e saída ativada
  • Limitação de taxa (rate limiting) no lado do cliente implementada
  • Registos estruturados para depuração
  • Avaliações automatizadas no CI/CD
  • Orçamento de custos com alertas
  • Documentação de prompts versionada

Pontos-chave

  • A monitorização abrange latência, erros, custos e qualidade da resposta
  • Acompanhe os percentis de latência, nunca apenas a média
  • Os alertas devem ser graduados: aviso e depois crítico
  • O disjuntor protege contra cascatas de falhas; a alternância garante a disponibilidade
  • Uma lista de verificação de produção previne omissões críticas

Teste os seus conhecimentos

Latência, custos, avaliações: reflexos de produção em cinco perguntas.

1. Quais são as principais alavancas para reduzir a latência?

Resposta: Streaming (latência percecionada), cache de prompts (prefixos estáveis), Saídas Previstas quando a resposta é largamente previsível (Chat Completions, em modelos desativados a 14 de janeiro de 2027) e otimização do próprio prompt — medido de ponta a ponta.

2. Quando deve utilizar a Batch API?

Resposta: Para processamento massivo sem restrições de tempo real: lotes assíncronos a custo reduzido — classificação, enriquecimento ou geração de volume não têm lugar no caminho síncrono.

3. O que faz a compactação de conversação?

Resposta: Comprime o histórico longo (resumos, poda) para caber no contexto e controlar custos — essencial para agentes e sessões longas.

4. Qual é o objetivo da estrutura de Avaliações (Evals) no CI/CD?

Resposta: Executar automaticamente as suas avaliações em cada alteração de prompt ou modelo: a regressão é detetada no commit, não em produção.

5. O que inclui uma arquitetura de produção completa?

Resposta: Monitorização (latência, custos, qualidade), alertas, filas assíncronas, moderação em escala e um plano de escalabilidade — a IA em produção é um sistema, não uma chamada à API.

Meça, coloque em cache, loteie, avalie continuamente: quatro hábitos que tornam as aplicações rápidas, leves e fiáveis.