De duas APIs para um Smart API Router: regras, v29 e Deep Analyze atrás de um único endpoint

Até esta semana, a zn oferecia duas APIs. Você escolhia uma por requisição, e os limites da sua assinatura ficavam divididos entre as duas. Era um imposto de design em cada integração: escolher errado dava uma falsa sensação de segurança, e escolher certo exigia entender nossas entranhas melhor do que você deveria precisar.

Hoje existe um único endpoint. POST /analyze encaminha cada requisição por três camadas progressivas — regras determinísticas, a porta neural v29 e o Deep Analyze — e diz qual delas decidiu.

TL;DR

• POST /analyze agora é um Smart API Router (SAR): Nível 1 regras determinísticas (<50 µs), Nível 2 v29 neural int8 (~15–18 ms), Nível 3 Deep Analyze (mmBERT v8, ~166 ms a quente) para a faixa ambígua.
• /v30/analyze continua como alias de compatibilidade. O caminho de produto POST /prod/analyze segue só-regras para quem quer a porta de latência ultrabaixa.
• O router é fail-open: se o Deep Analyze estourar o tempo (orçamento de 6 s) ou falhar, você ainda recebe o veredicto do v29. Um gateway de segurança nunca deve virar a queda.
• As assinaturas agora têm cotas explícitas de DeepAnalyze por nível, de 25/mês no teste de 48 h até 30.000/mês no Growth.
• Zero retenção de dados nos planos pagos. A resposta inclui tier, decided_by, latency_ms e um evidence_id auditável.

Por que duas APIs era o formato errado

O primeiro endpoint, POST /analyze, é um motor de regras determinísticas: normalização mais um catálogo de padrões de injeção (pi-direct e companhia). Responde em microssegundos, é trivialmente auditável e, quando uma regra dispara, quase nunca erra. Mas regras só pegam o que você já viu.

O segundo endpoint, POST /v30/analyze, roda o v29: um transformer multilíngue, exportado para ONNX e quantizado em int8, que pontua o texto bruto e bloqueia acima de um limiar calibrado (τ = 0,950 após a passada de endurecimento multilíngue). A troca é outra: ~15–18 ms p50 em CPU, cobertura muito melhor, e ainda assim longe do custo e da latência de um guard baseado em LLM.

Os dois são produtos honestos. Juntos, eram uma interface ruim. Os clientes precisavam saber em qual modelo de ameaça estavam para escolher endpoint a cada chamada, as cotas eram separadas e as evidências dos dois caminhos não eram diretamente comparáveis. Na prática, as pessoas usavam o caminho rápido e perdiam em silêncio a cobertura neural que estavam pagando.

Um endpoint, três cérebros

O router decide por requisição, à vista de todos:

1. Nível 1 — Regras. Normaliza, casa padrões determinísticos. Se uma regra dispara, retorna. Custo: microssegundos.
2. Nível 2 — v29 neural. Se as regras não concluem, pontua com o modelo int8. Casos claramente benignos ou claramente ataque terminam aqui.
3. Nível 3 — Deep Analyze. Só quando a pontuação do v29 cai na faixa incerta (0,50–0,935) a requisição vai para o Deep Analyze, o modelo mmBERT v8 que existe exatamente para isso: texto que parece benigno para um encoder pequeno mas merece uma segunda opinião.

A fusão do veredicto é simples de propósito: o router combina a pontuação do v29 com a do Deep Analyze e bloqueia a partir de 0,935. Cada resposta agora carrega tier (rules, advanced, deep), decided_by, latency_ms e evidence_id, para você medir seu próprio tráfego por caminho de decisão.

Deep Analyze: o nível que precisou merecer seu lugar

O Deep Analyze é nosso detector multilíngue mmBERT v8, exportado para ONNX int8 e servido numa Lambda de contêiner (3 GB de memória, 4 GB efêmeros, teto de 120 s). A quente responde em ~166 ms. Partidas a frio levam ~24 s, e é por isso que ele nunca fica na borda síncrona de um caminho desprotegido: só roda para a faixa ambígua, dentro de um orçamento duro de 6 s do router, e o router volta para o v29 se estourar.

Conseguir um modelo bom o bastante para merecer essa vaga levou mais tempo que o próprio router. Nossos posts anteriores contaram a história completa: o dataset que mentia para nós e dezessete treinos fracassados em que o modelo pontuava 0,498–0,509 em tudo porque a perda nunca via um rótulo. A correção foi ordinária — treino supervisionado ponta a ponta, split congelado, parar de ajustar no teste — e o resultado foi uma porta com FPR 0,82%, FNR 8,20%, AUROC 0,9958 no split de teste congelado, a 17,9 ms p50 em int8.

O Deep Analyze vai além na fatia mais difícil. Nas nossas sondas internas ele separa entradas adversariais a 0,9999999998, enquanto texto benigno porém suspeito fica em 1,35e-7. Não são probabilidades de marketing; são os números que o nosso próprio gateway vê quando decide, registrados com um evidence_id para cada bloqueio.

Implantar sem quebrar a produção

Um router na frente de cada requisição é um deploy assustador. Fizemos em três movimentos: primeiro o modo sombra, em que o caminho em produção e o router decidiam e só comparávamos — o Deep Analyze pontuando ao lado do veredicto de produção sem tocá-lo. Depois o canary em 50% atrás do alias, com alarmes do CloudWatch em erros de Lambda, fail-opens do Deep e latência p99, ligados ao SNS. Depois 100%.

As garantias chatas são o ponto: o rollback é trocar a versão do alias, o router tem 39/39 testes unitários incluindo uma suíte de equivalência que prova que o caminho roteado devolve o mesmo veredicto da chamada direta, e o fail-open é exercitado em teste, não torcido.

Assinaturas: limites maiores e cotas explícitas de DeepAnalyze

As assinaturas antigas contavam um único balde de chamadas e deixavam o Deep Analyze como experimento. O novo canon dá a cada nível uma cota padrão e uma cota DeepAnalyze no mesmo lugar, e sobe os tetos:

A retenção não muda: planos pagos armazenam zero entrada. Guardamos o veredicto, o nível e os hashes necessários para o Evidence Vault, com 90 dias de retenção. O nível Contributor — grátis para sempre — é o único que armazena entrada, anonimizada, e só porque você aceita a telemetria comunitária para treinar o modelo. Se você usa qualquer plano pago, seus prompts não estão no nosso conjunto de treino. Nunca.

O que muda para você

Se você chamava /v30/analyze, nada quebra: mesmo caminho, mesma forma de resposta, agora com tier e decided_by mostrando de onde veio cada veredicto. Se você chamava /analyze esperando só regras, migre para /prod/analyze para o caminho determinístico — ou fique, e ganhe o router completo pelo mesmo preço. Uma chave, um endpoint, três cérebros.

Se você quer ver o caminho de decisão no seu próprio tráfego antes de confiar nele, é para isso que serve o teste gratuito de 48 h: um POST, uma chave de API e evidência para cada bloqueio.