Architektur

Das Vision Model Interface ist als schlanker Drei-Modul-Aufbau in Python umgesetzt. Eine Gradio-basierte Browser-Oberfläche kapselt die Nutzerinteraktion, zwei spezialisierte Module übernehmen PDF-Verarbeitung und Export. Die Modellanbindung ist gegen einen externen, OpenAI-kompatiblen Endpunkt entkoppelt; die gesamte Konfiguration erfolgt über Umgebungsvariablen oder eine .env-Datei.

Auf einen Blick

• Drei-Modul-Architektur: Hauptanwendung (vision.py), PDF-Verarbeitung (pdf_processor.py), Export (export_handler.py)
• Gradio 6 als Web-Framework mit Tab-basierter Oberfläche und State-Verwaltung pro Sitzung
• Sequenzielle Verarbeitung mit Streaming-Statusrückmeldung an die Oberfläche (Generator-Pattern)
• Trennung von Bildverarbeitung (Pillow), PDF-Rendering (PyMuPDF) und Dokument-Export (python-docx, eigener Markdown-Konverter)
• OpenAI-kompatibler Chat-Completions-Endpunkt mit Vision-Unterstützung als externer Modelldienst
• Strukturierte Ergebnis-Datenklassen (PDFResult, ProcessingResult, PageAnalysis, PDFAnalysisResult) mit konsistenter Fehlerbehandlung
• Konfiguration ausschließlich über Umgebungsvariablen, keine persistenten Anwendungsdaten

Schichten und Komponenten

Die Anwendung lässt sich in vier Schichten gliedern.

Oberfläche (Gradio). Eine Single-Page-Anwendung mit zwei Tabs (Bildanalyse, PDF-Analyse). Pro Sitzung werden mehrere Gradio-State-Objekte gehalten — geladene PDF-Information, Auswahlliste, Original-Thumbnails, Analyseergebnis. Eingaben und Ausgaben werden über Gradio-Komponenten (Datei-Upload, Galerie, Markdown, HTML, Slider, Radio) gebunden; Tab-übergreifend gibt es keinen geteilten Zustand.

Verarbeitungs- und Orchestrierungsschicht. In vision.py liegen die Funktionen für Bildvorverarbeitung, Modellaufrufe und die Steuerung der mehrstufigen PDF-Analyse. Bilder werden mit Pillow geladen, EXIF-orientiert, skaliert und nach RGB konvertiert. PDF-Aufträge werden über eine Generator-Funktion seitenweise abgearbeitet und mit Zwischenständen an die Oberfläche zurückgegeben.

Fachmodule. Zwei separate Module kapseln spezialisierte Aufgaben:

• pdf_processor.py lädt und validiert PDFs mit PyMuPDF, erzeugt Thumbnails in niedriger Auflösung für die Vorschau und Seitenbilder in höherer Auflösung für die Analyse, parst Seitenauswahl-Ausdrücke und gibt strukturierte Ergebnisobjekte zurück.
• export_handler.py enthält die Datenklassen für das Analyseergebnis und exportiert dieses als Markdown, Word oder HTML. Eine eigene Markdown-zu-Word-Konvertierung übersetzt das vom Modell zurückgelieferte Markdown in echte Word-Formatierung (Überschriften, Listen, Tabellen, Inline-Auszeichnungen, Zitate, Code).

Modellzugang. Sämtliche Modellaufrufe gehen über zwei Funktionen (call_api für Vision-Anfragen, call_text_api für reine Textanfragen) gegen einen OpenAI-kompatiblen Chat-Completions-Endpunkt. Endpunkt, Modellname und Zugangsschlüssel sind über Umgebungsvariablen einstellbar; die Anwendung selbst hält keine Annahmen über das konkrete Modell.

Workflow

Der typische Ablauf einer PDF-Analyse durchläuft mehrere Stufen, die im folgenden Diagramm dargestellt sind:

flowchart TD
    User[Nutzerin / Nutzer]
    UI[Gradio-Oberfläche]

    subgraph Verarbeitung
        Validate[Validierung & Vorverarbeitung]
        PDFLoad[PDF laden / Metadaten]
        Thumbs[Thumbnails erzeugen]
        Select[Seitenauswahl]
        Render[Seite rendern]
        ImgPrep[Bildaufbereitung]
        VisionCall[Vision-Modell-Aufruf]
        SummaryCall[Zusammenfassungs-Aufruf]
        Export[Export Markdown / Word / HTML]
    end

    LLM[OpenAI-kompatibler<br/>Chat-Completions-Endpunkt]

    User -->|Upload Bild oder PDF| UI
    UI --> Validate
    Validate -->|PDF| PDFLoad
    PDFLoad --> Thumbs
    Thumbs --> UI
    UI -->|Seitenauswahl| Select
    Select --> Render
    Validate -->|Bild| ImgPrep
    Render --> ImgPrep
    ImgPrep --> VisionCall
    VisionCall <--> LLM
    VisionCall -->|pro Seite| UI
    VisionCall --> SummaryCall
    SummaryCall <--> LLM
    SummaryCall --> UI
    UI -->|Export-Klick| Export
    Export --> User

