Arquitetura de produção: monitorização, alertas e escalabilidade
Nesta página
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.