De deux API à un Smart API Router : règles, une porte neuronale et Deep Analyze derrière un seul endpoint

IngénierieJohn Silver9 min de lecture

Mis à jour le 2026-10-17 : signalé comme article historique, avec un renvoi à l'architecture actuelle ; limites d'abonnement et chiffres devenus caducs retirés.

Article historique. Il décrit le router tel qu'il était le 2026-09-12 : le modèle neuronal, le niveau Deep Analyze et les limites d'abonnement de cette date. Depuis le 12 octobre 2026, la vérification cloud utilise Galvanize 2 (seuil 0,662), et les niveaux du router sont rules, advanced et deep. Pour les abonnements et limites actuels, voir les tarifs.

Jusqu'à cette semaine, zn exposait deux API. Vous en choisissiez une par requête, et les limites de votre abonnement étaient réparties entre les deux. C'était une taxe de conception sur chaque intégration : le mauvais choix donnait un faux sentiment de sécurité, et le bon choix exigeait de comprendre nos entrailles mieux que vous ne devriez avoir à le faire.

Aujourd'hui, il n'y a qu'un seul endpoint. POST /analyze route chaque requête à travers trois couches progressives — règles déterministes, porte neuronale et Deep Analyze — et vous dit laquelle a décidé.

TL;DR

  • POST /analyze est désormais un Smart API Router (SAR) : Niveau 1 règles déterministes (<50 µs), Niveau 2 neuronal int8 (~15–18 ms), Niveau 3 Deep Analyze (mmBERT v8, ~166 ms à chaud) pour la bande ambiguë.
  • /v30/analyze reste un alias de compatibilité. Le chemin produit POST /prod/analyze reste règles-seules pour ceux qui veulent la porte à latence ultra-faible.
  • Le router est fail-open : si Deep Analyze expire (budget de 6 s) ou échoue, vous recevez quand même le verdict neuronal. Une passerelle de sécurité ne doit jamais devenir la panne.
  • Les limites des formules ont changé depuis la publication de cet article. Les limites actuelles sont sur la page des tarifs.
  • Nous ne conservons pas le texte que vous envoyez, sur aucun abonnement, sauf si vous activez le mode Contributor. Nous gardons des métadonnées de preuve, dont une empreinte SHA-256 de l'entrée, pendant 90 jours. La réponse inclut tier, decided_by, latency_ms et un evidence_id auditable.

Pourquoi deux API, c'était la mauvaise forme

Le premier endpoint, POST /analyze, est un moteur de règles déterministes : normalisation plus un catalogue de motifs d'injection (pi-direct et compagnie). Il répond en microsecondes, il est trivialement auditable, et quand une règle se déclenche elle a presque toujours raison. Mais les règles ne rattrapent que ce que vous avez déjà vu.

Le second endpoint, POST /v30/analyze, exécute une porte neuronale : un transformer multilingue, exporté vers ONNX et quantifié en int8, qui note le texte brut et bloque au-dessus d'un seuil calibré (τ = 0,950 après la passe de durcissement multilingue). Le compromis est différent : ~15–18 ms p50 sur CPU, une couverture bien meilleure, et toujours loin du coût et de la latence d'un guard basé sur un LLM.

Les deux sont de bons produits, et honnêtes. Ensemble, ils formaient une mauvaise interface. Les clients devaient savoir dans quel modèle de menace ils se trouvaient pour choisir un endpoint à chaque appel, les quotas étaient séparés et les preuves des deux chemins n'étaient pas directement comparables. En pratique, les gens utilisaient le chemin rapide et perdaient silencieusement la couverture neuronale qu'ils payaient.

Un endpoint, trois cerveaux

Le router décide par requête, à découvert :

  1. Niveau 1 — Règles. Normaliser, chercher des motifs déterministes. Si une règle se déclenche, retour. Coût : microsecondes.
  2. Niveau 2 — neuronal. Si les règles ne concluent pas, noter avec le modèle int8. Les cas clairement bénins ou clairement hostiles s'arrêtent ici.
  3. Niveau 3 — Deep Analyze. Seulement quand le score neuronal tombe dans la bande incertaine (0,50–0,935), la requête part vers Deep Analyze, le modèle mmBERT v8 qui existe exactement pour ça : un texte qui paraît bénin à un petit encodeur mais mérite un second avis.

La fusion du verdict est simple à dessein : le router combine le score neuronal et le score Deep Analyze et bloque à partir de 0,935. Chaque réponse porte désormais tier (rules, advanced, deep), decided_by, latency_ms et evidence_id, pour que vous mesuriez votre propre trafic par chemin de décision.

Avant : deux endpoints séparés. Après : un endpoint Analyze routé par le Smart API Router entre règles, neuronal et Deep AnalyzeLe panneau supérieur montre les anciens POST /analyze règles et POST /v30/analyze neuronal obligeant le client à choisir. Le panneau inférieur montre un unique POST /analyze routé par le Smart API Router vers le Niveau 1 règles sous 50 microsecondes, le Niveau 2 int8 environ 15 millisecondes et le Niveau 3 Deep Analyze mmBERT environ 166 millisecondes à chaud, avec un budget fail-open de 6 secondes et une réponse contenant tier, latence et evidence id.FIGURE 1 : DEUX ENDPOINTS → UN SMART API ROUTERAVANT · CHOISIR PAR REQUÊTEPOST /analyzeRègles déterministes · <50 µs · couverture par motifsPOST /v30/analyzeneuronal int8 · ~15–18 ms · quotas séparésAPRÈS · UN SEUL APPELPOST /analyze→ SMART API ROUTERNIVEAU 1 · RÈGLES<50 µs · déterministemotifs exacts, auditableNIVEAU 2 · NEURONAL~15–18 ms · ONNX int8multilingue, forte couvertureNIVEAU 3 · DEEP ANALYZE~166 ms à chaud · mmBERT v8seulement la bande 0,50–0,935réponse : verdict · tier · decided_by · latency_ms · evidence_idfail-open : Deep a 6 s, puis le verdict neuronal est renvoyé

