Brunovski/gemma4-e2b-incident-triage

Gemma 4 E2B — Agente de Triagem de Incidentes de Infraestrutura (SRE / DevOps)

Fine-tuning (QLoRA 4-bit) do modelo unsloth/gemma-4-E2B-it projetado para atuar como um Agente Determinístico de Triagem de Incidentes. O modelo recebe recortes de logs brutos e ruidosos de infraestrutura (Traefik, Docker/Swarm, Kubernetes, PostgreSQL, Authentik e Prometheus), filtra alarmes falsos (ruído de inicialização, erros 4xx de cliente, warnings transitórios), isola a causa raiz em cenários de falha em cascata e retorna estritamente um objeto JSON padronizado apontando para o runbook de mitigação correspondente.

O JSON gerado alimenta diretamente um servidor MCP (Model Context Protocol, padrão aberto para conectar LLMs a ferramentas externas e bases de dados) (mcp-ops-kb), conectando a detecção de anomalias em logs à base operacional de procedimentos em Markdown (.md) para reduzir o MTTR (Mean Time to Resolution).

📊 Arquitetura da Solução

Fluxo: Log Bruto (K8s/Chaos Lab) → Gemma 4 E2B (Inferência Local 4-bit) → JSON (Contrato Estrito) → Guardrail (Validação de Runbook) → Servidor MCP → Runbook .md

---

1. Contrato de Saída (JSON)

Quando uma falha real de infraestrutura é detectada:

{
  "severidade": "ALTA",
  "componente_afetado": "Traefik / PKI",
  "causa_raiz": "Certificado TLS de api.exemplo.com expirado na CA interna.",
  "runbook": "runbooks/traefik/certificado-expirado.md"
}

Quando o log contém apenas operação normal, avisos inofensivos ou erros de negócio/cliente (hard negatives):

{
  "severidade": "NENHUMA",
  "componente_afetado": null,
  "causa_raiz": "Nenhuma falha de infraestrutura encontrada nos logs.",
  "runbook": null
}

---

2. Por que Fine-Tuning (QLoRA) + MCP em vez de RAG puro?

Em triagem automatizada de incidentes, a escolha por Fine-Tuning supervisionado (SFT) acoplado a uma camada determinística de validação supera uma arquitetura de RAG tradicional por quatro razões operacionais:

Assimetria Semântica no Log Bruto

Logs de infraestrutura contêm códigos ANSI, timestamps em múltiplos formatos, IPs dinâmicos, hashes de pods e stack traces extensos. A busca vetorial por similaridade (embedding similarity) sofre degradação severa quando confrontada com cascatas de erros nas quais o sintoma final (ex.: HTTP 504 no Traefik) domina o volume de linhas, mas a causa raiz real está em uma única linha anterior (ex.: connection pool esgotado ou falha de disco no PostgreSQL).

Garantia de Contrato Estrutural e Taxonomia Fechada

Enquanto um modelo base via prompting/RAG frequentemente descreve passos genéricos no campo runbook ou utiliza escalas de severidade arbitrárias (high, critical), o QLoRA condiciona os pesos do modelo à taxonomia exata da operação (34 classes distribuídas em 7 subsistemas) e ao esquema JSON estrito.

Resolução Temporal de Causa Raiz

O treinamento ensina a regra de negócio operacional de ignorar sintomas derivados (como pods entrando em BackOff após queda do banco) e apontar exclusivamente o evento primário.

Eficiência e Execução Local (FinOps / Privacidade)

Rodando em 4-bit numa única GPU de consumidor (RTX 4060 8 GB VRAM), a inferência ocorre localmente com baixa latência, custo zero de API e sem tráfego externo de logs sensíveis. A recuperação do conteúdo do runbook ocorre de forma determinística via MCP Server a partir do caminho exato retornado pelo modelo.

---

3. Resultados Experimentais (Modelo Base → v5 → v6)

A avaliação foi conduzida em duas frentes rigorosamente separadas do treinamento:

