Plataforma GPU

Plataforma GPU — Arquitetura

Objetivo

Disponibilizar uma plataforma de IA unificada para uso interno (pesquisadores, aplicacoes, agentes), com:

API unica OpenAI-compatible para qualquer workload de IA
Flexibilidade: adicionar servico novo = 4 arquivos + git push
Multi-site (Franca + SP) sem over-engineering
Governanca: quotas, custo, observabilidade e seguranca desde o dia 1

Principio central

vLLM nao e a plataforma — e um dos backends.

A plataforma e: gateway + K3s + GPU ops + observabilidade + storage + auth. Servicos especificos (vLLM, Docling, Whisper, Tabby) se plugam na plataforma via um service contract padrao.

Cada ferramenta resolve exatamente um problema. Nenhuma ferramenta e a plataforma inteira.

Arquitetura em 4 camadas

┌─────────────────────────────────────────────────────────────────────────┐
│  LAYER 4 — API & Developer Experience                                   │
│                                                                         │
│  Traefik ──→ TensorZero ──→ backends                                    │
│  (TLS)       (auth, routing, A/B testing,                               │
│               rate-limit, spend tracking)                               │
│                                                                         │
│  Backstage (catalogo)     DSPy (pipelines declarativos de IA)           │
├─────────────────────────────────────────────────────────────────────────┤
│  LAYER 3 — AI Services                                                  │
│                                                                         │
│  Interativo (always-on)          │  Batch (Kueue)     │  CPU-only       │
│  ┌───────┐ ┌──────────┐         │  ┌─────────┐       │  ┌───────┐      │
│  │ vLLM  │ │SGLang    │         │  │ Unsloth │       │  │Qdrant │      │
│  │(chat) │ │(chat alt)│         │  │(fine-   │       │  │(vector│      │
│  └───────┘ └──────────┘         │  │ tuning) │       │  │  DB)  │      │
│  ┌───────┐ ┌──────────┐         │  └─────────┘       │  └───────┘      │
│  │Docling│ │Embeddings│         │  ┌─────────┐       │  ┌───────┐      │
│  │(OCR)  │ │ (BGE-M3) │         │  │OCR lote │       │  │Langfuse│     │
│  └───────┘ └──────────┘         │  └─────────┘       │  │(obs)  │      │
│  ┌───────┐ ┌──────────┐         │  ┌─────────┐       │  └───────┘      │
│  │Whisper│ │  FLUX    │         │  │Promptfoo│       │  ┌───────┐      │
│  │(STT)  │ │ (imagem) │         │  │ (eval)  │       │  │MLflow │      │
│  └───────┘ └──────────┘         │  └─────────┘       │  │(model)│      │
│  ┌───────┐ ┌──────────┐         │  ┌─────────┐       │  └───────┘      │
│  │ Tabby │ │pyannote  │         │  │autore-  │       │  ┌───────┐      │
│  │(code) │ │(diarizac)│         │  │search   │       │  │OpenWUI│      │
│  └───────┘ └──────────┘         │  └─────────┘       │  └───────┘      │
│  ┌───────┐ ┌──────────┐         │                     │  ┌───────┐      │
│  │LLM    │ │ dflash   │         │                     │  │Hermes │      │
│  │Guard  │ │(spec dec)│         │                     │  │Agent  │      │
│  └───────┘ └──────────┘         │                     │  └───────┘      │
│                                                                         │
│  Quantizacao: PolarQuant (pesos Q5) + TurboQuant (KV cache 3-bit)       │
│  Cada servico segue o SERVICE CONTRACT (secao dedicada)                 │
├─────────────────────────────────────────────────────────────────────────┤
│  LAYER 2 — Platform (comum a TODOS os workloads)                        │
│                                                                         │
│  GPU Sharing: KAI Scheduler (fracionario, topology-aware) + DRA          │
│  Scheduling:  Kueue (batch) + KEDA (autoscaling) + PriorityClasses      │
│  Observab.:   OpenObserve + OTel + DCGM + Langfuse + OpenCost           │
│  Storage:     SeaweedFS + HF cache PVC + Qdrant + DVC + MLflow          │
│  Seguranca:   Authentik + Kyverno + Sealed Secrets + NetworkPolicies     │
│  Ops:         Argo CD (GitOps) + Velero (backup)                        │
├─────────────────────────────────────────────────────────────────────────┤
│  LAYER 1 — GPU Infrastructure                                           │
│                                                                         │
│  Pulumi (LXC provisioning) → Proxmox → NVIDIA Driver                   │
│  → LXC privileged (/dev/nvidia*) → nvidia-ctk → K3s Agent              │
│  Node labels: gpu.site, gpu.model, gpu.vram                             │
│                                                                         │
│  Franca: 3x A5500 (24GB)  │  SP: 3x A5000 (24GB)                       │
│  Total: 144 GB VRAM                                   │
└─────────────────────────────────────────────────────────────────────────┘

LAYER 1 — GPU Infrastructure

Objetivo: GPU acessivel como recurso nativo do K8s (nvidia.com/gpu).

