Blog SIG & Territoires

Voir la première partie de cet article

Présentation du plugin QGIS LLM Assistant

Un assistant intégré au cœur de QGIS

QGIS LLM Assistant est un plugin expérimental que j’ai conçu pour établir un dialogue intelligent entre QGIS et un modèle de langage local (LLM) fonctionnant via un petit serveur Python.
L’objectif : permettre à l’utilisateur de formuler des requêtes naturelles — en français ou en anglais — et d’obtenir en retour :

• des explications sur une fonction ou un algorithme QGIS,
• du code PyQGIS prêt à exécuter,
• des corrections automatiques si le code échoue,
• et un retour visuel interactif (mise en couleur, statut d’exécution, erreurs détectées).

Une architecture simple et robuste

Le plugin repose sur une architecture légère en deux composants :

1. Le serveur local (server.py)
   • Écrit en Flask, il sert d’intermédiaire entre QGIS et le modèle de langage.
   • Il utilise la bibliothèque LangChain pour structurer les échanges et Ollama pour exécuter le modèle localement (sans connexion Internet).
   • Le serveur choisit automatiquement le modèle le plus adapté selon la mémoire et le GPU disponible (par exemple : Gemma, Mistral ou Llama3).

   En pratique, l’utilisateur n’a rien à configurer : le serveur sélectionne le modèle optimal avant chaque requête.

2. L’interface QGIS

   • Intégrée sous forme de dock, elle permet de rédiger une question, d’afficher la réponse du modèle et de voir le code PyQGIS suggéré.
   • Une zone d’exécution (“Run code”) permet d’exécuter directement le script dans QGIS, avec une vérification intelligente des erreurs et une auto-correction en cas d’échec.
   • Le code est surligné selon son statut :

     • Vert clair : Lignes exécutées avec succès
     • Jaune : Lignes corrigées automatiquement
     • Rouge : Lignes bloquées ou erronées

L’auto-correction intelligente

Le cœur du plugin repose sur une idée clé : ne jamais bloquer sur une erreur.
Lorsqu’un code PyQGIS échoue, le module d’exécution le réanalyse et applique une série de corrections automatiques :

• remplacement des imports manquants (from qgis.core import ...) ;
• adaptation des fonctions obsolètes (iface.activeProject() → QgsProject.instance()) ;
• conversion d’appels génériques (qgis.open_raster() → QgsRasterLayer(...)) ;
• suppression d’attributs invalides ou redondants.

Chaque correction est enregistrée et signalée à l’utilisateur pour garantir la transparence du processus.

Un outil d’apprentissage et de productivité

QGIS LLM Assistant n’est pas seulement un générateur de code :
c’est un formateur silencieux.

En affichant le code généré, commenté et corrigé, il aide l’utilisateur à comprendre la logique PyQGIS sans avoir besoin de consulter la documentation à chaque étape.

Les enseignants et formateurs peuvent ainsi :

• illustrer des concepts de QGIS en direct ;
• générer des exemples contextualisés ;
• aider les étudiants à comprendre les erreurs Python dans un environnement sécurisé.

Sécurité et exécution locale

Un aspect essentiel du plugin est son fonctionnement 100 % local.
Aucun texte, donnée ni script n’est envoyé vers un serveur externe :
tout s’exécute sur la machine de l’utilisateur, via le serveur Flask et les modèles Ollama.

Cette approche garantit :

• la confidentialité des données géospatiales ;
• la stabilité des performances, même hors connexion ;
• et la souveraineté numérique, un enjeu important pour les institutions publiques.

En résumé

Comment fonctionne le dialogue entre QGIS et le modèle LLM

Vue d’ensemble du flux de communication

Le fonctionnement de QGIS LLM Assistant repose sur un enchaînement clair et contrôlé entre QGIS, le serveur Flask, et le modèle de langage local (LLM).
Chaque étape joue un rôle précis dans la génération, la correction et l’exécution du code PyQGIS.

Voici la séquence typique :