• Teste Sintético Controlado (n = 300): inclui formulações vistas, formulações inéditas (frases de erro nunca vistas no treino), cascatas de falhas e exemplos sem erro (hard negatives como HTTP 404/422/499, slow queries e warnings).
• Logs Reais do Chaos Lab (n = 32 janelas): logs reais coletados de um cluster Kubernetes (Minikube, namespace chaos-lab) rodando Traefik v3, PostgreSQL, Authentik e Prometheus sob injeção de falhas reais.

3.1. Evolução nos Logs Reais do Chaos Lab (n = 32 — Nunca vistos no treino)

Métrica / Critério	Modelo Base (Zero-shot)	Modelo v5 (Antes)	Modelo v6 (Atual)	Ganho (Base → v6)	Ganho (v5 → v6)
JSON Válido	100%	100%	100%	Estável (100%)	Estável (100%)
Runbook Correto (Exato)	0%	53%	88%	+88 p.p.	+35 p.p.
Severidade Correta	28%	34%	94%	+66 p.p.	+60 p.p.
Componente Afetado	3%	72%	91%	+88 p.p.	+19 p.p.
Grounding (Fatos no Log)	88%	21%	96%	+8 p.p.	+75 p.p.
Runbooks Inventados (Alucinação)	100%	44%	12%	-88 p.p.	-32 p.p.

Desempenho por Grupo nos Logs Reais (Versão v6)

Grupo Real (chaos-lab)	Janelas (n)	JSON	Runbook	Severidade	Componente	Grounding	Inventado
TOTAL	32	100%	88%	94%	91%	96%	12%
real (cascata)	6	100%	100%	100%	100%	100%	0%
real (traefik)	7	100%	100%	100%	100%	100%	0%
real (prometheus)	3	100%	100%	100%	100%	100%	0%
real (postgres)	10	100%	90%	90%	90%	100%	10%
real (events)	3	100%	67%	67%	100%	50%	33%
real (authentik)	3	100%	33%	100%	33%	100%	67%

---

3.2. Desempenho no Conjunto de Teste Sintético (n = 300)

Grupo de Teste	Exemplos (n)	JSON	Runbook (v5 → v6)	Severidade	Componente	Grounding	Inventado
TOTAL	300	100%	92% → 95%	96%	96%	96%	1%
cascata (causa raiz)	33	100%	100% → 97%	100%	97%	100%	3%
formulacao_inedita	123	100%	83% → 89%	91%	91%	92%	2%
formulacao_vista	95	100%	100% → 100%	100%	100%	100%	0%
sem_erro (hard negatives)	49	100%	100% → 100%	100%	100%	-	0%

4. Engenharia de Recursos: Como o Gemma 4 E2B coube em 8 GB de VRAM

A família Gemma 4 "E" (Effective) carrega tabelas extensas de Per-Layer Embeddings (~4,38 GB em bf16), o que faria o modelo ocupar ~7,17 GB apenas no carregamento inicial e inviabilizaria o treinamento numa NVIDIA GeForce RTX 4060 (8 GB).

Para viabilizar o fine-tuning local sem recorrer a GPUs de nuvem:

1. Descarte das torres multimodais (text_only=True): remoção das camadas de visão e áudio, mantendo apenas o decoder textual.
2. Quantização NormalFloat 4-bit (load_in_4bit=True): compressão dos pesos base com bitsandbytes.
3. Offload de embeddings para a RAM (offload_embedding=True): transferência das tabelas de embeddings para a memória RAM do sistema, reduzindo o consumo estático de VRAM para 2,48 GB logo após o carregamento.
4. Cálculo de loss exclusivo na resposta (train_on_responses_only): mascaramento dos tokens de entrada (logs brutos) para focar o gradiente exclusivamente na geração do JSON padronizado.

Parâmetros de Treinamento (Unsloth + TRL)

• Hardware: 1× NVIDIA GeForce RTX 4060 (8 GB VRAM) no Linux.
• Tempo de treinamento: 87,0 minutos (1.000 steps / 2 épocas sobre 3.996 exemplos filtrados).
• Pico de VRAM reservada: 7,18 GB.
• Configuração LoRA: r = 16, lora_alpha = 32, lora_dropout = 0, bias = "none" (24.158.208 parâmetros treináveis — 0,52% do total).
• Otimizador e precisão: adamw_8bit, bf16 = True, max_seq_length = 2048, batch_size = 1, gradient_accumulation_steps = 8, learning_rate = 2e-4.

