Gateway de LLM open source KTMS 1.0 conecta GPUs próprias à nuvem e sobrevive a falhas

O KTMS (Keystone. The Model Switchboard) é um gateway de LLM open source escrito em Go: um ponto único pelo qual os aplicativos de uma empresa acessam modelos de diversos provedores. Os autores lançaram a versão 1.0 e explicaram como o gateway se comporta em produção. É possível conectar GPUs próprias e enviar requisições a elas antes de recorrer à nuvem paga. Para cada uma das três dependências (Postgres, Redis e o serviço de contabilização), o comportamento em caso de falha já está definido. As chaves de criptografia são trocadas sem perdas, e os releases são assinados e verificados. A atualização acontece sem parar o serviço.

GPUs próprias primeiro, nuvem como reserva

Muitas equipes têm um Mac Studio ou uma máquina Linux com uma boa placa que fica ociosa metade do tempo. Enquanto isso, a conta da nuvem cresce com requisições que um modelo local também resolveria. O KTMS transforma essas máquinas em um vendor à parte, chamado local.

O administrador emite, via gRPC, a chave do nó (exibida uma única vez) e registra o modelo. Na própria máquina, roda-se um único script. Ele instala o Ollama, o modelo e o agente do nó, configura os serviços em segundo plano e impede que o computador entre em suspensão. No macOS, não são necessários privilégios de administrador. Se algo der errado, o mesmo script com a flag --doctor aponta a causa: Ollama sem resposta, modelo não carregado, Ollama rodando na CPU via Rosetta, --tls incorreto. Há suporte a Ollama, vLLM, TGI e llama.cpp.

O gateway é quem se conecta ao nó, então ele precisa estar acessível. O agente consegue subir um túnel Cloudflare e um filtro na frente do engine. Só passam por ele POST /v1/chat/completions e GET /v1/models, de modo que não é possível baixar nem remover um modelo de fora.

A escolha do nó acontece em três etapas:

• Filtro. Ficam os nós que têm o modelo necessário, um slot livre e janela de contexto suficiente. Os saudáveis vêm antes dos suspeitos, e os "quentes" (com o modelo já na memória) antes dos "frios".
• Peso. O peso base é multiplicado por uma penalidade de carga, que cresce de forma quadrática com a ocupação dos slots, e por um fator de correção de velocidade. Esse fator é calculado a partir da velocidade de geração (tokens por segundo, peso 0,7) e do tempo até o primeiro token (peso 0,3), em relação à mediana de todos os nós com esse modelo.
• Seleção. Aplica-se o smooth weighted round-robin, como no nginx.

A principal proteção contra lentidão é a estimativa de fila pela lei de Little: a profundidade da fila multiplicada pela duração esperada da requisição. Se o resultado passar de queue_timeout_ms do modelo (2000 ms no exemplo), a requisição vai imediatamente para o próximo modelo da cadeia. Para clientes interativos, o limite é de 250 ms. O slot é um lease no Redis, renovado enquanto a geração está em andamento.

Políticas de posicionamento: nodes_first (padrão), nodes_only (sem nó livre, retorna erro e a nuvem não é acionada), cloud_first e cloud_only. A escolha pode ser feita por cabeçalho, por campo da requisição ou por sufixo do modelo, por exemplo auto:nodes-only:high.

O que o gateway faz quando Redis e Postgres caem

O princípio: uma falha na contabilização não deve virar uma falha do serviço.

• Redis. Os limites de requisições e de tokens são ignorados, sem contabilização. Para limites em dólares, é possível escolher o modo: open deixa passar, closed rejeita. O cache é tratado como miss. O estado dos nós fica desconhecido, então eles são pulados e a nuvem responde. Após três erros de rede seguidos, o gateway deixa de consultar o Redis por 2 segundos, e um Redis travado custa à requisição apenas um timeout.
• Postgres. As chaves verificadas nos últimos 5 minutos continuam funcionando, e as demais recebem auth_unavailable. A verificação é limitada a 3 segundos. A configuração vem do último snapshot bem-sucedido. Um batch cuja idempotência não pode ser verificada é rejeitado, para que não se pague por ele duas vezes.
• Serviço de contabilização. Os eventos se acumulam na memória (até 10 000), e as requisições não esperam por eles.

Quando o Postgres falha, /readyz responde 200 com status degraded enquanto a janela de chaves conhecidas estiver ativa, e 503 depois dela. Assim, o Kubernetes não reinicia os pods antes da hora. Cinco falhas seguidas abrem o circuit breaker do vendor, e após 30 segundos passa uma tentativa de teste. Vale configurar o alerta em ktms_dependency_errors_total.

Chaves, assinatura de releases e atualização sem downtime

As chaves dos vendors ficam no Postgres, criptografadas com AES-256-GCM. O keyring com as chaves de criptografia é passado pela variável KTMS_ENCRYPTION_KEYS e não é armazenado no banco. A rotação tem três etapas. Primeiro, adicionar a nova versão do keyring em todas as réplicas e esperar o fim do rollout. Depois, chamar RotateEncryption: em uma única transação, são recriptografadas as chaves dos vendors e os tokens dos nós. Por fim, remover a versão antiga quando não restar nenhum backup que dependa dela. Um dump junto com o keyring revela todas as chaves em texto aberto, por isso os dois devem ser guardados separadamente.

Desde a versão 0.14.0, as imagens são assinadas com cosign em modo keyless: a assinatura fica vinculada à identidade do workflow no GitHub Actions, e não há chave para roubar. As imagens acompanham SBOM (lista de componentes) e SLSA-provenance (registro de onde e como foram compiladas). Cada pull request passa pelo govulncheck, e um release não sai sem buf breaking e sem o teste de atualização. Os autores fazem uma ressalva honesta: a assinatura atesta a origem, não a segurança. Quem obtiver permissões sobre o workflow de release também conseguirá assinar uma imagem maliciosa.

Dentro da série 1.x, a API pública não é quebrada. As migrações são aplicadas na inicialização sob advisory-lock e apenas adicionam schema, então as réplicas antigas funcionam no banco novo enquanto as novas sobem. Não há rollback: o caminho de volta é o backup feito antes da atualização. Em caso de SIGTERM, as requisições têm 30 segundos para terminar, e o agente do nó entra primeiro em drain.

Para equipes com GPUs ociosas, é uma forma pronta de reduzir a conta da nuvem sem o risco de ficar sem resposta em caso de sobrecarga. Antes de colocar em produção, vale verificar o TLS (o próprio gateway fala gRPC em texto plano), remover o BOOTSTRAP_ADMIN_KEY, criar uma chave separada por cliente e acompanhar as conexões do Postgres (até 25 por réplica).