[1] L’utilisateur saisit une requête dans QGIS
↓
[2] Le plugin envoie le texte au serveur Flask (/analyze)
↓
[3] Le serveur choisit automatiquement le modèle LLM (Gemma, Mistral ou Llama3)
↓
[4] Le LLM génère une réponse : explication + code suggéré
↓
[5] Le serveur renvoie la réponse JSON à QGIS
↓
[6] QGIS affiche le texte et le code dans l’interface
↓
[7] L’utilisateur peut exécuter le code avec « Run Code »
↓
[8] Le module d’auto-fix corrige et réexécute si nécessaire

Étape 1 – La requête utilisateur

L’utilisateur formule une demande en langage naturel :

« Peux-tu générer un code PyQGIS pour calculer l’indice corallien à partir d’une image multispectrale ? »

Le plugin envoie cette requête au serveur Flask sous forme d’un message JSON :

{ "prompt": "Calcule l’indice corallien à partir du raster Palmar_MS.tif" }

Étape 2 – Le serveur Flask analyse la ressource

Le serveur reçoit la requête et :

1. mesure la RAM CPU et GPU disponibles ;
2. sélectionne le modèle LLM le plus approprié (par exemple gemma:2b-instruct-q4_K_M) ;
3. prépare un prompt structuré :

You are a marine AI assistant. {prompt}

Ce prompt fournit au modèle un rôle contextuel (assistant géospatial spécialisé) et le contenu de la question.

Étape 3 – Le modèle de langage local (LLM)

Le modèle exécute la génération du texte et renvoie :

• une explication ou un commentaire ;
• un bloc de code PyQGIS correspondant à la demande.

Exemple de sortie typique :

import qgis
from qgis.core import QgsRasterLayer

layer = QgsRasterLayer("Palmar_MS.tif", "RasterLayer")
if layer.isValid():
    print("Raster loaded successfully")

Étape 4 – Le serveur renvoie la réponse enrichie

Le serveur convertit la réponse du modèle en un message JSON enrichi, contenant :

• le texte brut de la réponse,
• le nom du modèle utilisé,
• la mémoire CPU/GPU disponible,
• et le temps total de traitement.

Exemple :

{
  "response": "Here is the PyQGIS code to calculate the coral index...",
  "model_used": "gemma:2b-instruct-q4_K_M",
  "available_cpu_gb": 5.4,
  "available_gpu_gb": 0.0,
  "processing_time_s": 14.8
}

Étape 5 – Affichage et exécution dans QGIS

Le plugin affiche :

• la réponse textuelle dans la fenêtre « Assistant Response » ;
• le code généré dans la fenêtre « Suggested PyQGIS Code ».

L’utilisateur peut alors :

• copier le code,
• ou cliquer sur Run Code pour l’exécuter directement.

Le module d’exécution analyse alors chaque ligne :

• vérifie les erreurs possibles ;
• tente des corrections automatiques ;
• surligne le code selon le résultat :

  • Vert clair : réussite,
  • Jaune : corrigé,
  • Rouge : bloqué.

Étape 6 – Retour interactif et traçabilité

Toutes les corrections appliquées sont :

• listées dans la fenêtre de sortie ;
• réinjectées dans le code affiché ;
• sauvegardées dans la session QGIS (pour apprentissage futur).

Ainsi, le plugin ne se contente pas d’exécuter du code :
il documente, corrige et illustre chaque interaction, créant un véritable assistant d’apprentissage pour PyQGIS.

Le rôle de l’auto-fix et de la validation progressive du code (philosophie et logique d’apprentissage)

L’un des aspects les plus innovants de ce plugin est sa capacité à corriger automatiquement les erreurs générées par le modèle LLM et à valider le code pas à pas. Contrairement à un simple outil qui se contente d’exécuter le code fourni, le plugin agit comme un assistant intelligent, capable de détecter des incohérences fréquentes dans le contexte QGIS et de proposer des correctifs sûrs et réutilisables.

Le fonctionnement repose sur deux concepts clés :

