Sparrow: Dokumentenextraktion als REST-API mit lokalen Vision-LLMs
Structured data extraction, instruction calling and agentic workflows with ML, LLM and Vision LLM
Auf einen Blick
- Was ist das?
- Sparrow bündelt Vision-LLM-Extraktion, Instruction-Calling und Agenten-Workflows hinter einer REST-Schnittstelle und läuft laut README vollständig auf eigener Infrastruktur. Der Preis dafür ist eine GPL-3.0-Lizenz und eine Installation, die pro Plattform unterschiedlich zusammengesetzt werden muss.
- Für wen ist es gedacht?
- Sparrow passt zu Teams, die Rechnungen, Kontoauszüge oder Tabellenbilder in validiertes JSON überführen wollen und dafür eigene GPU-Hardware stellen, statt pro Seite einen Cloud-Dienst zu bezahlen. Wer eine reine OCR-Bibliothek sucht, die ohne Modellgewichte auskommt, oder wer die Extraktionslogik in einer permissiven Lizenz weitergeben muss, ist hier falsch.
- Darf ich es kommerziell nutzen?
- Ja, unter Bedingungen. GPL-3.0 ist eine Copyleft-Lizenz: Wenn Sie Software weitergeben, die sie enthält, müssen Sie deren Quellcode unter derselben Lizenz veröffentlichen. Wer sie nur intern betreibt, ohne sie weiterzugeben, löst diese Pflicht nicht aus.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 1 Tag.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich Python, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 15. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Welches Problem Sparrow löst und für wen
Das Projekt adressiert einen wiederkehrenden Engpass in Backend-Pipelines: Rechnungen, Kontoauszüge, Formulare und Tabellen liegen als Bild oder mehrseitiges PDF vor, die nachgelagerten Systeme erwarten aber JSON mit festen Feldtypen. Das README beschreibt Sparrow als API-first Plattform für Dokumentenintelligenz, die genau diese Übersetzung übernimmt und das Ergebnis gegen ein JSON-Schema validiert. Der Rückgabewert des Beispielaufrufs enthält neben dem Feld data auch ein Feld valid, was zeigt, dass die Schema-Prüfung Teil der Antwort ist und nicht erst im aufrufenden Code passiert.
Angesprochen sind damit weniger Einzelpersonen als Teams, die Dokumente in großem Umfang verarbeiten und dabei die Kontrolle über die Daten behalten wollen. Das README formuliert die Abgrenzung ausdrücklich: alles läuft auf eigener Infrastruktur, ohne externe API-Aufrufe und ohne Cloud-Abhängigkeit. Für Kanzleien, Buchhaltungen oder interne Plattformteams, die Belege nicht an einen Fremdanbieter schicken dürfen, ist das der eigentliche Kaufgrund. Der Preis ist die eigene Hardware, denn das README nennt eine GPU als Voraussetzung und verlangt genug Speicher für das gewählte Vision-LLM.
Drei Pipelines, eine Oberfläche
Die Architektur ist modular aufgebaut. Das README listet fünf Komponenten: sparrow-ml/llm als API-Engine, sparrow-data/parse als Vision-LLM-Bibliothek für die JSON-Extraktion, sparrow-ml/agents für die Workflow-Orchestrierung, sparrow-data/ocr als Vorverarbeitung und sparrow-ui als Weboberfläche. Entscheidend ist, dass diese Teile nicht als ein starrer Ablauf verdrahtet sind. Über den Parameter --pipeline wird ausgewählt, welcher Pfad greift, und die Dokumentation spricht von Pluggable Pipelines, die sich je nach Aufgabe mischen lassen.
Konkret bedeutet das: Sparrow Parse schickt das Dokument an ein Vision-LLM, Sparrow Instructor nutzt ein Text-LLM für Weiterverarbeitung, Prüfung und Entscheidungen, und der Agenten-Pfad orchestriert mehrere Schritte. Die Backends sind austauschbar, ohne dass sich die API-Oberfläche ändert. Genannt werden MLX auf Apple Silicon, vLLM auf NVIDIA, Ollama, Hugging Face sowie Mistral OCR als Cloud-Variante. Wer später von einer lokalen Karte auf einen Server mit NVIDIA-GPU wechselt, ändert laut README den Backend-Namen, nicht die Aufrufe seiner Anwendung. Das ist der architektonische Kern des Projekts, und er ist sauberer geschnitten als bei vielen Skriptsammlungen, die Extraktion und Modellanbindung in einer Datei vermischen.
Vom Dokument zum validierten JSON
Der Datenfluss beginnt mit einer Datei, die über den Parameter --file-path übergeben wird, und einem Schema, das als JSON-Liste im ersten Argument steht. Im README-Beispiel ist das [{"instrument_name":"str", "valuation":0}]. Die Typangabe erfolgt also direkt im Schema: str für eine Zeichenkette, 0 als Platzhalter für eine Zahl. Dieses Schema geht zusammen mit dem Dokument an das Vision-LLM, das die Felder aus dem Bild füllt. Zurück kommt ein Objekt mit data und valid, im Beispiel zwei Instrumente mit den Werten 19049 und 83488.
Bemerkenswert ist, dass die Validierung offenbar im Extraktionsschritt selbst sitzt und nicht als separater Nachbearbeitungslauf. Für Pipelines heißt das: Ein fehlgeschlagenes Schema ist am Feld valid erkennbar, ohne dass man die Rohantwort des Modells selbst parsen muss. Die Dokumentation beschreibt außerdem ein Sparrow OCR genannten Baustein für die Texterkennung als Vorverarbeitung. Wann dieser Schritt nötig ist und wann das Vision-LLM direkt auf das Bild geht, lässt sich aus dem vorliegenden README nicht ableiten. Diese Lücke sollte man vor einem Produktiveinsatz mit einem eigenen Testdokument schließen, statt sich auf die Beispielausgabe zu verlassen.
Installation: die Plattform entscheidet über die Abhängigkeiten
Die Einrichtung ist in fünf Schritte gegliedert. Zuerst pyenv install 3.12.10 und pyenv global 3.12.10, dann ein virtuelles Environment, im README als .env_sparrow_parse bezeichnet. Danach folgt das Klonen des Repositories und der Wechsel in sparrow/sparrow-ml/llm, wo pip install -r requirements_sparrow_parse.txt ausgeführt wird. Unter macOS kommt brew install poppler für die PDF-Verarbeitung hinzu. Gestartet wird der Server mit python api.py.
Der kritische Punkt liegt in der Datei requirements_sparrow_parse.txt selbst. Das README weist ausdrücklich darauf hin, dass man sie vor der Installation anpassen muss: Auf macOS mit MLX-Backend soll der Eintrag sparrow-parse[mlx] stehen, auf Linux und Windows dagegen sparrow-parse, wodurch die MLX-Bibliotheken entfallen. Wer diesen Schritt überspringt, installiert auf einer Linux-Maschine Abhängigkeiten, die dort nicht laufen. Das ist eine bewusste Entscheidung des Projekts, aber eine, die einen manuellen Eingriff in eine Anforderungsdatei erzwingt. Für reproduzierbare Builds in CI bedeutet das, dass man die Datei vor dem Installationsschritt patchen oder zwei eigene Varianten pflegen muss.
Der Beispielaufruf aus der Kommandozeile lautet ./sparrow.sh mit dem Schema als erstem Argument, gefolgt von --pipeline "sparrow-parse", --options mlx, dem Modellpfad mlx-community/Qwen2.5-VL-72B-Instruct-4bit und --file-path "data/bonds_table.png". Der Modellname wird also direkt auf der Kommandozeile gewählt, nicht in einer zentralen Konfigurationsdatei.
Wo Sparrow an Grenzen stößt
Die deutlichste Einschränkung steht in den Voraussetzungen: eine GPU mit ausreichend Speicher für das ausgewählte Vision-LLM. Das Beispielmodell Qwen2.5-VL-72B-Instruct-4bit ist ein 72-Milliarden-Parameter-Modell in 4-Bit-Quantisierung. Wer keine passende Karte im Rechner hat, kann den gezeigten Aufruf nicht nachvollziehen. Sparrow skaliert also nicht nach unten, sondern setzt Hardware voraus. Kleine Modelle sind über die --options austauschbar, aber das README nennt keine Untergrenze und keine Empfehlung, welches Modell für welche Dokumentenklasse ausreicht. Diese Entscheidung bleibt vollständig beim Betreiber.
Ein zweiter Punkt betrifft die Betriebsform. Das Projekt liefert eine Weboberfläche und einen Prefect-basierten Dashboard zur Workflow-Überwachung mit. Wer nur gelegentlich ein PDF auslesen will, trägt damit mehr Betriebsaufwand als nötig. Die Oberfläche ist für den Dauerbetrieb gedacht, nicht für den Einzelfall.
Schließlich die Lizenz. Sparrow steht unter GPL-3.0. Das README erwähnt daneben kommerzielles Licensing. Wer Sparrow in ein Produkt einbettet, das er weitergibt oder als Dienst betreibt, muss die GPL-Bedingungen prüfen und klären, ob der kommerzielle Weg nötig ist. Eine rechtliche Einschätzung kann dieser Text nicht liefern, aber die Frage gehört vor die erste Zeile Integrationscode.
Sparrow gegen eine reine OCR-Bibliothek
Die naheliegende Alternative ist eine klassische OCR-Bibliothek wie Tesseract, die Text aus einem Bild gewinnt und sonst nichts tut. Der Unterschied liegt nicht im Tempo, sondern in der Aufgabe. Tesseract liefert Zeichenketten mit Koordinaten. Wer daraus die Rechnungsnummer und den Gesamtbetrag ziehen will, schreibt danach eigene Regeln, reguläre Ausdrücke und Fallunterscheidungen für jedes Layout. Sparrow überspringt diesen Schritt: Das Vision-LLM bekommt das Bild und das Zielschema und gibt die befüllten Felder zurück, ohne dass jemand die Position der Felder im Dokument kennt.
Das ist ein anderer Trade-off, nicht automatisch der bessere. Eine OCR-Bibliothek ist deterministisch, klein und läuft ohne Modellgewichte auf jeder CPU. Sparrows Ausgabe hängt vom gewählten Vision-LLM ab und kann sich ändern, wenn man das Modell wechselt. Für Dokumente mit stabilem Layout und wenigen Feldern ist die regelbasierte Variante oft die günstigere und besser prüfbare Wahl. Sparrow spielt seine Stärke dort aus, wo Layouts wechseln und die Feldmenge groß ist, weil dann das Schema die Arbeit macht und nicht der Regelkatalog. Wer beides kombinieren will, kann Sparrow OCR als Vorverarbeitung nutzen, aber das README erklärt nicht, wann sich dieser Zwischenschritt lohnt.
Pflegeaufwand und Versionsstand
Das Repository ist nicht archiviert, der letzte Push liegt laut Metadaten bei August 2026. Die Versionshistorie zeigt v0.4.4 im September 2025, dann v0.5.0 und v0.6.0 im Mai und Juni 2026. Zwischen diesen Ständen liegen also rund acht Monate ohne Release, gefolgt von zwei Veröffentlichungen innerhalb weniger Wochen. Solche Muster deuten auf phasenweise Entwicklung hin, und sie sind ein Risikofaktor für alle, die auf einen stabilen Stand aufsetzen wollen. Wer heute integriert, sollte mit weiteren Änderungen an den --options-Namen und den Pipeline-Bezeichnungen rechnen, denn genau diese Parameter werden in der Dokumentation prominent geführt.
Hinzu kommt die Backend-Vielfalt als Pflegekosten. MLX, vLLM, Ollama, Hugging Face und Mistral OCR bedeuten fünf Anbindungen mit unterschiedlichen Abhängigkeiten und unterschiedlichem Reifegrad. Das README behandelt sie als gleichwertig, liefert aber nur für den MLX-Pfad ein vollständiges Beispiel. Wer auf vLLM oder Ollama setzt, muss die passenden Aufrufe selbst aus der Dokumentation der jeweiligen Backends zusammentragen. Bei einem Upgrade von Sparrow ist damit nicht nur die eigene Anwendung zu testen, sondern auch die Kombination aus Backend, Modell und Anforderungsdatei. Für Teams mit festem Release-Zyklus empfiehlt es sich, die Modellreferenz und den Backend-Namen explizit zu pinnen, statt sie aus der Dokumentation zu übernehmen.
Redaktionelles Fazit
Sparrow passt zu Teams, die Rechnungen, Kontoauszüge oder Tabellenbilder in validiertes JSON überführen wollen und dafür eigene GPU-Hardware stellen, statt pro Seite einen Cloud-Dienst zu bezahlen. Wer eine reine OCR-Bibliothek sucht, die ohne Modellgewichte auskommt, oder wer die Extraktionslogik in einer permissiven Lizenz weitergeben muss, ist hier falsch. Vor dem ersten Commit in die eigene Pipeline sollte man prüfen, ob der gewählte Backend-Eintrag in requirements_sparrow_parse.txt zur eigenen Plattform passt (sparrow-parse[mlx] gegen sparrow-parse), ob der Zielrechner genug GPU-Speicher für das gewählte Vision-LLM hat und ob die eigene Rechtsabteilung die GPL-3.0-Bedingungen für den geplanten Vertriebsweg akzeptiert.
Community-Notizen