Aller au contenu
Blogue Krizaka

13

Sovkora v2 : l'architecture qu'on construit

23–26 oct. 202616 min de lecture

Ce que j'ai affronté, Un audit qui proposait d'empiler des cadres, et un moteur qu'on ne savait plus résumer; Ce qu'on a construit, un cœur qu'on possède, des bords qu'on branche, et la liste honnête de ce qui manque

Une longue salle de brique aux arcades et aux lampes suspendues, un petit canard jaune qui marche vers le fond

Quand on me demande ce qu'est Orazaka techniquement, je réponds souvent par une liste de dépôts. C'est une mauvaise réponse. Une liste ne dit pas ce qu'on construit, ni pourquoi.

Le 26 octobre, j'ai fait relire l'architecture par un audit externe, un modèle de langage à qui on a donné le contexte. Il proposait une architecture hybride : garder certaines pièces, en remplacer d'autres par des frameworks connus. Une partie était juste. Une autre décrivait comme existantes des choses qu'on n'a pas construites. On l'a vérifié dans le code, ligne par ligne, puis une contre-expertise a resserré ce qui restait. Il en est sorti une décision, l'ADR-092, et une phrase :

On possède le cœur, on branche les bords.

Ce chapitre explique cette phrase. Il dit aussi, sans arrondir, où on en est aujourd'hui.

Ce qu'on possède, ce qu'on branche

Un moteur d'IA, c'est beaucoup de pièces. La plupart existent déjà ailleurs, bien faites : un protocole pour parler aux outils, un broker de messages, des bibliothèques pour appeler un modèle. Les réécrire ne nous apprendrait rien et nous coûterait des années. Mais quelques pièces font qu'Orazaka est Orazaka. Celles-là, on les garde.

Ce qu'on possède :

  • L'orchestration. Une demande devient un graphe d'étapes typées. Chaque étape a un contrat de sortie (ce qu'elle doit rendre) et une politique de contrôle (comment on juge ce qu'elle a rendu).
  • La boucle de contrôle. Ce qui décide si une sortie est bonne, et quoi faire si elle ne l'est pas.
  • Le bail du GPU. Qui a le droit d'utiliser la carte graphique d'une machine, et pendant combien de temps.
  • Le pilotage en direct. Changer une étape pendant qu'un run avance, sans tout refaire.
  • L'accès. Qui a le droit de lire quoi, vérifié au moment où l'assistant cherche et au moment où il appelle un outil (ADR-091).

Ce qu'on branche tel quel :

  • MCP, le protocole des outils, par le SDK officiel, à travers Spring AI. On n'implémente pas le protocole.
  • RabbitMQ et l'outbox, pour que le travail parte de façon fiable, dans la même transaction que l'état du run.
  • Le worker média en Python, pour l'image et la vidéo. Il reste en Python. Il ne devient pas du Java.

Entre les deux, il y a Spring AI 2, la bibliothèque qui parle aux fournisseurs de modèles. On s'en sert, mais derrière nos ports : un seul module d'adaptation la connaît. Le domaine, lui, doit être du Java 21 pur.

Ce qu'on refuse : LangChain4j, LangGraph4j, un deuxième moteur de workflow, et StructuredTaskScope tant que c'est une API en préversion. La raison est la même à chaque fois : deux façons de faire la même chose, c'est deux trains de mises à jour et deux endroits où l'état d'un run peut diverger. On a déjà payé la migration vers Spring AI 2. On a déjà un graphe d'étapes, avec sa saga, ses approbations et ses crédits réservés. On n'en veut pas un second.

On possède

  • L'orchestration : un graphe d'étapes typées
  • La boucle de contrôle
  • Le bail GPU
  • Le pilotage en direct
  • L'accès, vérifié à la recherche et à l'outil

On branche

  • MCP, par le SDK officiel
  • RabbitMQ et l'outbox
  • Le worker média en Python
  • Spring AI 2, derrière nos ports

On refuse

  • LangChain4j
  • LangGraph4j
  • Un second moteur de workflow
  • StructuredTaskScope tant qu'il est en préversion
On possède le cœur, on intègre les bords (ADR-092) : ce qu'Orazaka garde, ce qu'il branche tel quel, ce qu'il refuse.