---

5. Catálogo Operacional Coberto (34 Classes)

Subsistema	Classes
Traefik (7)	backend-indisponivel, timeout-backend, certificado-acme, certificado-expirado, ca-nao-confiavel, middleware-inexistente, rbac-sem-permissao
PostgreSQL (8)	conexoes-esgotadas, pool-esgotado, falha-autenticacao, deadlock, conexao-recusada, relacao-inexistente, disco-cheio, banco-inexistente
Kubernetes (7)	crashloopbackoff, image-pull-backoff, oomkilled, pending-recursos, pvc-nao-vinculado, probe-falhando, no-notready
Docker (5)	oom-killed, porta-em-uso, disco-cheio, falha-pull-imagem, container-unhealthy
Authentik (4)	redis-indisponivel, banco-indisponivel, outpost-sem-provider, smtp-indisponivel
Docker Swarm (2)	recursos-insuficientes, no-indisponivel
Prometheus (1)	config-invalida

---

6. Guardrails, Análise de Erros e Limitações

Análise dos desvios residuais na v6 (12% nos logs reais)

Nos 4 casos (em 32 janelas reais) em que o modelo não acertou o caminho exato:

• Em 2 janelas isoladas do Authentik (amostra restrita de n=3), o log mostrava apenas o container da aplicação reclamando que o banco Authentik não existia. O modelo identificou corretamente o problema (banco-inexistente.md), mas atribuiu o prefixo runbooks/authentik/banco-inexistente.md em vez de runbooks/postgres/banco-inexistente.md. Importante: quando avaliado nas 6 janelas de cascata completa (em que o log do Postgres estava presente no contexto), o modelo acertou 100% dos casos.
• Em 1 janela de Kubernetes Events, gerou o nome aproximado runbooks/kubernetes/container-falhando.md em vez de crashloopbackoff.md.

Camada de Guarda Determinística (triagem.py)

Para impedir que qualquer alucinação residual de caminho chegue ao servidor MCP em produção, a função triagem() valida o campo runbook contra o conjunto imutável RUNBOOKS_VALIDOS (extraído diretamente do diretório real de arquivos .md). Qualquer caminho fora do catálogo é interceptado e convertido para None (ou sinalizado para escalonamento/fallback).

---

7. Como Usar (Inferência Local)

Pré-requisitos

Certifique-se de ter as bibliotecas instaladas e o módulo triagem.py (disponível no repositório do GitHub) no mesmo diretório do script.

pip install unsloth transformers peft accelerate bitsandbytes

Código de exemplo

import json
from functools import partial

from unsloth import FastModel
import triagem as tri

# Carrega o modelo base em 4-bit + adaptadores LoRA com offload de embeddings
model, tokenizer = FastModel.from_pretrained(
    model_name="Brunovski/gemma4-e2b-incident-triage",
    max_seq_length=2048,
    load_in_4bit=True,
    text_only=True,
    device_map={"": 0},
    offload_embedding=True,
)
FastModel.for_inference(model)

triagem_fn = partial(tri.triagem, model, tokenizer)

log_exemplo = """traefik-1  | 2026-10-31T12:01:10Z INF Starting provider *docker.Provider
api-1      | INFO:     172.18.0.4:51234 - "GET /health HTTP/1.1" 200 OK
api-1      | java.sql.SQLTransientConnectionException: HikariPool-1 - Connection is not available, request timed out after 30000ms (total=20, active=20, idle=0, waiting=37)
traefik-1  | 201.17.4.9 - - [31/Oct/2026:12:01:41 +0000] "POST /v1/checkout HTTP/2.0" 504 15 "-" "okhttp/4.12.0" 912 "api@docker" "http://172.18.0.4:8080" 30004ms"""

resultado = triagem_fn(log_exemplo)
print(json.dumps(resultado, indent=2, ensure_ascii=False))

---

8. Licença e Termos de Uso

Este modelo é um adaptador derivado do Gemma 4 (unsloth/gemma-4-E2B-it) e seu uso está sujeito aos termos da licença do Gemma (Gemma Terms of Use).

Os logs utilizados na validação real foram gerados em ambiente isolado de laboratório (chaos-lab em Minikube).