paperless-gpt : confier le titre, les tags et l'OCR de paperless-ngx à un LLM

Le problème que paperless-gpt prend en charge

paperless-ngx archive, indexe et retrouve des documents. Il ne décide pas à votre place qu'une facture doit s'appeler autrement que scan_2026_04_12.pdf, ni que le bon tag est celui de votre fournisseur d'électricité. Le README résume la promesse du projet en deux volets : générer des titres et des tags par IA, et retravailler l'OCR avec un LLM pour mieux lire les scans difficiles. La cible est donc l'utilisateur qui a déjà une bibliothèque paperless-ngx et qui passe du temps à corriger des métadonnées, ou qui constate que le texte extrait de certains documents est inutilisable pour la recherche. Le projet ajoute aussi la détection de correspondants et le remplissage de champs personnalisés, deux opérations que paperless-ngx ne devine pas seul.

Un service Go posé à côté de paperless-ngx

Le dépôt est écrit en Go et se déploie comme un conteneur, à composer aux côtés de paperless-ngx. Le README décrit une interface web unifiée qui sert à deux choses : revoir les suggestions de l'IA et lancer un traitement automatique. Le flux est celui-ci : paperless-gpt lit des documents dans paperless-ngx, interroge un fournisseur de modèle pour produire une proposition (titre, tags, correspondant, champs), et, selon la configuration, soit la présente pour validation, soit l'applique. Le fournisseur est au choix OpenAI ou Ollama en local, avec la possibilité de brancher des services OCR spécialisés : Google Document AI, Azure Document Intelligence, ou un serveur Docling auto-hébergé. Le README mentionne aussi une analyse ad hoc sur une sélection de documents avec un prompt libre, pour obtenir un résumé ou extraire une information précise de plusieurs pièces à la fois.

Le choix du mode OCR change tout

Le projet ne se contente pas d'appeler un modèle sur du texte déjà extrait. Il propose plusieurs modes de traitement OCR, dont un mode image par défaut, un mode PDF et un mode PDF entier, et précise que la compatibilité dépend du fournisseur retenu. C'est la partie la plus délicate à calibrer : le mode PDF entier envoie davantage de contenu au modèle, ce qui a un coût en jetons et en temps, alors que le mode image traite page par page. Le README signale aussi une détection d'OCR existant, utile pour éviter de refaire un travail déjà présent. Sur la sortie, paperless-gpt peut produire un PDF avec une couche de texte transparente positionnée sur chaque mot, ce qui rend le document cherchable et sélectionnable tout en gardant son apparence d'origine. Le PDF obtenu peut être conservé localement ou renvoyé vers paperless-ngx. Le README mentionne une limite explicite sur la copie des métadonnées lors de ce traitement, ainsi que des fonctions de sécurité ; il faut lire cette section avant d'écraser quoi que ce soit.

Installation : variables d'environnement et Compose

Le README annonce un déploiement Docker en quelques variables d'environnement. La section Installation propose deux chemins : Docker Compose, ou une installation manuelle. Les prompts personnalisés se gèrent depuis l'interface web, sous le menu Settings, et le projet décrit une structure de dossiers default_prompts et prompts qui garde vos modifications persistantes. Les variables d'environnement couvrent la connexion à paperless-ngx, le choix du fournisseur LLM, et le fournisseur OCR. Pour les champs personnalisés, le README est clair sur un point : la fonctionnalité doit être activée dans les paramètres et il faut sélectionner au moins un champ pour qu'elle agisse. Trois modes d'écriture sont proposés : Append, qui n'ajoute que les champs absents et n'écrase jamais une valeur existante, même vide ; Update, qui ajoute et remplace les champs suggérés en laissant intacts ceux sans suggestion ; Replace, qui supprime tous les champs personnalisés du document avant d'écrire les suggestions. Append est présenté comme l'option la plus sûre, et c'est cohérent : Replace est destructif par construction.

Ce que le projet ne promet pas

Le README vante un OCR meilleur que l'OCR traditionnel, mais cette affirmation vient de l'auteur du projet, pas d'une mesure indépendante. Un LLM peut inventer du texte absent d'un scan, et rien dans la documentation fournie ne décrit de garde-fou contre ce type d'erreur. Sur des documents à valeur légale ou comptable, c'est un risque qu'il faut peser avant d'envoyer une facture ou un contrat dans le pipeline. Autre point : le README indique que les modèles de raisonnement dans Ollama, comme qwen3:8b, améliorent la précision, et ajoute que « a bigger model will enhance the experience » si vous avez assez de GPU ou de NPU. Cela revient à dire que la qualité dépend directement du matériel dont vous disposez. Avec un modèle trop petit, les titres et les tags seront approximatifs. Enfin, l'installation manuelle existe, mais le chemin décrit et mis en avant reste Docker ; hors conteneur, vous vous éloignez de ce que la documentation couvre réellement.

paperless-ngx seul, ou paperless-ngx avec paperless-ai

L'alternative la plus directe est de ne rien ajouter : paperless-ngx sait déjà extraire du texte, appliquer des règles de correspondance et classer par tags selon des motifs de nom de fichier ou de contenu. Cette approche ne coûte rien en appels de modèle, ne dépend d'aucun GPU, et reste déterministe : la même règle produit le même résultat. paperless-gpt prend le problème par l'autre bout, en demandant à un modèle de comprendre le document plutôt que de faire correspondre un motif. La différence de comportement est nette. Une règle paperless-ngx ne se trompe pas sur un scan illisible, elle ne fait simplement rien. Un LLM, lui, produira toujours une réponse, y compris quand le document est ambigu. C'est précisément pour cela que l'interface de revue manuelle existe, et c'est aussi pourquoi le mode Append est présenté comme le plus sûr pour les champs personnalisés.

Maintenance, prompts et licence MIT

Le dépôt est publié sous licence MIT, ce qui autorise la modification et la redistribution avec conservation de l'avis de licence. Le projet n'est pas archivé et les versions récentes s'enchaînent : v0.26.0, v0.26.1 puis v0.27.0 entre juillet et septembre 2026. Ce rythme implique de suivre les notes de version avant de mettre à jour, d'autant que les prompts personnalisés vivent dans un dossier prompts distinct des default_prompts : vos adaptations devraient survivre aux mises à jour, mais c'est à vérifier à chaque changement de version. Le coût de maintenance réel ne vient pas du conteneur, il vient des modèles. Chaque évolution du fournisseur LLM ou OCR peut modifier la qualité des sorties, et un prompt qui fonctionnait sur un modèle donné peut se comporter différemment sur le suivant. La licence MIT ne dit rien du coût des appels à OpenAI ni des conditions d'utilisation de Google Document AI ou d'Azure Document Intelligence, qui restent régies par leurs propres contrats.

Conclusion éditoriale

paperless-gpt s'adresse aux instances paperless-ngx déjà en place dont les documents restent mal nommés ou mal tagués, et à celles qui traitent des scans dégradés que l'OCR intégré lit mal. Il faut éviter de l'installer si vous refusez d'ajouter un conteneur et une seconde surface de configuration à côté de paperless-ngx, ou si vous n'avez pas de quoi faire tourner un modèle Ollama. Avant de vous engager, vérifiez que vos modèles de prompts dans le dossier prompts donnent des sorties exploitables sur vos propres documents, puis contrôlez les modes d'écriture Append, Update et Replace sur les champs personnalisés avant de laisser le traitement automatique agir sans revue.

Sources officielles

1. icereed/paperless-gpt on GitHub
2. Issues
3. License: MIT
4. README
5. Releases