Componente	Funcao	Por que
Pulumi	Provisiona LXC/VMs no Proxmox via IaC (GPU passthrough, CPU/RAM, rede)	Infraestrutura reproduzivel, sem clique manual
Proxmox	Hypervisor que hospeda LXC/VMs com GPU	Ja existe na infra
NVIDIA Driver	Driver no host Proxmox (script `pve-nvidia-upgrade.sh`)	Base de tudo — sem driver, sem GPU
LXC privileged	Container com bind mount `/dev/nvidia*`, overhead minimo vs VM	Performance quase nativa, kernel compartilhado
NVIDIA Container Toolkit (nvidia-ctk)	Runtime nvidia para containerd dentro do LXC	Permite pods K8s acessarem GPU
K3s Agent	Worker node GPU que se junta ao cluster existente	Extende o cluster sem substituir
Node Labels	`gpu.site=franca/saopaulo`, `gpu.model=a5000`, `gpu.vram=24gi`	Scheduling por afinidade (modelos grandes → GPU maior)

Divisao Pulumi vs Ansible

Ferramenta	Escopo
Pulumi	Criar LXC, configurar GPU passthrough, alocar CPU/RAM, rede
Ansible	Instalar NVIDIA driver no host, nvidia-ctk no LXC, join do K3s agent

Hardware

- Franca: 3x NVIDIA A5500 (24 GB VRAM cada) = 72 GB
Sao Paulo: 3x NVIDIA A5000 (24 GB VRAM cada) = 72 GB
Total atual: 144 GB VRAM
Expansao futura: A6000 (48 GB VRAM) conforme demanda

Por que LXC e nao VM?

LXC acessa a GPU via bind mount dos devices (/dev/nvidia*), usando o driver instalado no host Proxmox. Performance quase nativa com overhead minimo. O trade-off (menos isolamento) e aceitavel em ambiente academico controlado.

1 LXC por servidor, nao por GPU. Servidores com multiplas GPUs devem ter 1 unico LXC com acesso a todas as GPUs. O DRA (Dynamic Resource Allocation) expoe as GPUs como recursos K8s, e o KAI Scheduler gerencia multiplas GPUs dentro do mesmo K3s worker com topology-awareness, permitindo tensor parallelism para modelos grandes.

LAYER 2 — Platform

Objetivo: Infraestrutura compartilhada que todo servico de IA usa, independente do tipo de workload.

Componente	Funcao	Por que
DRA (Dynamic Resource Allocation)	Alocacao granular de GPU nativa do K8s (GA no 1.31+). NVIDIA doou driver para CNCF (KubeCon EU 2026).	Substitui NVIDIA Device Plugin com modelo de recursos mais expressivo
KAI Scheduler	Scheduler GPU da NVIDIA (open-sourced Run:ai, CNCF Sandbox). GPU fracionaria, topology-aware (NVLink/PCIe), hierarchical queues, gang scheduling, preemption inteligente.	Principal — substitui HAMi com scheduling mais sofisticado e NVIDIA-backed
Kueue	Filas de jobs batch, quotas por lab/departamento, fairness, preemption controlada	Sem ele, fine-tuning compete sem regras com inference
KEDA	Autoscaling de replicas baseado em metricas (fila vLLM, latencia, GPU util)	Escala vLLM automaticamente; libera GPU para batch quando ocioso
PriorityClasses	`critical-inference(1000)` > `default-gpu(500)` > `batch(100)`	Inference always-on nunca e preemptada por batch

Observabilidade

Componente	Funcao	Por que
DCGM Exporter	Metricas GPU (utilizacao, VRAM, temperatura) → OpenObserve	Visibilidade de hardware GPU
OpenObserve + OTel	Metricas de infra (CPU, RAM, disco, rede) + logs de todos os pods	Ja existe, extender com GPU
Langfuse	Observabilidade LLM — tracing de requests, tokens, latencia, custo, qualidade por usuario/modelo	Mede o uso da IA, nao so da infra
Promptfoo	Avaliacao de modelos antes do deploy (CI/CD de prompts)	Previne deploy de modelo que degradou qualidade
OpenCost	Custo por namespace/lab/modelo em reais	Accountability em ambiente academico, justifica investimento

Storage

Componente	Funcao	Por que
SeaweedFS (S3 API)	Datasets, checkpoints de fine-tuning, documentos, backups	Ja existe, S3-compatible
HuggingFace Cache PVC	PVC compartilhado montado em todos os GPU nodes com cache de modelos	Evita re-download de modelos de 20GB+ entre nodes
Qdrant	Vector database para embeddings e busca semantica (RAG)	CPU-only, nao compete por GPU
MLflow	Model registry — versoes de modelos fine-tunados, rollback, lineage	Controle formal de modelos treinados com Unsloth
DVC	Versionamento de datasets de treino no Git	Rastreabilidade de dados usados em fine-tuning

Seguranca

Componente	Funcao	Por que
Authentik	SSO, API keys, OIDC, RBAC	Identidade centralizada (ja existe)
Kyverno	Policies K8s — limitar VRAM maxima por job, forcar labels obrigatorios, impedir pods privileged em ai-services	Guardrails operacionais: um job mal configurado nao derruba a inference
Sealed Secrets	Credenciais criptografadas no Git (API keys OpenRouter, tokens HuggingFace, credenciais Langfuse)	Eliminar plaintext no repositorio
LLM Guard	Content filtering, deteccao de PII, protecao contra prompt injection	Seguranca do conteudo gerado pelos modelos
NetworkPolicies	Isolamento de namespace `ai-services`	Pods de IA nao acessam namespaces de outras apps

Multi-tenancy

Preocupacao	Solucao
Dados entre labs/pesquisadores	Collections separadas no Qdrant, org separation no Langfuse
Quotas de uso	Budget caps por lab no TensorZero, quotas de GPU no Kueue
API keys	Isolamento por usuario/grupo via Authentik
Logs/prompts (LGPD)	Politica de retencao no Langfuse, anonimizacao quando necessario