1. L’auto-fix intelligent
   Le plugin identifie des erreurs typiques générées par le LLM, comme l’utilisation de fonctions obsolètes, des importations manquantes, ou des appels à des méthodes inexistantes dans l’API QGIS actuelle. Pour chaque cas, il applique un correctif prédéfini, par exemple :
   • Remplacer qgis.open_raster() par une instance valide de QgsRasterLayer ;
   • Substituer evaluateExpression() par sample() pour récupérer des valeurs ponctuelles sur un raster ;
   • Corriger les références obsolètes à iface.activeProject() par QgsProject.instance().

   Ces corrections sont appliquées en conservant la structure du code original et en surlignant visuellement les lignes modifiées pour que l’utilisateur puisse suivre et comprendre les interventions.

2. La validation progressive du code
   Plutôt que d’exécuter le script d’un bloc, le plugin teste chaque ligne ou chaque section de code individuellement. Chaque tentative peut aboutir à :
   • un succès complet,
   • une correction automatique,
   • ou un blocage si l’erreur n’est pas résoluble automatiquement.

   Ce mécanisme permet non seulement d’exécuter en toute sécurité des scripts générés par le modèle, mais aussi d’apprendre au fil des essais quelles erreurs se répètent et comment les corriger de façon fiable.

En combinant ces deux approches, le plugin offre un environnement sécurisé et interactif, transformant chaque requête LLM en une expérience d’apprentissage pour l’utilisateur, tout en garantissant un code PyQGIS valide et exécutable.

La fenêtre du plugin et le retour visuel ligne par ligne

Pour rendre l’expérience intuitive et pédagogique, le plugin fournit un retour visuel clair sur chaque ligne de code exécutée. Plutôt que de se limiter à un simple message d’erreur générique, l’utilisateur peut suivre l’état exact du script généré par le LLM et comprendre instantanément ce qui a été exécuté, corrigé ou bloqué.

1. Structure de la fenêtre

La fenêtre du plugin se compose de trois zones principales :

• Zone de saisie du prompt : ici, l’utilisateur décrit sa question ou sa tâche à accomplir dans le contexte du projet QGIS actuel.
• Zone de réponse de l’assistant : affiche la réponse textuelle générée par le LLM, accompagnée d’informations pratiques : modèle utilisé, ressources disponibles, temps de traitement.
• Zone de code suggéré (PyQGIS) : contient le script généré et corrigé automatiquement par le plugin. C’est dans cette zone que le surlignage ligne par ligne apparaît.

Les boutons en bas de fenêtre agissent sur la fenêtre « Suggested PyQGIS Code ».

2. La logique des couleurs

Chaque ligne de code reçoit un surlignage couleur indiquant son statut :

• Vert clair : la ligne a été exécutée avec succès.
• Jaune : la ligne a été automatiquement corrigée par le plugin (import, fonction, alias).
• Rouge : la ligne contient une erreur bloquante non résolue automatiquement.

Ce code couleur permet à l’utilisateur de voir immédiatement quelles parties du code sont fiables et lesquelles nécessitent son attention, transformant l’exécution d’un script LLM en un apprentissage guidé.

3. Feedback détaillé

Le plugin fournit également un résumé :

• nombre de lignes exécutées avec succès,
• lignes auto-corrigées,
• lignes bloquées.

Chaque correction appliquée est listée dans le message, offrant un journal d’exécution complet, utile pour comprendre la logique de l’auto-fix et pour reproduire manuellement les corrections si nécessaire.

Cette approche transforme le plugin en un véritable assistant pédagogique pour PyQGIS, permettant aux utilisateurs, qu’ils soient débutants ou confirmés, d’apprendre à coder dans QGIS tout en bénéficiant de la puissance des modèles LLM.

Le rôle de l’auto‑fix et de la validation progressive du code

Le plugin ne se contente pas d’exécuter le code généré par le LLM : il applique une logique intelligente d’auto-correction et de validation progressive, qui reflète une véritable philosophie d’apprentissage par essais et ajustements.