Une demande, de bout en bout

Le workspace orazaka assemble 20 dépôts : des briques Krizaka réutilisables (utilisateurs, notifications, facturation), les fondations (contrats, edge), le moteur d'IA, les clients (web, mobile, ligne de commande), le worker média et les packs.

Une correction d'abord, parce que je le disais mal. Le « moteur d'IA » n'est pas un service. C'est une bibliothèque, orazaka-ai-engine, que les services embarquent : le client d'IA, la chaîne d'intercepteurs, les outils. Le graphe d'étapes, lui, vit dans le service Studio.

Voici le chemin d'une demande, dans l'ordre.

Le chemin d'une demande dans Orazaka
  1. Le client (web, mobile ou un produit)Le web passe par son serveur intermédiaire (BFF), le mobile par un token, un produit comme Yomizaka par une clé de service. Personne n'appelle un service directement.
  2. L'edge (la porte unique)Il échange une clé d'API contre une session, applique CORS et la traçabilité, et envoie la route au bon service.
  3. Le Studio (le graphe d'étapes)Il tient les packs, les installations et les runs. Il fait avancer le plan d'un Studio étape par étape, avec compensation si une étape échoue.
  4. RabbitMQ et l'outbox (interactif ou batch)Le travail est écrit dans la même transaction que l'état du run, puis publié dans une file. Une ligne de la base dit laquelle.
  5. Le job-service et le worker (du code ou un GPU)Il vide la file et confie le travail à l'exécuteur que la même ligne désigne : du code dans le service, ou le worker média.
  6. La facturation (réserver, régler, libérer)Chaque run a réservé ses crédits avant de partir. À la fin, on règle ce qui a tourné et on libère le reste.

Le routage est dans la base. Une capacité est une ligne : routing_key dit où le travail va, handler_key dit quel code l'exécute. Avant, le code devinait la file avec une chaîne de contains() sur un nom, et une capacité inconnue partait en silence vers la mauvaise file. Aujourd'hui, un test de gouvernance arrête la construction si une ligne n'a pas d'exécuteur.

La boucle de contrôle

C'est la pièce qui compte le plus pour moi, et celle qui a le plus de travail devant elle.

L'idée est simple. Un modèle produit une sortie. Avant de la donner à quelqu'un, on la juge. Et on ne demande pas à un modèle ce qu'une règle peut vérifier. Voici l'ordre visé, pour chaque étape :

La boucle de contrôle visée pour une étape : les règles avant les modèles, une personne en dernier
  1. Vérifications déterministes (d'abord, sans modèle)Le schéma est respecté, le fichier existe et se lit, la durée et les proportions sont bonnes. Pas de token. Cible : moins de 10 ms.
  2. Un juge sémantique (un score de dérive)Un modèle lit la sortie et dit à quel point elle s'écarte de ce qui était demandé. Il ne tourne jamais sur une sortie que les vérifications ont rejetée.
  3. Une correction (au plus K essais)Au-dessus du seuil, on régénère en disant au modèle ce qui ne va pas. Une mémoire des erreurs refuse une correction qui répète un échec déjà vu.
  4. Un humain (en dernier)Après K essais, ou dès le départ quand la politique le dit, la décision revient à une personne.

Chaque jugement est un verdict typé : Validated, DriftAdjustment ou HumanEscalation. Ce n'est pas un détail de code. Un verdict typé s'écrit dans le journal du run, se compte, se relit. Les seuils, K et les politiques sont des lignes de la base, que l'administrateur règle, pas des if dans le Java.

La loi 25. La Loi sur la protection des renseignements personnels dans le secteur privé, à son article 12.1, encadre les décisions fondées exclusivement sur un traitement automatisé. La personne concernée doit pouvoir faire réviser la décision par quelqu'un. Le verdict HumanEscalation est ce chemin. Il est enregistré avec le run, la raison, la personne qui a décidé, l'heure et l'action prise, dans la même transaction que l'état du run. Une politique peut rendre l'escalade obligatoire pour une étape qui décide quelque chose à propos d'une personne. Une obligation de la loi devient une fonction du moteur.

Le GPU d'une machine

Sur le Mac, et sur un serveur avec une seule carte, deux choses veulent la mémoire du GPU en même temps : Ollama, qui garde des modèles de texte chargés, et le worker média, qui charge un modèle vidéo de plusieurs dizaines de gigaoctets. Si les deux se battent, la machine rame ou un des deux tombe.

La réponse visée est un bail par appareil. Celui qui veut le GPU demande un bail, avec une durée de vie et un heartbeat. Un bail dont le heartbeat s'arrête est repris. Il y a deux profils : SHARED_LIGHT, où plusieurs petits travaux partagent la carte, et EXCLUSIVE_HEAVY, pour un rendu lourd. Avant d'accorder un bail exclusif, l'arbitre demande à Ollama de libérer sa mémoire (keep_alive: 0) et vérifie sur /api/ps qu'elle est vraiment libérée. On ne fait pas confiance, on vérifie. Un petit modèle reste hors du verrou lourd, pour que l'interface continue de répondre.

Le pilotage en direct

Un run long, par exemple une vidéo en plusieurs plans, prend du temps. Pendant ce temps, on change d'avis. Refaire tout le run pour un détail coûte cher.

Le pilotage visé repose sur des liens typés entre étapes. Un lien dit ce qu'un changement en amont veut dire en aval :

  • CONTENT : l'étape suivante dépend du contenu, elle est régénérée ;
  • ASSEMBLY : seul l'assemblage, qui est déterministe, est refait ;
  • CONTINUITY : seule la boucle de contrôle est relancée sur l'étape voisine. Elle ne régénère que si la dérive dépasse le seuil, sinon elle signale « impact détecté » et laisse la personne décider.

On annule seulement la partie du graphe touchée, pas le run entier.

Qui a le droit de lire quoi

La question qui m'a fait tout relire, je l'ai posée comme ceci : si un employé demande le salaire du PDG à l'assistant, et que ce salaire est dans un document indexé, que se passe-t-il ?

Il y a deux façons de se tromper. Croire que le modèle fera attention : il ne le fera pas, un texte lu par un modèle peut contenir des ordres, et une consigne dans le prompt n'est qu'un conseil. Ou filtrer la réponse après coup, quand le passage a déjà été lu. Le contrôle doit se faire avant.

L'ADR-091 pose trois règles :

  • Celui qui demande voyage. L'identité vérifiée (l'organisation, la personne, ses rôles, ses groupes) part avec chaque recherche et chaque appel d'outil, dans un token signé. Jamais dans le corps d'une requête.
  • Le droit est dans la requête. Chaque passage indexé porte les droits de sa source. Le filtre fait partie de la recherche elle-même, avant le classement. Un passage qu'on n'a pas le droit de lire n'est jamais lu, donc il ne peut fuir ni par un extrait, ni par un compte, ni par un cache.
  • Chaque outil déclare ses rôles. Un outil qui ne déclare rien est réservé aux administrateurs. Sans identité, rien ne s'exécute.

C'est en cours de correction, avant qu'on indexe quoi que ce soit de sensible. Je ne détaille pas plus tant que ce n'est pas livré.

Les packs, et la preuve que le cœur reste générique

Un pack est un dossier : un manifeste, ses traductions, ses Studios (des plans d'étapes), parfois son worker. L'installer écrit des données : des capacités, un prix, une entrée de catalogue. Il ne change aucun code. Le moteur ne sait pas ce qu'est un bail. Il sait lancer un plan, réserver des crédits, appeler un outil, juger une sortie et garder une trace.

Comment savoir que c'est vrai, et que ça le reste ? Une règle de l'ADR-092 le dit : la preuve est un pack. Le pack de vérification de documents (orazaka-packs), celui des règles du bail, doit évoluer sans un seul changement dans le cœur. Ces règles viennent de la loi : un document n'est jugé que par un jeu de règles promu, après ses cas de référence et une relecture (ADR-089). Si un jour il faut toucher au cœur pour un produit, la pull request est refusée, et le changement va dans un port ou dans un pack.

C'est la même chose pour les médias. Il n'y a pas de module vidéo dans le cœur. Il y a le worker média et des packs qui l'utilisent.

Les produits passent par l'API, seulement. Yomizaka ne parle jamais à un modèle. Il appelle les Studios du pack sur l'edge avec une clé de service, et garde l'identifiant du run de chaque analyse : c'est la trace de ce qui a tourné. Akinaza suit la même règle. Le client commun, @krizaka/orazaka-client, lance un run avec une clé d'idempotence, lit son état et attend sa fin. Le consentement, le budget, l'audit et l'idempotence sont écrits une fois, dans le moteur. Un produit qui le contournerait devrait les réécrire, et un jour il en oublierait un.

Où on en est

Voilà la direction. Voici ce que le code dit le 26 octobre. L'audit et la contre-expertise l'ont trouvé, et je préfère l'écrire ici que le laisser découvrir.

  • Le cœur importe encore Spring AI. 52 fichiers du moteur l'importent : 36 dans le cœur, 14 dans les intercepteurs, 2 dans les outils (mesuré dans l'ADR-092). Un test ArchUnit va compter ces fichiers, et ce compte ne pourra que baisser. Pas de grand soir : on déplace une tranche à la fois vers le module d'adaptation, jusqu'à zéro.
  • Le DagCompiler du cœur est une ébauche. Deux noms de tâches écrits en dur, aucun exécuteur, et personne ne l'appelle. Le vrai graphe, c'est le plan du Studio : il a ses dépendances, son parallélisme, ses contrats de sortie et ses étapes d'approbation. L'ébauche sera supprimée.
  • La boucle de contrôle a un défaut. À chaque nouvel essai, l'intercepteur revérifiait le même texte au lieu d'en régénérer un, et après le dernier essai il servait la réponse sans qu'elle soit validée. Le correctif est fusionné depuis (sovkora-engine#117). Les verdicts typés, le score de dérive et l'escalade viennent ensuite.
  • Le bail du GPU n'existe pas encore. Rien n'appelle /api/ps aujourd'hui, et rien ne règle keep_alive. Le worker gère sa propre mémoire, c'est tout.
  • Le pilotage en direct est dessiné, pas construit (ADR-088). On sait approuver une étape, reprendre à partir d'une étape et annuler un run entier. Pas encore annuler une seule branche.
  • Le cache marche par run, pas par étape. Un run identique est servi depuis le cache. Une seule étape changée refait tout le run.
  • Le contrôle d'accès de la section précédente n'est pas fini.

Et ce que ça coûte, mesuré :

  • Un run coûte cher en requêtes, pas en temps. Un run d'une seule étape fait 37 requêtes SQL, dont environ 9 en trop. Le surcoût de la saga reste petit : un p95 de 19,2 ms après le passage par l'outbox, loin du seuil de 250 ms fixé avant de mesurer (ADR-067). Ce que l'envoi attend vraiment, c'est le relais de l'outbox : au plus 500 ms, 250 en moyenne.
  • Le GPU loué coûte même quand il dort. Le 16 octobre, un pod a tourné cinq heures avec le GPU à 0 %, pour environ 20 $. Un garde-fou l'arrête maintenant (ADR-078).
  • Un composant ne se construit jamais seul. Avec 20 dépôts, la CI clone le workspace et construit d'abord les dépendances. C'est la bonne façon d'attraper une rupture, et c'est lent.

En incubation : les Recettes

Une idée de plus, qui n'est pas construite. Elle est en incubation, en haut de la colonne.

Quand on tape un bon prompt dans le chat, on le perd. L'idée : le garder comme recette. Une recette est privée par défaut. Le moteur repère ce qui change d'une fois à l'autre (un document, une date, un montant, un nom) et en fait des variables typées. On appuie sur ▶ Play, un petit formulaire demande le document ou la date, et le run part.

Ce qui me plaît, c'est ce qu'il y a dessous. Une recette ne relance pas la décomposition de l'intention à chaque fois. Elle exécute un plan déjà compilé et versionné, le même graphe d'étapes que le reste du moteur. C'est plus rapide, le coût est prévisible, et le résultat se reproduit. Pas de deuxième moteur de workflow, là non plus.

Plus tard, une recette pourra recevoir un déclencheur (tous les lundis à 8 h, un nouveau document dans un dossier) et devenir une Routine. Elle tournera alors sous l'identité de la personne qui l'a activée, jamais sous un compte système. Ses droits seront revérifiés à chaque run, et si la boucle de contrôle demande un humain, la Routine s'arrête et attend.

Et la v3 ?

La v3 n'a ni branche, ni dépôt, ni date. Mais elle a maintenant une forme : c'est l'endroit où mènent les tranches de l'ADR-092. On ne la construira pas à côté de la v2. On y arrivera en passant les tranches au vert, l'une après l'autre, sur le moteur qui tourne déjà.

Son but reste le même : faire le même travail plus vite, pour moins cher, avec des sorties qu'on peut prouver.

Les tranches, dans l'ordre

  1. La frontière. Spring AI dans un seul module d'adaptation, le domaine en Java 21 pur, le compte ArchUnit à zéro, l'ébauche de graphe supprimée.
  2. Le verdict. D'abord le test qui reproduit le défaut de la boucle, puis les verdicts typés, le juge, les K corrections avec le diff et l'escalade.
  3. L'arbitre du GPU. Le bail par appareil, l'éviction vérifiée, les travaux regroupés par modèle pour ne pas recharger des dizaines de gigaoctets entre deux clips. Le worker dit sa mémoire et ses modèles chargés.
  4. Le pilotage. Les commandes entre deux étapes, les liens typés, l'annulation d'une seule branche.
  5. Le cache par étape. Une clé par étape, calculée à partir de ses entrées, pour qu'un changement ne refasse que les branches touchées.

Les trois dernières répondent directement aux douleurs mesurées. Le GPU chaud et l'arbitre attaquent le chargement des modèles. Le pilotage et des événements au lieu de relire l'état attaquent l'attente. Le cache par étape attaque le travail refait pour rien.

Comment on saura que c'est mieux

« Plus performant » sans chiffre, c'est une impression. La méthode existe déjà : la mesure M0 a fixé son seuil avant de mesurer, et la décision a suivi le chiffre. La v3, ce sont ces chiffres devenus des budgets, vérifiés dans la CI.

BudgetAujourd'huiCible
Fichiers qui importent Spring AI hors de l'adaptateur52, mesuré0
Requêtes SQL, run d'une étape37, mesuré28 ou moins, sans les lectures en double
Surcoût de la saga, p9519,2 ms, mesurépas plus, et toujours sous 250 ms
Attente de l'envoi250 ms en moyenne, 500 au plus, mesuréaucune relève périodique sur ce chemin
Vérifications déterministes d'une étapepas mesurésous 10 ms
Chargement de Wan 2.2 TI2V 5B sur un H10032,1 s, mesurésous 12 s
GPU loué au reposcinq heures à 0 % le 16 octobre, mesuré0 $
Une étape changée dans un runtout le run refaitseulement les branches touchées

Chaque budget est un cliquet : il part du chiffre d'aujourd'hui, et il ne peut que baisser. C'est le même mécanisme que pour Spring AI dans le cœur.

Ce qu'on refuse

  • Une réécriture. Je connais la tentation. On voit 52 fichiers mal placés, une ébauche inutile, une boucle qui ne régénère pas, et on a envie de tout reprendre au propre. En juillet, on a découpé le monolithe d'Orazaka par étapes, chacune verte avant la suivante (ADR-032). La v3 suit le même chemin.
  • Optimiser sans mesurer. Les 9 requêtes en trop sont connues depuis la première mesure. On les a laissées, parce que le chiffre tenait son seuil. Elles partiront avec le budget qui les compte.
  • Appeler propriété intellectuelle ce qui n'est pas construit. L'arbitre du GPU est prévu. Tant qu'il n'est pas là, je ne le vends pas.

Ce que j'en retiens : une architecture n'est pas un schéma qu'on dessine une fois. C'est une ligne qu'on tient. Ce qui fait la valeur du moteur, on le possède et on le prouve. Le reste, on le branche, et on le garde derrière une porte qu'on peut changer.

Chapitre 13

Résultats

dépôts dans le workspace d'Orazaka

20

Une demande, de bout en bout

fichiers du moteur qui importent encore Spring AI, un compte qui ne peut que baisser

52

Où on en est

requêtes SQL pour un run d'une seule étape

37

Où on en est

p95 de ce run, après le passage par l'outbox

19,2 ms

Où on en est