Operacoes

Componente	Funcao	Por que
Argo CD	GitOps — cada servico = 1 Application, sync automatico	Zero kubectl manual, git e a fonte de verdade
Velero	Backup de PVCs (Qdrant, Langfuse, MLflow, configs)	Recuperacao de estado apos falha

Compartilhamento e segmentacao de GPU

Secao dedicada porque e uma decisao arquitetural critica: como compartilhar GPUs que nao suportam MIG entre multiplos servicos.

Tecnologias disponiveis

Tecnologia	O que faz	Isolamento VRAM	A5500/A5000	Custo	Status
KAI Scheduler	Scheduler GPU NVIDIA (ex-Run:ai). GPU fracionaria, topology-aware, hierarchical queues, gang scheduling	Sim	Sim	Free (CNCF Sandbox)	Escolhido
DRA (Dynamic Resource Allocation)	Alocacao granular de GPU nativa do K8s (GA no 1.31+). NVIDIA doou driver para CNCF.	Sim (via driver)	Sim	Free	Escolhido (complementa KAI)
HAMi	Virtualizacao de GPU com limite de VRAM enforced por pod	Sim (soft)	Sim	Free (CNCF Sandbox)	Fallback
Time-slicing	Compartilha GPU por tempo, N pods revezam	Nao	Sim	Free	Fallback
NVIDIA MIG	Particiona GPU em instancias isoladas (hardware)	Sim (hardware)	Nao (A100/H100 apenas)	Free	N/A p/ nosso hardware
NVIDIA vGPU	Virtualiza GPU com VRAM dedicada via hypervisor	Sim (virtualizado)	Sim	Pago (licenca Enterprise)	Descartado por custo

Decisao: KAI Scheduler + DRA (primario) + HAMi (fallback)

KAI Scheduler (NVIDIA, CNCF Sandbox, KubeCon EU 2026) e o scheduler de GPU mais sofisticado disponivel em open source. Substitui HAMi com capacidades superiores:

Capacidade	HAMi	KAI Scheduler
GPU fracionaria (VRAM enforced)	Sim	Sim (via DRA)
Topology-aware (NVLink, PCIe)	Nao	Sim — coloca pods que precisam de multi-GPU em GPUs conectadas por NVLink
Hierarchical queues	Nao	Sim — quotas por lab/departamento com fairness
Gang scheduling	Nao	Sim — multi-GPU atomico (fine-tuning distribuido)
Preemption inteligente	Basica	Sim — respeita prioridade + fairness
Consolidation	Nao	Sim — empacota workloads para liberar GPUs inteiras para jobs grandes
Reclaim	Nao	Sim — GPU ociosa de um lab e emprestada para outro
Backing	Comunidade	NVIDIA

KAI + DRA trabalham juntos: DRA e o driver que expoe GPUs como recursos K8s (substitui NVIDIA Device Plugin). KAI e o scheduler que decide como alocar esses recursos de forma inteligente.

# Com KAI Scheduler + DRA
# Pod declara GPU fracionaria via ResourceClaim
apiVersion: resource.k8s.io/v1beta1
kind: ResourceClaim
metadata:
  name: vllm-gpu
spec:
  devices:
    requests:
      - name: gpu
        deviceClassName: gpu.nvidia.com
        selectors:
          - cel:
              expression: "device.attributes['gpu.nvidia.com'].memory >= 8192"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm
spec:
  template:
    spec:
      containers:
        - name: vllm
          resources:
            claims:
              - name: gpu
      resourceClaims:
        - name: gpu
          resourceClaimTemplateName: vllm-gpu

Por que KAI em vez de HAMi:

NVIDIA-backed — alinhado com o ecossistema GPU (driver DRA, Device Plugin, DCGM)
CNCF Sandbox — governanca comunitaria, nao vendor-locked
Topology-aware — critico para fine-tuning distribuido (Unsloth multi-GPU)
Hierarchical queues — labs com quotas e fairness, sem Kueue para scheduling (Kueue mantem o papel de job queueing)
Consolidation — empacota workloads pequenos para liberar GPUs inteiras para jobs grandes

Fallback: HAMi como alternativa caso KAI apresente problemas de compatibilidade com K3s (KAI e mais testado em K8s vanilla/OpenShift).

MIG: nao aplicavel — requer A100, A30, ou H100. Se o hardware futuro incluir essas GPUs, MIG e a melhor opcao (isolamento real de hardware).

vGPU: funciona em A5500/A5000 com isolamento real, mas requer licenca paga da NVIDIA (vGPU Enterprise). Descartado por custo.

Exemplo pratico: 1 A5000 (24 GB) compartilhada

GPU A5000 #1 (24 GB total) — KAI Scheduler distribui:
├── vLLM chat (Qwen3-8B AWQ)     → 14 GB VRAM (ResourceClaim)
├── vLLM embeddings (BGE-M3)     → 2 GB VRAM
└── Faster-Whisper               → 4 GB VRAM
                                   ─────────────────────────
                                   Total: 20 GB / 24 GB (4 GB livre)

KAI Scheduler: lab-pesquisa submete fine-tuning que precisa de 24 GB
  → KAI consolida vLLM+BGE+Whisper para outra GPU
  → libera GPU inteira para fine-tuning
  → quando fine-tuning termina, redistribui

Se um pod tentar alocar mais VRAM do que disponivel, KAI rejeita o scheduling (nao cabe).

Quantizacao — estrategia para 24 GB VRAM