1. Exécution par blocs

Au lieu d’envoyer tout le script d’un coup, le plugin décompose le code ligne par ligne ou par petits blocs logiques. Chaque bloc est vérifié et exécuté indépendamment :

• si un bloc pose problème, il est isolé, et l’exécution des autres blocs peut continuer,
• si le bloc est corrigé automatiquement, la correction est appliquée avant de poursuivre,
• chaque ligne conserve son statut : succès, corrigée ou bloquée.

Cette méthode permet de préserver le contexte global du projet QGIS tout en évitant qu’une erreur sur une seule ligne interrompe tout le processus.

2. Corrections intelligentes

Le plugin identifie et corrige automatiquement plusieurs types d’erreurs fréquentes :

• import manquant ou incorrect,
• fonctions obsolètes ou mal nommées (iface.activeProject() → QgsProject.instance()),
• alias ou préfixes erronés (qgis.open_raster → QgsRasterLayer),
• usages d’attributs inexistants ou fonctions déconseillées (.raster, evaluateExpression()).

Chaque correction est consignée et surlignée dans la zone de code, offrant un feedback visuel immédiat.

3. Apprentissage progressif

Bien que le plugin ne modifie pas le modèle LLM lui-même, il “apprend” de chaque tentative grâce à la logique suivante :

• les corrections appliquées sont mémorisées dans la session et peuvent être réutilisées pour de futurs prompts similaires,
• les erreurs bloquantes sont identifiées et signalées pour permettre à l’utilisateur d’ajuster son prompt ou son code.

Cette approche transforme l’exécution d’un script LLM en une expérience d’apprentissage itérative, où l’utilisateur comprend progressivement le fonctionnement de PyQGIS et comment anticiper les erreurs courantes.

Bénéfices concrets pour l’utilisateur QGIS

L’intégration du LLM avec l’auto-fix intelligent transforme l’expérience QGIS : elle réduit la frustration, accélère le développement et facilite l’apprentissage progressif du code PyQGIS. Voici les principaux bénéfices :

1. Moins de blocages techniques

Grâce à la validation progressive et aux corrections automatiques, l’utilisateur ne se retrouve plus face à un script entièrement bloqué par une erreur mineure. Les lignes problématiques sont isolées et surlignées : on sait immédiatement ce qui a été corrigé et ce qui nécessite une intervention manuelle.

2. Gain de temps

Au lieu de chercher dans la documentation ou de tester des dizaines de variations, l’utilisateur peut se concentrer sur l’objectif final. Par exemple :

# Code généré par le LLM pour ouvrir un raster et calculer un indice
raster_layer = qgis.open_raster("Palmar_MS.tif")
coral_index = calculate_coral_index(raster_layer)
coral_index.save("coral_index.tif")

Le plugin corrige automatiquement la ligne qgis.open_raster en :

raster_layer = QgsRasterLayer("Palmar_MS.tif", "Palmar_MS")
if not raster_layer.isValid():
    raise Exception("Raster layer invalide")

Ainsi, le code devient directement exécutable dans QGIS, sans perte de temps à déboguer.

3. Feedback visuel et apprentissage

Chaque ligne est surlignée :

• vert clair → exécutée avec succès,
• jaune → ligne corrigée automatiquement,
• rouge → ligne bloquée nécessitant une intervention.

L’utilisateur voit en un coup d’œil quelles parties du code sont sûres et quelles parties méritent son attention. C’est un véritable outil pédagogique, qui aide à comprendre les erreurs fréquentes et à anticiper les problèmes dans de futurs scripts.

4. Adaptabilité à tout projet

Que ce soit pour un projet de cartographie, d’analyse spatiale ou de traitement raster/vectoriel, le plugin s’adapte à n’importe quel code PyQGIS généré par le LLM. Il crée un pont intelligent entre la puissance du modèle et la réalité du projet QGIS.

Limites actuelles et appel à retours d’expérience