Deep Analyze : le niveau qui a dû gagner sa place

Deep Analyze est notre détecteur multilingue mmBERT v8, exporté vers ONNX int8 et servi depuis une Lambda conteneur (3 Go de mémoire, 4 Go éphémères, plafond de 120 s). À chaud, il répond en ~166 ms. Les démarrages à froid prennent ~24 s, et c'est pourquoi il n'est jamais sur le bord synchrone d'un chemin non protégé : il ne tourne que pour la bande ambiguë, dans un budget dur de 6 s du router, et le router retombe sur le verdict neuronal s'il dépasse.

Obtenir un modèle assez bon pour mériter cette place a pris plus de temps que le router lui-même. Nos articles précédents ont raconté l'histoire complète : le dataset qui nous mentait et dix-sept entraînements ratés où le modèle notait 0,498–0,509 sur tout parce que la perte ne voyait jamais d'étiquette. Le correctif était ordinaire — entraînement supervisé de bout en bout, split gelé, arrêt du réglage sur le test — et le résultat fut une porte fonctionnelle sur le split de test gelé.

Échelle de décision et budget de latence en échelle logarithmique : règles sous 50 microsecondes, la porte neuronale environ 15 millisecondes, Deep Analyze environ 166 millisecondes, budget du router 6 secondesAxe logarithmique de 10 microsecondes à 10 secondes. La barre du Niveau 1 règles finit près de 50 microsecondes. Celle du Niveau 2 neuronal près de 15 millisecondes. Celle du Niveau 3 Deep Analyze près de 166 millisecondes. Une ligne pointillée marque le budget fail-open de 6 secondes. Deep Analyze ne tourne que si le score neuronal tombe dans la bande 0,50 à 0,935 ; 0,935 ou plus bloque.FIGURE 2 : ÉCHELLE DE DÉCISION · BUDGET (ÉCHELLE LOG)bande neuronale 0,50–0,935 → Deep Analyze · score ≥0,935 → bloquerNIVEAU 1 · RÈGLEScorrespondance concluante~50 µsNIVEAU 2 · NEURONALONNX int8, p50~15–18 msNIVEAU 3 · DEEP ANALYZEmmBERT v8, à chaud~166 msLIMITE FAIL-OPEN 6 s10 µs100 µs1 ms10 ms100 ms1 s10 sChaque niveau journalise tier, decided_by, latency_ms et evidence_id.Fail-open : un timeout de Deep ne devient jamais une requête échouée.

Le déployer sans casser la production

Un router devant chaque requête, c'est un déploiement qui fait peur. Nous l'avons fait en trois temps : d'abord le mode ombre, où le chemin en production et le router décidaient tous les deux et nous comparions seulement — Deep Analyze notait à côté du verdict de production sans y toucher. Puis le canary à 50 % derrière l'alias, avec des alarmes CloudWatch sur les erreurs Lambda, les fail-opens de Deep et la latence p99, reliées à SNS. Puis 100 %.

Les garanties ennuyeuses sont le point : le rollback est un changement de version d'alias, le router a 39/39 tests unitaires dont une suite d'équivalence qui prouve que le chemin routé renvoie le même verdict que l'appel direct, et le fail-open est exercé en test, pas espéré.

Abonnements

Les limites d'abonnement décrites à la publication de cet article ont changé. Voir les tarifs pour les abonnements et quotas actuels.

La rétention ne change pas : l'entrée n'est conservée qu'en mode Contributor. Nous conservons le verdict, le niveau et les hashes nécessaires à l'Evidence Vault, avec 90 jours de rétention. Le mode Contributor, sur option, est le seul cas où l'entrée est stockée, anonymisée, et seulement parce que vous acceptez la télémétrie communautaire pour l'entraînement du modèle. Si vous n'activez pas le mode Contributor, nous n'utilisons pas vos prompts pour l'entraînement. (Modifié le 15 octobre 2026.)

Ce qui change pour vous

Si vous appeliez /v30/analyze, rien ne casse : même chemin, même forme de réponse, désormais avec tier et decided_by qui indiquent d'où vient chaque verdict. Si vous appeliez /analyze en attendant uniquement les règles, passez à /prod/analyze pour le chemin déterministe — ou restez, et obtenez le router complet au même prix. Une clé, un endpoint, trois cerveaux.

Si vous voulez voir le chemin de décision sur votre propre trafic avant de vous y fier, le plan Free (10 000 appels par mois) sert à cela : un POST, une clé d'API et une preuve pour chaque blocage.

Mis à jour le 14 octobre 2026 : la formulation sur le traitement des données a été reformulée pour décrire ce que font aujourd'hui le paquet et l'API.

Partager