Com GPUs de 24 GB (A5000), caber modelos grandes exige compressao eficiente. A estrategia combina duas tecnicas complementares que atuam em partes diferentes do modelo:

Tecnica	O que comprime	Abordagem	Resultado
PolarQuant	Pesos do modelo	Transformada de Hadamard → quantizacao polar. Q5 praticamente lossless, sem calibracao, sem dataset de treino	Modelo 70B cabe onde antes so cabia 30B
TurboQuant	KV cache (memoria de contexto)	Quantizacao 3-bit do KV cache (Google, ICLR 2026). Training-free, data-oblivious	Contexto longo (32K+ tokens) sem estourar VRAM

Por que duas tecnicas?

Pesos e KV cache sao gargalos independentes:

Pesos: ocupam VRAM fixa ao carregar o modelo. PolarQuant reduz isso.
KV cache: cresce com o tamanho do contexto (cada request aloca mais). TurboQuant comprime isso.

Aplicar as duas = modelo menor + contexto mais longo na mesma GPU.

Comparativo de quantizacao de pesos

Metodo	Bits	Precisa calibracao?	Qualidade vs FP16	Status
PolarQuant	Q5	Nao (training-free)	~99.5% (praticamente lossless)	Recomendado
AWQ	Q4	Sim (dataset de calibracao)	~98%	Fallback (ja suportado no vLLM)
GPTQ	Q4	Sim (dataset de calibracao)	~97-98%	Fallback
GGUF	Q4-Q8	Nao	Variavel	Uso em llama.cpp, nao em vLLM

Nota sobre TensorRT-LLM

TensorRT-LLM (NVIDIA) oferece 15-30% mais throughput via compilacao otimizada, mas tem trade-offs significativos:

Modelos precisam ser pre-compilados (engine build demorado)
Sem API OpenAI nativa — requer Triton Inference Server como wrapper
Menos flexivel no K3s (binarios pesados, ciclo de deploy lento)
Lock-in NVIDIA (sem suporte AMD futuro)

Decisao: acompanhar evolucao, nao adotar agora. Se throughput se tornar gargalo critico, avaliar como backend alternativo do vLLM (que ja suporta TensorRT como backend experimental).

LAYER 3 — AI Services

Objetivo: Servicos especializados que consomem GPU via service contract. Cada servico e 1 Deployment (ou Job) no K8s, independente dos outros.

Servicos interativos (always-on)

Deployments que rodam continuamente, servindo requests em tempo real.

Servico	Runtime	Funcao	GPU estimada
vLLM	vLLM	Chat, raciocinio, geracao de codigo. API OpenAI-compatible. Continuous batching interno, prefix caching.	1-2 GPUs (depende do modelo)
SGLang	SGLang	Backend alternativo ao vLLM. OpenAI-compatible, RadixAttention (KV cache reuse entre requests), ~29% mais rapido em RAG e multi-turn. TensorZero roteia entre vLLM e SGLang via A/B testing.	1-2 GPUs (depende do modelo)
Embeddings (BGE-M3)	vLLM	Vetorizacao de texto multilingual para busca semantica e RAG. Alimenta o Qdrant.	~2 GB VRAM
Docling/Marker	PyTorch	Parsing de PDFs, OCR, extracao de tabelas e estrutura de documentos. Nao depende de vLLM.	~4-8 GB VRAM
Faster-Whisper	CTranslate2	Speech-to-text otimizado. Transcricao de aulas, entrevistas, reunioes.	~2-4 GB VRAM
pyannote	PyTorch	Diarizacao de falantes (quem disse o que em reunioes/entrevistas). Complementa Whisper.	~2 GB VRAM
Tabby	Custom	Self-hosted Copilot. Autocomplete de codigo em IDE (VS Code, JetBrains).	~4-8 GB VRAM
FLUX/SDXL	Diffusers	Geracao e analise de imagens. Materiais didaticos, visualizacoes cientificas.	~8-12 GB VRAM
LLM Guard	PyTorch	Guardrails de seguranca: content filtering, deteccao de PII, prompt injection protection.	~2 GB VRAM (ou CPU)
Grobid	Java	Parser de artigos cientificos (autores, afiliacoes, referencias, DOI). Pode rodar em CPU.	CPU-only
dflash	PyTorch	Speculative decoding via block diffusion. Otimizacao ortogonal — funciona COM vLLM ou SGLang, 6x+ speedup em geracao longa. Nao e um backend separado, e um acelerador.	Usa GPU do backend

SGLang vs vLLM — quando usar qual?

Ambos sao backends OpenAI-compatible. TensorZero roteia entre eles.

Aspecto	vLLM	SGLang
Maturidade	Referencia, maior comunidade	Mais novo, comunidade crescente
Multi-turn / RAG	Bom (prefix caching)	~29% mais rapido (RadixAttention reutiliza KV cache entre requests)
Throughput puro	Excelente	Comparavel ou superior
Modelos suportados	Maior catalogo	Catalogo crescente (cobre os principais)
Operador K8s	Nao tem oficial	OME operator (deploy facilitado)

Estrategia: vLLM como backend primario (mais maduro). SGLang como alternativo para workloads RAG-heavy. TensorZero faz A/B testing automatico e roteia para o mais performante.

Servicos batch (jobs com inicio e fim)

Jobs gerenciados pelo Kueue com filas, quotas e preemption.