Ce plugin n’est pas un outil « fini » au sens traditionnel du terme.
Il s’agit d’un prototype fonctionnel, fourni tel quel, dont l’objectif principal est d’explorer le potentiel d’interaction entre QGIS et un modèle de langage (LLM).

L’idée n’est pas encore d’offrir une solution de production, mais de tester des scénarios d’usage, d’évaluer la qualité des réponses générées et d’identifier les ajustements nécessaires pour un futur développement plus robuste.

Je publie donc ce plugin dans l’esprit du libre : pour favoriser la discussion, la contribution et le retour d’expérience des utilisateurs.
Vos remarques, suggestions ou signalements d’erreurs sont donc les bienvenus — ils aideront à orienter les prochaines évolutions.

Points à connaître et limites actuelles

• Différents modèles, différents résultats : selon le modèle LLM utilisé (GPT-4, Mistral, Gemini, etc.), les réponses et corrections de code peuvent varier sensiblement. Certains modèles sont plus précis sur le code QGIS, d’autres sur le texte explicatif.
• Exécution locale ou distante : le comportement dépend du mode d’accès au modèle (API, serveur local, ou instance privée). Des différences de latence et de compatibilité peuvent survenir.
• Support partiel de l’environnement QGIS : certaines classes ou méthodes ne sont pas reconnues correctement par les modèles, notamment lorsqu’elles changent entre versions (ex. QGIS 3.28 → 3.44).
• Erreur de contexte persistante : après plusieurs exécutions, le modèle peut réutiliser un code incorrect précédemment produit. Une réinitialisation du contexte ou une relance du plugin peut être nécessaire.
• Pas de validation de sécurité : le plugin exécute le code Python proposé, mais il ne vérifie pas la sécurité de ce code. Il convient de rester prudent et de lire le code avant exécution.
• Absence de supervision humaine : les corrections automatiques (« auto-fix ») sont expérimentales ; elles peuvent résoudre des erreurs simples mais aussi introduire de nouveaux bugs.

Vers une version communautaire

L’objectif à moyen terme est de faire évoluer ce plugin vers une version communautaire, développée et améliorée collectivement.
Plusieurs pistes sont déjà envisagées :

• meilleure gestion du contexte QGIS pour éviter les erreurs de compatibilité,
• intégration de plusieurs modèles de langage sélectionnables depuis l’interface,
• sauvegarde des échanges et du code testé,
• documentation collaborative des cas d’usage réussis.

Comme souvent dans l’univers open source, c’est l’usage réel et les contributions qui feront progresser l’outil.
Que vous soyez formateur, développeur, chercheur ou simple curieux de l’intelligence artificielle appliquée à la géomatique, vos retours ont une vraie valeur.

Conclusion générale

L’intelligence artificielle générative ouvre une nouvelle étape dans la relation entre l’utilisateur et QGIS : celle du dialogue assisté par le langage naturel.
Ce plugin expérimental n’est pas une solution aboutie, mais une porte entrouverte sur ce que pourraient devenir les outils géospatiaux de demain — des environnements interactifs où la connaissance métier, le code et la cartographie se rencontrent sans friction.

L’enjeu n’est pas seulement technique : il s’agit aussi de réinventer la manière d’apprendre, de transmettre et de collaborer autour du géospatial libre.
À ce titre, chaque essai, chaque retour, chaque amélioration contribuera à tracer la voie vers des usages plus intelligents, plus accessibles, et toujours ouverts.

Vous pouvez télécharger le plugin et partager vos retours directement sur le dépôt GitHub : https://github.com/SigEtTerritoires/qgis-llm-codeassistant. N’hésitez pas à signaler les bugs, proposer des améliorations ou contribuer au développement : vos retours permettront d’améliorer le plugin et de le rendre plus robuste pour la communauté QGIS.

Si cet article vous a intéressé et que vous pensez qu'il pourrait bénéficier à d'autres personnes, n'hésitez pas à le partager sur vos réseaux sociaux en utilisant les boutons ci-dessous. Votre partage est apprécié !

Atilio Francois