Nach dem Upload werden PDF-Datei und Eingabebilder zunächst geprüft (Größe, Format, Passwortschutz, EXIF). Bei einem PDF erzeugt das Verarbeitungsmodul Thumbnails niedriger Auflösung für die Vorschau-Galerie und liefert die Liste an die Oberfläche zurück. Nutzerinnen und Nutzer wählen die zu analysierenden Seiten — entweder durch Klick auf Thumbnails, durch eine manuelle Bereichseingabe oder durch die Wahl „alle Seiten".

Die eigentliche Analyse läuft sequenziell ab: Für jede ausgewählte Seite wird ein Bild in höherer Auflösung gerendert, in eine Base64-Daten-URL kodiert und mit dem gewählten Prompt an das Vision-Modell geschickt. Nach jedem Seitendurchlauf wird der aktuelle Stand per Generator an die Oberfläche zurückgegeben, sodass Fortschritt und Zwischenergebnisse sichtbar werden. Schlägt eine Seite fehl, wird der Fehler protokolliert und mit der nächsten Seite fortgefahren.

Sind alle Seiten verarbeitet, baut die Anwendung aus den erfolgreichen Einzelergebnissen einen zweiten Prompt zusammen und ruft das Modell ohne Bildanteil erneut auf, um eine konsolidierte Gesamtzusammenfassung zu erzeugen. Erst danach steht das vollständige Ergebnis-Objekt bereit, aus dem die Exporte erzeugt werden.

Modelleinsatz

Die Anwendung nutzt ein einzelnes Vision Language Model in zwei Modi: zuerst als bildverarbeitender Beschreiber für jede einzelne Seite, anschließend als reiner Textgenerator für die zusammenfassende Auswertung der Einzelergebnisse. Es kommen weder Embedding-Verfahren noch Reranking, noch agentische Steuerung zum Einsatz; die Mehrstufigkeit ergibt sich aus der zweistufigen Prompt-Kette und dem deterministischen Ablauf in der Orchestrierungsschicht.

Nebenläufigkeit und Robustheit

Die Verarbeitung einer PDF-Analyse erfolgt synchron in einem Aufruf, gibt aber über Pythons Generator-Mechanismus laufend Zwischenstände an die Gradio-Schicht zurück. Damit ist die Oberfläche während der Analyse responsiv und zeigt eine Fortschrittsanzeige. Robustheit wird durch typisierte Fehlerklassen (ErrorType, PDFErrorType) und konsistente Rückgabeobjekte erreicht: Jede Operation liefert ein Ergebnis mit success-Flag, Daten und gegebenenfalls typisierter Fehlermeldung, sodass Fehler in der Oberfläche differenziert dargestellt werden können. Pro Seite wird eine Fehlertoleranz angewandt, sodass ein einzelner Render- oder Modellfehler nicht den gesamten Lauf abbricht.

Konfiguration und Deployment

Die Konfiguration erfolgt vollständig über Umgebungsvariablen oder eine optionale .env-Datei (über python-dotenv). Konfigurierbar sind unter anderem Endpunkt-URL und Modellname für die LLM-API, Server-Port und URL-Pfad der Gradio-Anwendung sowie Render- und Vorschau-Auflösungen für die PDF-Verarbeitung. Die Anwendung legt keine persistenten Daten ab; temporäre Dateien aus Up- und Export werden über das Session-Management der Gradio-Schicht automatisch bereinigt. Telemetrie ist abgeschaltet; ausgelieferte Schriftarten beschränken sich auf System-Fonts.

Technologie-Übersicht

• Web-Oberfläche — Gradio 6 mit Blocks/Tabs-Layout, State-Komponenten und Event-Bindings
• Bildverarbeitung — Pillow (PIL) für Laden, EXIF-Korrektur, Skalierung, Farbraumkonversion, JPEG-Kodierung
• PDF-Verarbeitung — PyMuPDF (fitz) für Laden, Metadaten, Thumbnail- und Seitenrendering
• HTTP-Kommunikation — requests für Modellaufrufe und URL-Bildabruf
• Konfiguration — python-dotenv für .env-Unterstützung
• Word-Export — python-docx mit eigener Markdown-zu-Word-Konvertierung
• Markdown- und HTML-Export — eigene, abhängigkeitsfreie Konverter im Modul export_handler.py
• Modell-API — OpenAI-kompatibler Chat-Completions-Endpunkt mit Vision-Unterstützung