Servico	Runtime	Funcao	GPU estimada
Unsloth	PyTorch	Fine-tuning LoRA/QLoRA de LLMs. Ate 2x mais rapido que metodos tradicionais. Checkpointing para retomar apos preemption.	1-4 GPUs (12-48 GB)
OCR em lote	Docling/Marker	Processamento batch de documentos (teses, acervos, microfilmes). Submetido via Airflow ou API.	1 GPU
Dataset generation	vLLM/API	Geracao de dados sinteticos via modelos cloud para fine-tuning de modelos locais.	1 GPU (ou API externa)
Promptfoo	Node.js + API	Avaliacao automatica de modelos antes do deploy. CI/CD de prompts — roda como Job no pipeline.	Usa vLLM existente
autoresearch	vLLM + Python	Pesquisa ML autonoma (pattern Karpathy): agente modifica codigo → treina 5 min → avalia → repete. Jobs longos gerenciados pelo Kueue com checkpoint.	1-2 GPUs

Servicos CPU-only (parte da plataforma, sem GPU)

Servico	Funcao
Qdrant	Vector database para embeddings e RAG. Busca semantica, clustering, deduplicacao.
Langfuse	Observabilidade LLM: tracing de requests, contagem de tokens, latencia, custo e qualidade por usuario/modelo.
MLflow	Model registry: versoes de modelos fine-tunados, rollback, lineage de dados de treino.
Open WebUI	Interface web para pesquisadores. Arena Mode para comparar modelos side-by-side. Chat, upload de documentos, historico.
DVC	Data Version Control: versionamento de datasets de treino no Git, rastreabilidade para fine-tuning.
Hermes Agent	Agentes autonomos NousResearch. Multi-plataforma, memoria auto-melhoravel, skills-based. Orquestra pipelines de pesquisa combinando vLLM + Qdrant + Neo4j.

Service Contract

Para adicionar qualquer servico novo a plataforma, sao necessarias 4 coisas:

Container image com CUDA runtime + endpoint de saude (GET /health → 200 OK)
K8s manifests em apps/<service>/
- deployment.yaml (ou job.yaml para batch)
- service.yaml (ClusterIP, porta 8000 por convencao)
- Resources: nvidia.com/gpu, hami.io/gpu-mem, priorityClassName, readinessProbe
Argo CD Application em apps/argocd/<service>.yaml
Rota no gateway (1 entrada na config do TensorZero ou 1 IngressRoute para servicos nao-OpenAI)

Nenhuma mudanca de infra. Nenhum driver. Nenhum CRD custom.

Exemplo — adicionar servico de TTS (text-to-speech):

# 1. Criar manifests
apps/tts/deployment.yaml    # image, gpu: 1, hami.io/gpu-mem: 4096, priority: default-gpu
apps/tts/service.yaml       # ClusterIP, port 8000

# 2. Registrar no Argo CD
apps/argocd/tts.yaml        # Application CR apontando para apps/tts/

# 3. Adicionar rota no gateway
# TensorZero config: /v1/audio/speech → tts-svc.ai-services:8000

# 4. Deploy
git push → Argo CD sync → Pod schedulado no GPU node → disponivel via gateway

LAYER 4 — API & Developer Experience

Objetivo: Entrada universal para consumidores + self-service para pesquisadores.

Componentes

Componente	Funcao	Por que
Traefik	TLS termination, host-based routing (`ai.cppsunesp.org`)	Ja existe na infra, reusar
TensorZero	AI Gateway: auth, rate-limit, routing, fallback local→cloud, A/B testing de modelos, prompt versioning, spend tracking, BYOK	Mais que proxy: experimentacao integrada. Pesquisadores podem testar modelos diferentes sem mudar codigo.
DSPy	Framework declarativo Stanford para pipelines de IA. Substitui prompt engineering por codigo Python: define modulos (ChainOfThought, ReAct, RAG) e DSPy otimiza prompts automaticamente via avaliacao.	Pesquisadores descrevem o que querem (classificar, extrair, resumir), DSPy descobre como fazer com o modelo disponivel.
Backstage	Internal Developer Portal: catalogo de servicos, endpoints disponiveis, documentacao, ownership por time	Pesquisadores sabem o que existe e como usar sem ler o repo ou perguntar

Fluxo de um request

Pesquisador / Aplicacao
    │
    │  POST https://ai.cppsunesp.org/v1/chat/completions
    │       { "model": "qwen3-8b", "messages": [...] }
    │
    ▼
┌─ Traefik (debian-proxy) ──────────────────────────────────────┐
│  TLS termination                                               │
│  Host: ai.cppsunesp.org → K3s NodePort (ai-gateway)           │
└───────────────────────────┬────────────────────────────────────┘
                            │
                            ▼
┌─ TensorZero (K3s Pod) ────────────────────────────────────────┐
│  1. Autenticar (Authentik token / API key)                    │
│  2. Rate-limit (por usuario/grupo/lab)                        │
│  3. Rotear por modelo:                                        │
│     "qwen3-8b"           → vllm-svc ou sglang-svc (A/B test) │
│     "openrouter/claude"  → OpenRouter API (cloud)             │
│     "openai/gpt-4o"      → OpenAI API (BYOK: token pessoal)  │
│  4. Emitir trace → Langfuse                                   │
│  5. Registrar custo → OpenCost                                │
└───────────────────────────┬────────────────────────────────────┘
                            │
                            ▼
┌─ vLLM ou SGLang (K3s Pod) ────────────────────────────────────┐
│  Continuous batching, KV cache, prefix caching (vLLM)          │
│  RadixAttention, KV cache reuse entre requests (SGLang)        │
│  Resposta JSON OpenAI-compatible                               │
└────────────────────────────────────────────────────────────────┘

Endpoints da API

