Résumé
GGUF Loader est une application de bureau open source, prioritaire à la confidentialité, qui rend l'inférence locale de grands modèles de langage accessible aux utilisateurs non techniques. Construite sur PySide6 avec llama.cpp comme unique moteur d'inférence, elle charge n'importe quel modèle GGUF — des quantisations légères de 1,5 Go aux poids de classe frontière de 40 Go — et propose le chat, un mode agentique piloté par une machine à états LangGraph avec sept outils sandboxés et une approbation avant exécution, la recherche documentaire sans récupération et le résumé de dossiers entiers, le tout sans aucune dépendance réseau. Le projet est développé en open source depuis juillet 2025, a atteint la v2.2.0 en août 2026, et est distribué à la fois comme application de bureau et comme paquet PyPI ggufloader. Ce rapport documente l'architecture en couches du système, le moteur d'inférence, la boucle agentique, le modèle de sécurité, le conditionnement, et les dix principes de conception qui gouvernent son ingénierie.
Mots-clés : inférence locale ; llama.cpp ; GGUF ; quantification ; LangGraph ; IA agentique ; utilisation d'outils ; informatique respectueuse de la vie privée ; intervention humaine
1. Introduction
Faire fonctionner un LLM open-weight capable sur son propre matériel a historiquement exigé d'assembler un système à partir de pièces : choisir un modèle, sélectionner une quantification, configurer un runtime, jongler avec le déchargement CPU/GPU et — pour des réponses fondées — bricoler une récupération à la main. La plupart des praticiens abandonnent et acheminent leurs données privées vers une API cloud. GGUF Loader existe pour réduire toute cette pile à une seule opération de bureau, consciente du matériel.
La thèse du projet est que le modèle de classe 7B est le véritable utilisateur : invites, schémas d'outils, logique de réessai et valeurs par défaut sont réglés pour les petits modèles locaux plutôt que pour les API de pointe. Ce rapport décrit comment cette thèse est réalisée dans le moteur d'inférence (§4), la boucle agentique (§5), le fondement documentaire sans base vectorielle (§6), le modèle de confidentialité et de sécurité (§7) et la distribution (§8), et conclut avec la feuille de route d'architecture explicite du projet sur 12 mois (§11).
2. Contexte et travaux connexes
2.1 GGUF et llama.cpp
Le format GGUF, introduit par llama.cpp [1], est le conteneur de facto des modèles open-weight quantifiés, encodant poids, tokenizer et métadonnées dans un seul fichier. La quantification (Q4_K_M, Q5_K_M, etc.) compresse les poids à 4–8 bits, échangeant une petite perte de qualité contre un important gain de mémoire et de débit — c'est ce qui rend les modèles de 7 à 70B réalisables sur du matériel grand public. llama.cpp [1] fournit le runtime C/C++ portable et hautement optimisé ; llama-cpp-python [2] l'expose à Python et constitue le seul binding moteur utilisé par GGUF Loader.
2.2 Frameworks agentiques et utilisation d'outils
Le style raisonnement-et-action (ReAct) [3] a établi le schéma d'entrelacement du raisonnement du modèle avec des appels d'outils. LangGraph [4] fournit une abstraction de graphe de bas niveau — état typé, nœuds, arêtes, routage conditionnel, point de contrôle et intervention humaine via interrupt() — devenue un substrat courant pour les boucles agentiques de production. GGUF Loader adopte délibérément LangGraph plutôt que de bricoler sa boucle : l'exécution pointée et les interruptions sont des exigences, pas des commodités (§5).
2.3 Logiciel local d'abord
Un nombre croissant de systèmes — du système RAG juridique Lawyer Assistant [5] à divers assistants embarqués — affirme que la gouvernance des données, la déterminisme de l'infrastructure et l'économie prévisible sont des propriétés qui valent l'effort d'ingénierie. La contribution de GGUF Loader est de conditionner ces propriétés dans un produit de bureau à installation unique avec une interface non experte, plutôt qu'une chaîne d'outils pour développeurs.
3. Architecture du système
3.1 Conception en couches
Le code est divisé en trois couches à dépendance stricte :
| Couche | Contenu | Règle |
|---|---|---|
core/ | Abstraction du moteur, graphe agentique, registre d'outils, extraction de texte, recherche | Python pur, sans Qt — tout testable sans GUI |
services/ | Ponts Qt (modèle, chat, agent, approbation, mémoire, réglages, session) | Un service par préoccupation ; exécution sur threads de travail |
ui/ | Fenêtre principale, panneau de chat, panneau agent, boîte de réglages, chat flottant | Rendu fin ; transmet l'intention de l'utilisateur aux services |
3.2 Threading et schéma de travail
Tout travail bloquant — chargement du modèle, génération de chat, étapes agentiques — s'exécute sur des threads de travail dédiés, avec des signaux transmis au thread de l'interface. Le modèle de threading garantit que l'interface ne gèle jamais : chaque opération de longue durée diffuse des événements de progression, et chaque opération est annulable. Un contrat d'annulation coopérative garantit qu'une demande d'annulation est honorée entre les étapes plutôt qu'ignorée en cours d'exécution.
3.3 Système d'addons
Une API d'addons formalisée repose sur la racine de composition, permettant aux composants optionnels — le chat flottant en étant l'exemple de référence — d'enregistrer des panneaux et des comportements sans modifier le code de base. C'est le même mécanisme d'extension que la feuille de route sur 12 mois formalise pour les outils, les backends et les fournisseurs de mémoire.
4. Moteur d'inférence
4.1 llama.cpp comme unique moteur
La couche moteur définit un protocole ModelEngine (load, chat, complete, embed) avec exactement une implémentation : llama-cpp-python. C'est un non-négociable déclaré (« llama.cpp est le moteur, pour toujours ») — chaque appel LLM et de plongement passe par une seule interface, ce qui maintient uniformes la propriété du contexte GPU, la comptabilité mémoire et la sémantique d'annulation. Les backends sont un détail d'adaptateur, pas une fonctionnalité produit.
4.2 Exécution sérialisée
Le système impose un modèle à la fois : llama.cpp possède un seul contexte GPU, et toute l'inférence passe par un exécuteur unique. Cela évite les à-coups de VRAM, les changements de contexte et les échecs d'allocation qui affligent l'inférence multi-modèles de bureau, au prix d'une concurrence sérialisée — un compromis accepté pour un produit de bureau.
4.3 Accélération GPU
Le support GPU se fait en un clic : un bouton Installer le support GPU dans la barre latérale désinstalle la roue CPU et installe le build compatible CUDA de llama-cpp-python depuis l'index officiel cu124, puis affiche un indicateur de statut en direct (coche verte quand c'est prêt). L'application détecte la disponibilité du GPU au chargement et décharge automatiquement les couches entre GPU et CPU lorsqu'un modèle dépasse la VRAM disponible. Le même flux sert macOS (y compris Apple Silicon via Metal) et les machines sans GPU.
4.4 Universalité des modèles
Comme le moteur est llama.cpp et le conteneur est GGUF, le chargeur accepte n'importe quel fichier modèle compatible : Mistral, LLaMA, DeepSeek, Qwen, Gemma et la longue traîne des quantifications Hugging Face — sans conversion ni configuration par modèle. Les métadonnées du modèle (longueur de contexte, nombre de couches, quantification) sont lues depuis le fichier lui-même.
5. Mode agentique
5.1 Le graphe
Le mode agent est un StateGraph LangGraph avec la boucle START → agent → outils → agent → … → END et un routage conditionnel. Le nœud agent émet un plan d'appel d'outils structuré ; le nœud outils l'exécute ; le routeur décide de continuer ou de terminer. Le graphe prend en charge les événements de streaming, l'exécution pointée et la reprise depuis des points arbitraires.
5.2 Ensemble d'outils
Sept outils sont sandboxés dans un dossier de travail accordé par l'utilisateur :
| Outil | Capacité |
|---|---|
| Lister le répertoire | Énumérer le contenu de l'espace de travail |
| Lire un fichier | Lire du texte depuis les fichiers de l'espace de travail |
| Écrire un fichier | Créer ou écraser des fichiers |
| Modifier un fichier | Modifications chirurgicales, conscientes du contexte |
| Rechercher des fichiers | Trouver du contenu dans l'espace de travail |
| Exécuter une commande | Exécuter des commandes shell (soumises à approbation) |
| Git | Opérations git (soumises à approbation) |
5.3 Approbation avant exécution
Les commandes shell et les écritures git suspendent l'exécution via interrupt() de LangGraph avant que quoi que ce soit ne s'exécute, affichent une carte d'approbation Autoriser/Refuser dans le panneau de transcription de l'agent, et reprennent au point d'interruption exact avec la décision de l'utilisateur — aucun résultat partiel n'est perdu. Cela transforme l'agent d'acteur autonome en acteur supervisé, ce qui constitue la posture de sécurité centrale du projet.
5.4 Pointage et reprise
Chaque conversation persiste en SQLite via SqliteSaver de LangGraph, clé par un identifiant de thread stable par espace de travail. Le même dossier reprend la même conversation même après un redémarrage de l'application — une exigence que le projet a explicitement choisie de satisfaire avec LangGraph plutôt que de la réimplémenter.
5.5 Ingénierie de robustesse
Quatre mécanismes traitent la réalité selon laquelle les petits modèles locaux sont moins fiables que les API de pointe : réparation automatique du JSON malformé (si le modèle renvoie un JSON d'action cassé, l'agent lui demande de corriger la charge utile, avec réessais, au lieu d'échouer) ; réessais correctifs d'outils (les appels d'outils échoués reçoivent un réessai correctif, puis sont ignorés plutôt que répétés indéfiniment) ; réponses finales diffusées (la réponse finale de l'agent diffuse jeton par jeton via les callbacks de l'application) ; et annulation coopérative entre les étapes. Le principe directeur est explicite : « dégradation gracieuse, jamais d'échec silencieux » — si un modèle 7B ne peut pas produire un JSON d'outil valide, le système répare, réessaie, puis retombe en chat simple et dit ce qui s'est passé.
6. Fondement documentaire sans récupération
GGUF Loader ne livre délibérément pas de base vectorielle. Sa fonctionnalité Trouver le paragraphe répond à « où est-ce dans mon document ? » en laissant le modèle lui-même localiser le passage — un planificateur décide quoi lire, et la progression par fichier est diffusée en direct. Ce choix échange le rappel par index contre la simplicité et la transparence : pas de plongements à construire, pas d'index à maintenir, et le modèle lit le contenu réel des fichiers. Les résumés de dossiers entiers appliquent la même philosophie à l'échelle : l'agent lit chaque fichier lisible (Markdown, PDF, DOCX, TXT, code source) avant de répondre, avec un statut visible « lecture des fichiers restants… ».
7. Modèle de confidentialité et de sécurité
- Local d'abord par défaut : pas de cloud, pas de télémétrie, pas d'analytique. Les outils réseau n'existent que derrière une configuration explicite de l'utilisateur.
- Cage de l'espace de travail : chaque outil est confiné au dossier accordé par l'utilisateur ; le modèle ne peut pas atteindre l'extérieur.
- Portes d'approbation : tout ce qui est exécutable, destructeur ou lié au réseau exige l'approbation humaine (§5.3).
- Transparence : le panneau de transcription de l'agent montre plans, étapes, résultats d'outils, diffs et approbations — le comportement du modèle est entièrement auditable.
8. Conditionnement et distribution
GGUF Loader se distribue de trois manières : le dépôt source avec launch.bat/launch.sh (qui créent un venv, vérifient chaque dépendance épinglée, installent ce qui manque et lancent) ; comme paquet PyPI (pip install ggufloader, lancé avec la commande ggufloader), restructuré en un espace de noms de paquet unique à l'épreuve des collisions pour être sûr dans les environnements Python partagés ; et comme build de bureau conditionné. En mode paquet installé, données, configuration, cache et journaux vivent dans le répertoire de données par utilisateur plutôt que dans site-packages. Le projet supporte Windows 10/11, Linux et macOS, y compris Apple Silicon.
9. Évaluation
L'ingénierie du projet est gouvernée par ses dix principes de conception (§0 des documents d'architecture), dont les plus porteurs sont : llama.cpp comme seul moteur ; LangGraph comme seule boucle agentique ; local d'abord sans télémétrie ; sécurité par défaut ; tout diffuser et tout annuler ; dégradation gracieuse avec communication explicite ; cœur pur avec interface fine ; un modèle à la fois avec exécution sérialisée ; extensibilité de première classe ; et le modèle de classe 7B comme véritable utilisateur. Une suite de tests unitaires (tests/unit/) exerce le cœur pur — adaptateur moteur, graphe, outils, mémoire, réglages — sans nécessiter d'affichage, et la feuille de route prévoit des tests d'intégration sur modèle réel et des tests de fumée GUI hors écran (pytest-qt). Les principes fonctionnent comme une spécification exécutable : chaque changement de fonctionnalité est évalué contre eux avant fusion.
10. Discussion
La conception incarne un ensemble clair de compromis. L'exécution sérialisée à un modèle sacrifie la concurrence pour la stabilité de la VRAM — juste pour un outil de bureau, faux pour un serveur. Le fondement sans récupération sacrifie le rappel par index pour la transparence — juste pour « où est ce passage ? », faux pour la recherche sémantique sur des milliers de documents (un rôle que la feuille de route réserve à des plongements optionnels). Le partage strict cœur/interface ajoute de l'indirection mais rend tout le moteur testable sans tête. Et l'engagement sur un moteur unique (llama.cpp) accepte un risque fournisseur en échange d'un chemin de code à maintenir. Chaque choix est documenté et révisable ; les documents d'architecture distinguent explicitement la conception actuelle de la cible à 12 mois.
11. Limites et travaux futurs
Limites actuelles : pas de stockage vectoriel intégré (Trouver le paragraphe est sans récupération ; les plongements sont un élément explicite de la feuille de route) ; un seul modèle chargé à la fois ; pas de mode multi-utilisateur ni serveur ; et aucun résultat de benchmark publié contre des suites d'évaluation externes. La feuille de route Architecture v2 publiée cible : un SDK d'outils et une API d'addons formalisés ; des fournisseurs de mémoire (stores SQLite, plongements + recherche cosinus, instantanés d'annulation copie-avant-écriture) ; un schéma de réglages avec événements de changement ; un protocole ModelEngine avec llama.cpp comme implémentation de référence ; et la formalisation du protocole JSON de l'agent, de la boucle de réparation et du catalogue d'outils. La direction produit déclarée est un assistant IA de bureau local d'abord dont la capacité phare est un agent LangGraph qui accomplit réellement des tâches sur les fichiers de l'utilisateur.
12. Conclusion
GGUF Loader démontre qu'un runtime LLM local performant peut être un produit grand public : chargement universel de GGUF, accélération GPU en un clic, agent supervisé à mémoire pointée, fondement documentaire transparent et confidentialité stricte — le tout derrière une interface PySide6 qu'un utilisateur non technique peut opérer. Ses principes de conception explicites et son architecture en couches en font une implémentation de référence utile pour l'IA locale, et sa licence MIT et son développement ouvert (58 étoiles, 13 forks au moment de la rédaction) invitent à la contribution. La leçon centrale du projet est que supprimer la taxe d'infrastructure — quantification, configuration du runtime, fiabilité des appels d'outils — change la question de « l'IA locale est-elle possible ? » à « que devrions-nous exécuter localement ensuite ? ».
Références
- Gerganov, G., et al. llama.cpp : inférence du modèle LLaMA en C/C++ pur. https://github.com/ggml-org/llama.cpp
- llama-cpp-python. Bindings Python pour llama.cpp. https://github.com/abetlen/llama-cpp-python
- Yao, S., et al. ReAct : Synergizing Reasoning and Acting in Language Models. ICLR 2023. https://arxiv.org/abs/2210.03629
- LangChain. LangGraph : Building Stateful, Multi-Actor Applications with LLMs. https://github.com/langchain-ai/langgraph
- Haal Lab. Lawyer Assistant : application de bureau RAG juridique respectueuse de la vie privée. https://github.com/haal-lab/Lawyer-Assistant
- GGUF Loader, Architecture v2 (cible 12 mois) et documents d'architecture actuels. https://github.com/GGUFloader/gguf-loader