Sparrow : extraction structurée et agents sur votre propre infrastructure
Structured data extraction, instruction calling and agentic workflows with ML, LLM and Vision LLM
En bref
- De quoi s’agit-il ?
- Sparrow est une plateforme API-first en Python qui transforme factures, relevés et tableaux en JSON validé, avec un choix de backends allant de MLX sur Apple Silicon à Mistral OCR. Le point sensible n'est pas la qualité de l'extraction, c'est le coût de mise en route et la licence GPL-3.0.
- À qui s’adresse-t-il ?
- Sparrow convient aux équipes qui traitent des documents sensibles et disposent déjà d'un GPU sur site, ou d'un Mac Apple Silicon pour le backend MLX. Il ne convient pas à qui veut extraire quelques factures par mois sans administrer de modèle : le coût d'installation et la mémoire GPU requise dépassent largement le besoin.
- Puis-je l’utiliser commercialement ?
- Oui, sous conditions. GPL-3.0 est une licence copyleft : si vous distribuez un logiciel qui l’inclut, vous devez publier le code source de ce logiciel sous la même licence. Un usage interne, sans distribution, ne déclenche pas cette obligation.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 1 jour.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le problème : sortir du JSON validé d'un PDF sans envoyer le document ailleurs
Les factures, relevés bancaires et tableaux scannés arrivent rarement dans un format exploitable. La réponse habituelle consiste à appeler une API d'OCR ou un LLM hébergé, ce qui suppose de faire sortir le document de votre périmètre. Sparrow prend le problème par l'autre bout : le README décrit une plateforme API-first qui tourne sur votre propre infrastructure, avec la mention « no external API calls or cloud dependencies ». Le public visé est donc l'équipe backend qui doit alimenter un pipeline de données à partir de documents, et qui ne peut pas confier ces documents à un tiers. Le dépôt couvre trois usages distincts : l'extraction structurée depuis des images et des PDF, le traitement de texte par instruction (validation, prise de décision) et l'orchestration de workflows multi-étapes. Ces trois usages partagent la même surface REST, ce qui évite d'assembler trois outils séparés.
Trois pipelines interchangeables derrière une seule API
L'architecture repose sur des composants nommés dans le README. Sparrow Parse est la bibliothèque Vision LLM qui produit le JSON structuré. Sparrow Instructor prend en charge le texte et les instructions. Sparrow Agents orchestre les étapes, avec un suivi visuel via Prefect. Sparrow OCR intervient en amont pour la reconnaissance de texte, et Sparrow ML LLM est présenté comme le moteur API principal. Le point de conception intéressant est que le pipeline se choisit à l'appel et non à l'installation : la comparaison des pipelines et l'exemple CLI montrent que l'on passe le nom du pipeline et le backend en options. Le backend est lui aussi un paramètre : MLX sur Apple Silicon, vLLM sur NVIDIA, Ollama, Hugging Face, Mistral OCR. Le README insiste sur le fait que la surface d'API reste identique d'un backend à l'autre, ce qui laisse la possibilité de changer de moteur sans réécrire le client. La validation s'appuie sur un schéma JSON fourni par l'appelant, et la réponse porte un champ valid en plus des données extraites.
Mise en route : les commandes et les deux pièges de configuration
Le README donne une séquence en cinq étapes. On installe Python 3.12.10 via pyenv, on crée un environnement virtuel nommé .env_sparrow_parse, on clone le dépôt, on se place dans sparrow-ml/llm et on lance pip install -r requirements_sparrow_parse.txt. Le serveur démarre ensuite avec python api.py. Sur macOS, le traitement des PDF nécessite poppler, installé par brew install poppler. Le piège de configuration est explicite dans le README : avant d'installer les dépendances, il faut ouvrir requirements_sparrow_parse.txt et vérifier la référence de bibliothèque. Sur macOS avec MLX, il faut que sparrow-parse[mlx] y figure. Sur Linux ou Windows, il faut la référence sparrow-parse seule, ce qui évite d'installer les bibliothèques liées à MLX. Un fichier de requirements édité à la main selon la plateforme, c'est un point de friction réel pour une équipe qui veut automatiser son installation. L'extraction se lance ensuite en ligne de commande, avec le schéma en premier argument, puis --pipeline "sparrow-parse", --options mlx, --options mlx-community/Qwen2.5-VL-72B-Instruct-4bit et --file-path. Le README donne le résultat attendu sous forme d'un tableau data accompagné de valid.
Le prérequis matériel est le vrai filtre
Le README liste comme prérequis un GPU avec assez de mémoire pour le Vision LLM choisi, et il précise que le backend MLX suppose macOS. L'exemple d'appel utilise un modèle Qwen2.5-VL-72B en quantification 4 bits : ce n'est pas un choix anodin, et la quantification n'annule pas le besoin de mémoire. Autrement dit, Sparrow déplace la contrainte. Là où une API hébergée se paie à l'usage, ici on immobilise une machine. Pour un volume faible, le calcul est défavorable. Le second point est que le README ne fournit aucun chiffre de débit, de latence ou de précision. Impossible, à partir de ce seul matériel, de savoir si le pipeline tient un volume de production donné. Une équipe qui doit dimensionner un parc de GPU devra mesurer elle-même. Il faut aussi noter que la documentation décrit plusieurs backends mais que le README ne détaille pas les écarts de résultat entre eux : le même schéma appliqué à MLX et à Mistral OCR peut ne pas produire le même JSON, et rien dans le matériel fourni ne permet de trancher.
Ce que Sparrow n'est pas : le cas du document unique
Si votre besoin se résume à extraire un tableau d'une capture d'écran, une fois par semaine, Sparrow est un mauvais outil. Il faut installer pyenv, Python 3.12.10, poppler, choisir un backend, éditer un fichier de requirements, télécharger un modèle de vision de grande taille et disposer d'un GPU. Un script de quelques lignes appelant un service d'OCR hébergé règle le problème en une soirée. Sparrow devient pertinent quand le volume, la sensibilité des documents ou la nécessité d'enchaîner plusieurs étapes justifient l'infrastructure. Le README mentionne par ailleurs du rate limiting, des analytics d'usage et une licence commerciale disponible : cela suggère une vocation multi-utilisateurs, pas un usage individuel. Enfin, la partie agents s'appuie sur Prefect pour le suivi visuel, ce qui ajoute une dépendance d'infrastructure supplémentaire si vous voulez l'observabilité décrite.
Face à un pipeline OCR plus règles maison
L'alternative la plus courante n'est pas un autre projet, c'est un assemblage : un moteur OCR classique qui sort du texte brut, puis des expressions régulières ou un parseur dédié pour remplir les champs. La différence d'approche est nette. Un pipeline à base de règles est déterministe et peu coûteux en calcul, mais chaque nouveau format de facture demande une nouvelle règle, et un décalage de mise en page casse l'extraction. Sparrow confie l'interprétation au modèle de vision et valide le résultat contre un schéma JSON fourni à l'appel : on décrit la forme attendue, pas la position des champs. C'est ce qui permet de traiter un tableau de bonds et une facture avec le même code. Le prix à payer est l'opacité : quand l'extraction est fausse, il n'y a pas de règle à corriger, seulement un modèle à changer ou un schéma à préciser. Le champ valid aide à détecter les sorties non conformes, mais il ne dit pas pourquoi le modèle s'est trompé.
Maintenance, cadence de publication et licence GPL-3.0
Le dépôt n'est pas archivé et la dernière poussée date du 26 août 2026. Les versions publiées montrent une accélération récente : v0.4.4 en septembre 2025, puis v0.5.0 et v0.6.0 en mai et juin 2026. Une cadence qui passe de plusieurs mois à quelques semaines entre deux versions signifie que les ruptures d'API sont probables : prévoyez de lire les notes de version avant chaque montée, d'autant que le projet n'a pas atteint la version 1.0. Le README ne décrit pas de procédure de migration entre versions. Sur le plan juridique, Sparrow est publié sous GPL-3.0. Cette licence impose des obligations dès lors que vous redistribuez le logiciel ou une version modifiée, et le README mentionne une licence commerciale disponible en parallèle pour les cas où la GPL ne convient pas. Si Sparrow reste un service interne que vous exploitez sans le distribuer, la question se pose différemment que si vous l'embarquez dans un produit livré à des clients. Ce paragraphe décrit ce que dit le dépôt, pas ce que votre situation juridique implique : faites trancher ce point avant d'intégrer le code.
Conclusion éditoriale
Sparrow convient aux équipes qui traitent des documents sensibles et disposent déjà d'un GPU sur site, ou d'un Mac Apple Silicon pour le backend MLX. Il ne convient pas à qui veut extraire quelques factures par mois sans administrer de modèle : le coût d'installation et la mémoire GPU requise dépassent largement le besoin. Avant d'adopter, vérifiez deux choses concrètes : le backend retenu dans requirements_sparrow_parse.txt (sparrow-parse[mlx] contre sparrow-parse) et la présence de poppler, sans lequel le traitement des PDF multi-pages échoue sur macOS. Vérifiez aussi que la GPL-3.0 est compatible avec la distribution prévue de votre produit.
Notes de la communauté