Path	Backend	Protocolo
`/v1/chat/completions`	vLLM (chat)	OpenAI-compatible
`/v1/embeddings`	vLLM (BGE-M3)	OpenAI-compatible
`/v1/audio/transcriptions`	Faster-Whisper	OpenAI-compatible
`/v1/images/generations`	FLUX/SDXL	OpenAI-compatible
`/v1/documents/parse`	Docling	Custom REST
`/v1/code/completions`	Tabby	Tabby protocol
`/v1/models`	TensorZero	OpenAI-compatible (lista modelos disponiveis)
`/api/jobs/*`	Kueue (via controller)	Custom REST

TensorZero: por que, e nao LiteLLM?

Aspecto	LiteLLM	TensorZero
Proxy OpenAI	Sim	Sim
Rate-limit/quotas	Sim	Sim
Spend tracking	Sim	Sim
Fallback local→cloud	Sim	Sim
BYOK	Sim	Sim
A/B testing de modelos	Nao	Sim, nativo
Prompt versioning	Nao	Sim, nativo
Routing dinamico por performance	Nao	Sim
Dados estruturados para fine-tuning	Nao	Sim

Em ambiente academico com experimentacao continua (testar Qwen vs DeepSeek vs Llama, otimizar prompts, medir qualidade), TensorZero agrega mais valor que um proxy simples.

MVP: Traefik → vLLM direto (sem gateway). TensorZero entra quando houver 2+ servicos.

Observabilidade — 4 camadas

Cada camada mede algo diferente. Sao complementares, nao substitutas.

Camada	Ferramenta	O que mede	Exemplo
Infra	OpenObserve + OTel + DCGM	CPU, RAM, disco, rede, GPU utilization, VRAM, temperatura	”GPU #2 esta a 85C”
LLM	Langfuse	Tokens, latencia, custo, qualidade por request/usuario/modelo	”Lab X consumiu 500K tokens esta semana”
Eval	Promptfoo	Qualidade de modelo antes do deploy (CI/CD de prompts)	“Qwen3-8B v2 piorou 5% em queries em portugues”
Custo	OpenCost	Custo por namespace/lab/modelo em reais	”Namespace ai-services custa R$X/mes em GPU”

Storage

Tipo	Ferramenta	Conteudo	Observacoes
Object storage	SeaweedFS (S3 API)	Datasets, checkpoints de fine-tuning, documentos, backups	Ja existe no cluster
Model cache	PVC compartilhado (HuggingFace Hub cache)	Pesos de modelos (~20-40 GB cada)	Montado em todos os GPU nodes, evita re-download
Vector store	Qdrant	Embeddings para busca semantica e RAG	CPU-only, nao compete por GPU
Dataset versioning	DVC	Versionamento de dados de treino	Rastreabilidade para fine-tuning
Model registry	MLflow	Versoes de modelos fine-tunados, rollback, lineage	Controle formal de modelos treinados

Seguranca

Preocupacao	Solucao	Componente
Credenciais em plaintext	Criptografia no Git	Sealed Secrets
Controle de acesso	SSO, API keys, RBAC	Authentik (ja existe)
Policies K8s	Limitar VRAM, forcar labels, impedir privileged	Kyverno
Conteudo do modelo	Content filtering, deteccao de PII, prompt injection	LLM Guard
Isolamento de rede	Namespace isolation	NetworkPolicies
Multi-tenancy	Collections separadas, org separation	Qdrant + Langfuse
Backup/DR	Backup de PVCs + dump de databases	Velero + CronJob
Rotacao de secrets	Rotacao automatica de API keys	External Secrets Operator (futuro)

Batch vs Interactive

Dois fluxos distintos que compartilham a mesma GPU pool.

INTERACTIVE (Deployments always-on)
──────────────────────────────────
Request → TensorZero → vLLM/Whisper/Docling
                         │
                         ├── vLLM gerencia fila interna (continuous batching)
                         ├── KEDA escala replicas (baseado em fila/latencia)
                         └── PriorityClass: critical-inference (1000)

BATCH (Jobs gerenciados por Kueue)
──────────────────────────────────
Submit → Kueue → Job K8s → GPU
           │
           ├── Fila com fairness entre labs
           ├── Quotas: "Lab X max 2 GPUs para batch"
           ├── Preemption: batch e evictado se inference precisa da GPU
           ├── Checkpoint: estado salvo em SeaweedFS, retoma de onde parou
           └── PriorityClass: batch (100)

Coexistencia:
  - Inference tem prioridade absoluta sobre batch
  - Batch roda quando ha GPU livre (ex: madrugada)
  - KEDA escala inference para baixo quando ocioso → libera GPU para batch
  - Kueue re-submete batch automaticamente apos preemption

Multi-site (Franca + SP)

Documento detalhado: ver integracao-sp-franca.md para arquitetura completa, papel de cada ferramenta e fases de implementacao.

Decisao: clusters separados

Cada site roda K3s independente. A rede entre sites (via UNESP/ANSP) pode sofrer particoes. Em cluster unico, particao de rede evicta pods e e destrutiva. Em clusters separados, cada site continua autonomo.

