Arquitetura e LLMOps em Produção

9.1 IA ou regra determinística?

Os melhores sistemas misturam: o LLM interpreta (texto → dados estruturados), o código decide e executa (regras de negócio, cálculos, permissões). Você viu isso no extrator de recibos: o modelo lê, o código valida a soma e os dígitos do CNPJ.

9.2 Arquitetura de referência

Princípios

• Baixo acoplamento: aplicações falam com o gateway e com serviços internos por interfaces estáveis; trocar de modelo ou provedor não exige mudar as aplicações.
• Políticas como dados: rotas, cotas e prompts ficam em configuração versionada (o politicas.ts e a pasta prompts/ do projeto).
• Segurança no centro: chaves dos provedores só no gateway; aplicações recebem chaves próprias, revogáveis, com cota.
• Onde rodar: serverless (escala a zero, bom para tráfego irregular, cuidado com tempo máximo de execução em respostas longas), contêineres/Kubernetes (controle e conexões longas de streaming), edge (latência, mas ambiente limitado).

9.3 Roteamento de modelos e tiering

export const ROTAS: Record<Tarefa, string[]> = {
  classificar: ["claude-haiku-5-5", "claude-sonnet-5-5"],   // barato primeiro, reserva depois
  extrair:     ["claude-sonnet-5-5", "claude-opus-5-5"],
  resumir:     ["claude-sonnet-5-5", "claude-haiku-5-5"],
  geral:       ["claude-opus-5-5", "claude-sonnet-5-5"],
};

• Roteamento por tarefa (o do projeto): a aplicação declara a tarefa; o gateway escolhe o modelo. Simples e previsível.
• Roteamento por intenção ou dificuldade: um classificador barato decide se a pergunta precisa do modelo grande. Economiza mais, mas o classificador também erra; meça.
• Cadeia de reserva: em erro transitório (429, 5xx, conexão) ou recusa, tenta o próximo modelo. Em erro do pedido (400), não: o problema não é o modelo.
• Esforço por rota: o mesmo modelo com esforço baixo pode bastar para tarefas simples; compare isso antes de trocar de modelo.

9.4 Camadas de cache

Repare que a chave do cache do projeto inclui a versão do prompt: lançar um prompt novo invalida automaticamente as respostas antigas. Cache semântico só em casos controlados (FAQ sem dados pessoais, com limiar de similaridade alto e avaliado).

9.5 Capacidade, filas e processamento assíncrono

python python/01_capacidade.py

TRÁFEGO
  chamadas por dia:                 120.000
  média / pico por segundo:         2.8 / 11.1
  chamadas simultâneas no pico:      67   (lei de Little: taxa × latência)

LIMITES DO PROVEDOR (no pico)
  requisições/min                 667 de      4.000 (17%)
  tokens de entrada/min     2.000.000 de  2.000.000 (100%)  ⚠ NO LIMITE OU ACIMA: vai receber 429 no pico

CUSTO MENSAL (30 dias)
  tudo no claude-opus-5-5                      US$   72.000/mês  (100%)
  tudo no claude-sonnet-5-5                    US$   36.000/mês  (50%)
  roteado: 60% haiku, 30% sonnet, 10% opus     US$   19.080/mês  (26%)
  roteado + 50% da entrada vinda do cache      US$   13.928/mês  (19%)

• Lei de Little: chamadas simultâneas = taxa de chegada × latência. Latências de segundos geram muita concorrência, o que pede pools de conexão e servidores preparados para conexões longas.
• Filas para o que não precisa de resposta imediata: absorvem picos e permitem retentativas com controle.
• Batch (50% mais barato) para processamento noturno.
• Tempo máximo por requisição e cancelamento quando o usuário desiste (Módulo 8).

9.6 Observabilidade

O gateway grava uma linha JSON por requisição (gateway.jsonl):

{"id":"req-118","cliente":"app-suporte","tarefa":"geral","versaoPrompt":"v1",
 "modelo":"claude-sonnet-5-5","tentativas":[{"modelo":"claude-opus-5-5","erro":"RateLimitError"},{"modelo":"claude-sonnet-5-5"}],
 "cache":false,"tokensEntrada":2400,"tokensSaida":150,"custoUsd":0.0063,"latenciaMs":1840,"status":"ok"}

• Métricas de operação: custo por cliente, modelo e versão de prompt; taxa de cache; latência p50/p95; uso de reserva; erros; recusas por cota. É o que o painel do projeto mostra.
• Traces distribuídos (OpenTelemetry): uma requisição de usuário que passa por RAG, três chamadas de modelo e duas ferramentas vira um trace com todos os passos e tempos. Os SDKs dos provedores e várias plataformas de observabilidade de LLM já emitem esses spans.
• Prompts e respostas nos logs: essenciais para depurar, e são dados pessoais. Decida o que registrar, por quanto tempo e quem acessa; mascare dados sensíveis.
• Qualidade em produção: amostras avaliadas pelo LLM-juiz calibrado e sinais dos usuários (Módulo 3) entram no mesmo painel.

9.7 Versionamento de prompts, canário e rollback

{
  "estavel": "v1",
  "candidata": "v2",
  "fracaoCandidata": 0.1,
  "versoes": {
    "v1": { "sistema": "Classifique ...", "criadoEm": "2026-09-02", "nota": "versão inicial" },
    "v2": { "sistema": "Você classifica ... desempate ...", "criadoEm": "2026-10-20", "nota": "em canário 10%" }
  }
}

1. A versão nova passa no eval offline (Módulo 3).
2. Entra como candidata com 5–10% do tráfego. A escolha é determinística pelo id da requisição.
3. O painel compara custo e qualidade de classificar@v1 e classificar@v2.
4. Promove (vira estável) ou faz rollback (remove a candidata), mudando um arquivo, sem deploy das aplicações.

O mesmo vale para trocar de modelo: uma rota nova em canário, medida, e então promovida.

Projeto do módulo: gateway de LLM

cd projeto && npm install && npm test       # 13 testes com provedor falso
GATEWAY_CLIENTES="$(openssl rand -hex 16):app-suporte:5" npm run gateway
# painel em http://127.0.0.1:8787/

Os testes usam um provedor falso em que cada modelo se comporta como configurado (sucesso, 429, 500, 400 ou recusa) e provam: roteamento, reserva só em erro transitório, cache e TTL, cota diária com virada de dia, autorização por tarefa, proporção do canário e as métricas.

Entregáveis

1. Coloque duas aplicações suas (ou os projetos dos Módulos 2 e 4) para chamar o gateway em vez da API.
2. Adicione streaming (SSE) ao gateway, com registro de custo ao fim do stream.
3. Implemente roteamento por dificuldade com um classificador barato e compare custo e qualidade com o roteamento por tarefa usando a suíte do Módulo 3.
4. Exporte traces com OpenTelemetry para uma ferramenta de sua escolha.
5. Faça um canário real de uma versão de prompt e escreva a decisão de promover ou não, com números.

Critérios de avaliação

Recursos para aprofundar

• OpenTelemetry · traces, métricas e logs; veja as convenções semânticas para IA generativa
• LiteLLM · um gateway aberto, para comparar com o seu
• Documentação da API · limites de taxa, cache de prompt e batch
• Livros de SRE do Google · fundamentos de operação que valem para sistemas com IA