Architecture générale de la Box IA

L'essentiel

• La Box IA est une seule machine Linux sur site qui héberge tout : interface web, authentification, runtime LLM, pipeline RAG, stockage des documents, journaux et sauvegardes. Aucune donnée ne sort du réseau de l'entreprise.
• L'architecture est en couches (accès, application, IA, données, exploitation), chaque brique tournant dans un conteneur Docker orchestré par Docker Compose.
• Le contrat entre briques est l'API OpenAI-compatible : l'interface ne connaît pas le runtime, ce qui permet de remplacer llama-server par vLLM ou un autre moteur sans toucher au reste.
• Les permissions s'appliquent avant la recherche : le RAG ne cherche que dans les documents que l'utilisateur connecté a le droit de voir (décision ADR-003).
• Les choix de composants présentés ici sont des candidats : le runtime, l'interface et la base vectorielle restent à valider par des tests (statut hypothesis).

Architecture simple

Vue destinée à un dirigeant ou à un utilisateur : cinq blocs, un seul sens de lecture.

L'utilisateur pose une question dans son navigateur. L'interface cherche les passages pertinents dans les documents autorisés, les transmet au modèle avec la question, et affiche une réponse accompagnée des sources. Tout se passe sur la Box.

Architecture complète

Vue destinée à l'installateur et au responsable informatique. Chaque sous-graphe correspond à une couche ; chaque nœud correspond à un conteneur ou à un composant système.

Lecture du schéma :

• Couche accès : un seul point d'entrée chiffré (reverse proxy TLS) et un fournisseur d'identité qui porte les comptes, les groupes et le MFA.
• Couche application : l'interface de chat et l'API qui expose le modèle. Dans la V1, l'interface (Open WebUI) intègre elle-même l'orchestration RAG ; l'« API IA » est alors l'endpoint OpenAI-compatible de llama-server, éventuellement derrière un routeur.
• Couche IA : le runtime qui charge le modèle en mémoire unifiée, plus les modèles d'embedding et de reranking.
• Couche données : la base vectorielle (index des passages), le stockage des documents sources et la base applicative (utilisateurs, conversations, métadonnées).
• Couche exploitation : journaux d'audit, métriques et sauvegardes chiffrées vers un support externe.

Composants

Principes d'architecture

1. Tout sur site. Le modèle, l'index, les documents, les journaux et les sauvegardes restent dans les locaux (ou sur un support contrôlé par l'entreprise). Aucun appel vers un service d'IA externe. C'est la promesse du produit et la condition du secret professionnel. Voir Vision et RGPD.
2. Permissions avant recherche. Le filtre de droits s'applique à la requête vectorielle, jamais après coup sur les résultats. Un utilisateur ne peut pas obtenir, même par recoupement, un passage d'un dossier qu'il n'a pas le droit d'ouvrir. Voir Permissions et la décision ADR-003.
3. API OpenAI-compatible comme contrat. L'interface parle au runtime uniquement via /v1/chat/completions, /v1/embeddings et équivalents. Le runtime est interchangeable (llama-server aujourd'hui, vLLM ou autre demain) sans modifier l'interface, les scripts ni la documentation utilisateur.
4. Un conteneur par brique, orchestrés par Docker Compose. Pas de Kubernetes : une machine, un fichier compose.yaml, des volumes nommés, des réseaux internes. L'installation doit être reproductible en une commande.
5. Un seul point d'entrée TLS. Seul le reverse proxy expose un port sur le réseau du cabinet. Tous les autres services écoutent sur des réseaux Docker internes.
6. Observabilité par défaut. Chaque requête laisse une trace (qui, quand, quelles sources, quel modèle), et la machine remonte ses métriques (GPU, mémoire, températures, latence). Sans cela, ni l'audit ni le support ne sont possibles.
7. Formats ouverts et réversibilité. Modèles au format GGUF, données dans PostgreSQL, documents inchangés à leur emplacement d'origine, configuration versionnée en texte. Le client peut reprendre la main ou changer de prestataire.
8. Sobriété. Une seule machine, un seul modèle chargé à la fois pour le chat, des services légers. La mémoire unifiée de 128 Go est la ressource rare : elle est budgétée explicitement (voir Box v1).

Flux d'une requête

Séquence nominale d'une question posée dans l'interface, avec RAG activé.

Points à retenir :