K3s Cluster Franca                    K3s Cluster SP
├── Control Plane                     ├── Control Plane
├── GPU Nodes (3x A5500, 24GB)        ├── GPU Nodes (3x A5000, 24GB)
├── Argo CD (self)                    ├── Argo CD (self)
├── Cilium (CNI)                      ├── Cilium (CNI)
│                                     │
│        VyOS WireGuard (site-to-site, UNESP/ANSP)
│        Cilium Cluster Mesh (Global Services, mTLS)
│        Karmada (placement, failover, override por cluster)
│                                     │
├── vLLM (modelos menores)            ├── vLLM (modelos 70B+, A6000)
├── Whisper, Docling, BGE-M3          ├── Whisper, Docling, BGE-M3
└── Servicos web (replicas)           └── Servicos web (replicas)
         │                                    │
         └───── Kueue MultiKueue ─────────────┘
                (batch GPU cross-site)

Especializacao por site

Site	Hardware	Papel
Franca	CPU moderado, 3x A5500 (24GB) = 72 GB VRAM	Web, orquestracao (Airflow), modelos menores
SP	Epic 84-core, 3x A5000 (24GB) = 72 GB VRAM	Compute pesado, modelos grandes, fine-tuning

Abordagem hibrida para chamadas cross-site

Tipo de chamada	Quem roteia	Por que
GPU (vLLM, Whisper, embeddings)	TensorZero	Model-aware, A/B test, fallback cloud
Batch GPU (fine-tuning, OCR lote)	Kueue MultiKueue	Queue-aware, despacha para cluster com GPU livre
Dados (Trino, Neo4j, PostgreSQL, Qdrant)	Cilium Global Services	Service discovery transparente cross-cluster

Futuro: 3o site (cloud)

Quando houver demanda de burst ou DR:

Liqo para overflow transparente de pods para cloud (virtual nodes)
Kueue MultiKueue para despachar batch GPU para cloud
Candidatos: Oracle Cloud (free tier ARM), Hetzner (~4 EUR/mes)

Estrutura do repositorio

devops/
├── infra/
│   └── gpu-nodes/             # Pulumi: provisiona LXC com GPU passthrough no Proxmox
│
├── config/
│   ├── gpu-node/              # Ansible: NVIDIA driver, nvidia-ctk, K3s agent join
│   ├── traefik/               # (existente) + rota ai.cppsunesp.org
│   └── vyos/                  # (existente)
│
├── apps/
│   ├── gpu-operator/          # DRA driver + KAI Scheduler (GPU sharing)
│   ├── ai-gateway/            # TensorZero (gateway)
│   ├── ai-platform/           # Namespace, PriorityClasses, ResourceQuotas, Kyverno policies
│   ├── dcgm-exporter/         # GPU metrics → OpenObserve
│   ├── kueue/                 # Job scheduling (batch)
│   ├── opencost/              # Cost tracking
│   ├── langfuse/              # LLM observability
│   ├── qdrant/                # Vector database
│   ├── mlflow/                # Model registry
│   ├── backstage/             # Developer portal
│   ├── llm-guard/             # Safety guardrails
│   ├── vllm/                  # LLM inference
│   ├── sglang/                # LLM inference (alternativo)
│   ├── embeddings/            # BGE-M3
│   ├── docling/               # Document processing
│   ├── whisper/               # Audio STT
│   ├── tabby/                 # Code assistance
│   ├── hermes-agent/          # Agentes autonomos
│   ├── open-webui/            # Web interface
│   ├── openobserve/           # (existente) OTel Collector
│   ├── argocd/                # (existente) + 1 Application CR por servico novo
│   └── ...                    # apps existentes (Airflow, etc.) inalteradas
│
├── roadmap/
│   └── gpu-platform.md        # Este documento
│
└── docs/
    └── openobserve-setup.md   # (existente)

Fases de implementacao

Cada fase funciona independente das seguintes. A plataforma e utilizavel a partir da Fase 2.

Fase	Foco	Componentes	Resultado
0	GPU no K3s	Pulumi (LXC), NVIDIA driver, nvidia-ctk, K3s agent	`nvidia-smi` visivel de dentro de um Pod
1	Platform base	DRA driver, KAI Scheduler, DCGM, PriorityClasses, namespace `ai-services`, HF cache PVC, Sealed Secrets	GPU schedulavel como recurso K8s com sharing inteligente
2	Primeiro servico	vLLM (chat) + Open WebUI, acessivel via Traefik direto	Pesquisadores usando chat via browser
3	Gateway + obs	TensorZero + Authentik + Langfuse + LLM Guard	API unificada com auth, tracing e guardrails
4	Expandir servicos + SGLang	Embeddings + Qdrant + Docling + Whisper + SGLang (1 git push cada). SGLang como backend alternativo, TensorZero roteia via A/B test.	5+ servicos de IA operacionais, benchmarks vLLM vs SGLang
5	Batch + modelos	Kueue + Unsloth + MLflow + DVC + Promptfoo	Fine-tuning com filas, model registry, eval
6	Operacoes	OpenCost + Kyverno + Velero + KEDA	Custo, policies, backup, autoscaling
7	Developer experience	Backstage (catalogo) + Tabby (code assist) + DSPy (pipelines declarativos)	Self-service para pesquisadores
8	Multi-site	VyOS WireGuard (UNESP/ANSP) + K3s SP + Cilium Cluster Mesh + Karmada + Argo CD SP + GPU nodes SP (A6000) + MultiKueue	Clusters separados com failover automatico, 216 GB VRAM distribuidos
9	Avancado	dflash (speculative decoding), Hermes Agent (agentes autonomos), autoresearch (pattern Karpathy), PolarQuant + TurboQuant (quantizacao), TensorZero A/B testing, pipeline de auto-melhoria	Experimentacao continua, modelos locais melhorando automaticamente

Catalogo de componentes (indice completo — 48)

Todos os componentes da plataforma, sem excecao:

#	Componente	Camada	Tipo	Funcao resumida
1	Pulumi	L1 Infra	IaC	Provisiona LXC/VM no Proxmox
2	Proxmox	L1 Infra	Hypervisor	Hospeda VMs/LXCs
3	NVIDIA Driver	L1 Infra	Driver	Acesso a GPU no host
4	LXC	L1 Infra	Container	GPU passthrough com overhead minimo
5	nvidia-ctk	L1 Infra	Runtime	GPU em containers
6	K3s Agent	L1 Infra	Orchestrator	Worker node GPU
7	DRA (Dynamic Resource Allocation)	L2 Platform	K8s nativo	GPU como recurso K8s (substitui Device Plugin)
8	KAI Scheduler	L2 Platform	GPU Sharing	Fracionario, topology-aware, hierarchical queues (substitui HAMi)
9	DCGM Exporter	L2 Platform	Metricas	Metricas GPU
10	Kueue	L2 Platform	Scheduling	Filas de jobs batch
11	KEDA	L2 Platform	Autoscaling	Escala replicas por metricas
12	PriorityClasses	L2 Platform	K8s	Prioridade inference > batch
13	OpenCost	L2 Platform	FinOps	Custo por namespace/lab
14	Kyverno	L2 Platform	Policies	Guardrails K8s
15	Sealed Secrets	L2 Platform	Seguranca	Credenciais no Git
16	Velero	L2 Platform	Backup	Backup de PVCs
17	Argo CD	L2 Platform	GitOps	Sync automatico
18	Authentik	L2 Platform	IAM	SSO, API keys, RBAC
19	NetworkPolicies	L2 Platform	Seguranca	Isolamento de rede
20	OpenObserve + OTel	L2 Platform	Observabilidade	Metricas e logs de infra
21	SeaweedFS	L2 Platform	Storage	Object storage S3
22	HF Cache PVC	L2 Platform	Storage	Cache de modelos
23	vLLM	L3 Services	Inference	Chat, raciocinio, codigo
24	BGE-M3 (Embeddings)	L3 Services	Inference	Vetorizacao de texto
25	Docling/Marker	L3 Services	Inference	OCR, parsing de PDFs
26	Faster-Whisper	L3 Services	Inference	Speech-to-text
27	pyannote	L3 Services	Inference	Diarizacao de falantes
28	Tabby	L3 Services	Inference	Code assist (Copilot)
29	FLUX/SDXL	L3 Services	Inference	Geracao de imagens
30	LLM Guard	L3 Services	Seguranca	Content filtering, PII
31	Grobid	L3 Services	Inference	Parser de artigos cientificos
32	Unsloth	L3 Services	Batch	Fine-tuning LoRA/QLoRA
33	Promptfoo	L3 Services	Batch	Eval de modelos (CI/CD)
34	Qdrant	L3 Services	Database	Vector DB para RAG
35	Langfuse	L3 Services	Observabilidade	Tracing LLM
36	MLflow	L3 Services	MLOps	Model registry
37	Open WebUI	L3 Services	Frontend	Interface para pesquisadores
38	DVC	L3 Services	MLOps	Versionamento de datasets
39	SGLang	L3 Services	Inference	Backend alternativo ao vLLM (RadixAttention)
40	dflash	L3 Services	Otimizacao	Speculative decoding via block diffusion (6x+)
41	autoresearch	L3 Services	Batch	Pesquisa ML autonoma (pattern Karpathy)
42	Hermes Agent	L3 Services	Agentes	Agentes autonomos NousResearch
43	PolarQuant	L2 Platform	Quantizacao	Pesos Q5 lossless via Hadamard
44	TurboQuant	L2 Platform	Quantizacao	KV cache 3-bit (Google ICLR 2026)
45	Traefik	L4 API	Gateway	TLS, routing externo
46	TensorZero	L4 API	AI Gateway	Auth, routing, A/B testing
47	DSPy	L4 API	DX	Pipelines declarativos de IA (Stanford)
48	Backstage	L4 API	DX	Catalogo de servicos

Plataforma GPU

Plataforma GPU — Arquitetura

Objetivo

Principio central

Arquitetura em 4 camadas

LAYER 1 — GPU Infrastructure

Divisao Pulumi vs Ansible

Hardware

Por que LXC e nao VM?

LAYER 2 — Platform

GPU Sharing e Scheduling

Observabilidade

Storage

Seguranca

Multi-tenancy

Operacoes

Compartilhamento e segmentacao de GPU

Tecnologias disponiveis

Decisao: KAI Scheduler + DRA (primario) + HAMi (fallback)

Exemplo pratico: 1 A5000 (24 GB) compartilhada

Quantizacao — estrategia para 24 GB VRAM

Por que duas tecnicas?

Comparativo de quantizacao de pesos

Nota sobre TensorRT-LLM

LAYER 3 — AI Services

Servicos interativos (always-on)

SGLang vs vLLM — quando usar qual?

Servicos batch (jobs com inicio e fim)

Servicos CPU-only (parte da plataforma, sem GPU)

Service Contract

LAYER 4 — API & Developer Experience

Componentes

Fluxo de um request

Endpoints da API

TensorZero: por que, e nao LiteLLM?

Observabilidade — 4 camadas

Storage

Seguranca

Batch vs Interactive

Multi-site (Franca + SP)

Decisao: clusters separados

Especializacao por site

Abordagem hibrida para chamadas cross-site

Futuro: 3o site (cloud)

Estrutura do repositorio

Fases de implementacao

Catalogo de componentes (indice completo — 48)