• Les étapes 3 et 7 sont les garanties de confidentialité : l'identité est vérifiée avant toute recherche, et la recherche est filtrée à la source.
• Les étapes 5, 9 et 10 passent toutes par le même contrat OpenAI-compatible, ce qui rend le runtime remplaçable.
• Le temps ressenti dépend surtout de l'étape 10 : TTFT puis débit en tokens par seconde. Voir Multi-utilisateurs.
• Le journal d'audit (étape 12) doit enregistrer les sources retournées, pas seulement la question : c'est ce qui permet de prouver, a posteriori, qu'aucun dossier interdit n'a été consulté.

Variantes

V1 minimale (cible du POC)

• Comptes locaux dans Open WebUI, groupes gérés à la main.
• Documents importés dans les « knowledge bases » d'Open WebUI, un espace par dossier ou par client.
• Un seul modèle de chat, un modèle d'embedding, reranker optionnel.
• Sauvegarde sur disque externe, monitoring minimal (Netdata ou équivalent).
• Convient à un cabinet de 5 à 10 personnes sans annuaire d'entreprise. Détail : Box v1.

V2 avec IdP externe et connecteurs

• Authentification par SSO (OIDC) via Authentik ou Keycloak, fédérée à Entra ID ou Google Workspace si le cabinet en dispose ; groupes synchronisés.
• Connecteurs vers le partage de fichiers existant (SMB, Nextcloud, SharePoint) avec synchronisation des ACL : les droits du système de fichiers deviennent les droits du RAG.
• Plusieurs modèles servis (chat, raisonnement, vision), routage par usage.
• Monitoring complet avec alertes, sauvegardes 3-2-1 vers un site distant.
• Accès distant via VPN WireGuard. Voir Réseau.

Ce qui reste ouvert

• Q-001Combien d'utilisateurs simultanés la Box peut-elle réellement servir ?HauteOuverte
• Q-002Quel runtime d'inférence est le plus performant sur AMD Strix Halo ?HauteEn cours
• Q-003Quelle quantification retenir pour le modèle principal ?MoyenneOuverte
• Q-004pgvector ou Qdrant pour la base vectorielle ?HauteOuverte
• Q-005Open WebUI est-il suffisant comme interface, ou faut-il LibreChat ou une interface propriétaire ?MoyenneEn cours
• Q-006Faut-il monter les SSD en miroir (RAID 1) ?MoyenneOuverte
• Q-007Quelle distribution Linux pour la Box ?MoyenneOuverte
• Q-008Vulkan (RADV) ou ROCm (HIP) pour llama.cpp sur Strix Halo ?HauteOuverte

Décisions

• ADR-006Tenir le dossier de référence en Markdown versionné dans GitLe contenu vit dans content/ en Markdown + frontmatter YAML (un fichier = une information), rendu par Next.js ; pas de base de données en V1.
• ADR-005Utiliser Open WebUI comme interface du prototype, avec un RAG externe pour les permissionsOpen WebUI (version corrigée ≥ 0.9.0) est l'interface du prototype et du POC. Le RAG multi-dossiers avec permissions n'utilise pas la fonction « knowledge » interne mais un service RAG externe branché en pipeline. LibreChat reste l'alternative évaluée.
• ADR-004Démarrer avec llama.cpp (llama-server) comme runtime d'inférenceLe prototype utilise llama-server (llama.cpp) derrière une API OpenAI-compatible. Le backend (Vulkan ou ROCm) sera choisi par benchmark (Q-008). vLLM/SGLang sont évalués en second temps.
• ADR-003Appliquer les permissions documentaires avant ou pendant la recherche RAG, jamais aprèsChaque chunk porte ses ACL en métadonnées ; toute recherche vectorielle ou lexicale est pré-filtrée par ces ACL à partir de l'identité authentifiée ; une seconde barrière est imposée par le moteur (filtre JWT Qdrant ou RLS PostgreSQL).
• ADR-002Retenir le Framework Desktop Ryzen AI Max+ 395 / 128 Go comme machine candidateLe Framework Desktop (Ryzen AI Max+ 395, 128 Go) est la machine candidate pour le prototype. La décision d'en faire la base du produit sera prise après benchmarks (ADR à venir).
• ADR-001Utiliser Linux comme système du serveur IALe serveur est un Linux (distribution à choisir, voir Q-007) ; toute l'interaction utilisateur passe par le navigateur.