Architektur

STT-Helper folgt einer Trennung zwischen interaktivem Web-Frontend und asynchronem Verarbeitungs-Worker. Die Anwendung bietet kein dauerhaftes Ergebnis-Display im UI, sondern stellt einen Auftrag in eine Job-Queue ein; die eigentliche, langlaufende LLM-Verarbeitung findet entkoppelt statt und mündet in einer E-Mail-Zustellung. Das Frontend bleibt dadurch responsiv und ist nicht an die Lebensdauer der Browsersitzung gebunden.

Auf einen Blick

• Trennung zwischen Web-Frontend, Job-Queue und Worker-Prozess
• Asynchrone Hintergrundverarbeitung; Ergebnis per E-Mail
• Chunkbasierte Pipeline mit semaphor-begrenzter Parallelität
• Kumulative Drei-Stufen-Verarbeitung über getrennte Prompts
• Dateibasierte Job-Konfiguration in einem temporären Arbeitsverzeichnis
• HTTP/JSON-Anbindung an eine LLM-API mit Retry und Timeout
• Zustandloses Frontend; persistenter Zustand nur in einer einfachen Statistikdatei

Komponenten

Die Anwendung besteht aus drei aktiven Bestandteilen und mehreren Anbindungen:

• Web-Frontend: nimmt Eingabe entgegen, validiert Datei und E-Mail, legt ein temporäres Arbeitsverzeichnis mit Eingangstext und Konfigurationsdatei an und übergibt einen Auftrag an die Job-Queue.
• Job-Queue: vermittelt Aufträge zwischen Frontend und Worker. Aufträge werden im Hintergrundmodus übergeben; das Frontend erhält keine Rückmeldung über den Verarbeitungsfortschritt.
• Worker-Prozess: liest die Job-Konfiguration, führt das Chunking durch, ruft die LLM-API stufenweise auf, fügt die Ergebnisse zusammen und übergibt die Ergebnisdatei an den E-Mail-Versand.
• LLM-API: extern angesprochener HTTP-Endpunkt, der pro Chunk und Stufe einmal aufgerufen wird.
• E-Mail-Versand: Hilfsprogramm für die Zustellung des Ergebnisses bzw. einer Fehlermeldung.

Workflow

flowchart TD
    User[Nutzer]
    UI[Web-Frontend]
    Validate[Validierung]
    Workdir[Arbeitsverzeichnis<br/>Eingang + Config]
    Queue[Job-Queue]
    Worker[Worker-Prozess]
    Chunker[Chunking + Überlappung]
    Stage1[Stufe 1: Korrektur]
    Stage2[Stufe 2: Überarbeitung]
    Stage3[Stufe 3: Formatierung]
    LLM[LLM-API]
    Merge[Zusammenführung]
    Result[Ergebnisdatei]
    Mailer[E-Mail-Versand]
    Mailbox[Postfach Nutzer]

    User -->|Datei oder Text| UI
    UI --> Validate
    Validate -->|gültig| Workdir
    Workdir --> Queue
    Queue --> Worker
    Worker --> Chunker
    Chunker --> Stage1
    Stage1 -->|HTTP/JSON| LLM
    LLM --> Stage1
    Stage1 --> Stage2
    Stage2 -->|HTTP/JSON| LLM
    LLM --> Stage2
    Stage2 --> Stage3
    Stage3 -->|HTTP/JSON| LLM
    LLM --> Stage3
    Stage1 --> Merge
    Stage2 --> Merge
    Stage3 --> Merge
    Merge --> Result
    Result --> Mailer
    Mailer --> Mailbox
    Mailbox --> User

Der Ablauf beginnt mit der Eingabe im Web-Frontend. Nach erfolgreicher Validierung wird ein temporäres Arbeitsverzeichnis angelegt, das den Eingangstext und eine Konfigurationsdatei mit Empfänger, gewählter Endstufe, Sprachvorgabe und Kontext enthält. Das Frontend übergibt diesen Pfad an die Job-Queue und meldet dem Nutzer die erfolgreiche Auftragsannahme; die Browsersitzung kann anschließend geschlossen werden.

Der Worker-Prozess wird durch die Queue gestartet, lädt die Konfiguration und liest den Eingangstext ein. Anschließend zerlegt er den Text in Chunks fester Länge mit Überlappung. Pro aktivierter Stufe wird der LLM-API-Aufruf für jeden Chunk parallel ausgeführt, begrenzt durch eine Semaphore. Bei vorübergehenden Fehlern werden bis zu fünf Wiederholversuche mit ansteigender Wartezeit unternommen. Die Ergebnisse einer Stufe gehen als neue Eingabe in die nächste Stufe ein.

Beim abschließenden Zusammenfügen wählt der Worker pro Chunk das höchstwertige erfolgreiche Zwischenergebnis und fällt bei dauerhafter Fehlerhaftigkeit auf den Originalabschnitt mit Fehlernotiz zurück. Die Ergebnisdatei wird unter einem Namen abgelegt, der die Endstufe widerspiegelt, und an den E-Mail-Versand übergeben. Nach Zustellung wird das Arbeitsverzeichnis vollständig entfernt.

Rolle des LLM in der Pipeline

Die Anwendung nutzt ein einziges LLM, ruft es jedoch in jeder Stufe mit einem dedizierten Prompt auf. Die Stufen verfolgen unterschiedliche Aufgaben (sprachliche Korrektur, stilistische Überarbeitung, Markdown-Strukturierung) und werden nicht in einem einzigen, vermischten Aufruf gebündelt. Embedder, Reranker oder agentische Entscheidungslogik kommen nicht zum Einsatz; die Pipeline ist deterministisch in der Reihenfolge der Stufen und in der Abbildung Chunk → API-Aufruf.

Nebenläufigkeit und Robustheit

Die Parallelität ist über eine Semaphore auf eine feste Zahl gleichzeitig laufender Chunk-Aufrufe begrenzt. Damit wird die Last auf der LLM-API beschränkt und die Aufrufrate vorhersehbar gehalten. Pro Chunk und Stufe sind bis zu fünf Wiederholversuche mit progressiver Verzögerung vorgesehen; ein dauerhaft fehlerhafter Chunk verhindert weder die Verarbeitung anderer Chunks noch den Abschluss des Gesamtjobs. Eine Statistikdatei wird über eine Dateisperre serialisiert, um Schreibkonflikte bei parallelen Aufträgen zu vermeiden.

Konfiguration und Betrieb

Wesentliche Laufzeitparameter (Wurzelpfad, Request-Timeout) werden über Umgebungsvariablen gesteuert. Die LLM-Anbindung wird über zentrale Konstanten definiert. Die Job-Queue wird beim Start kontaktiert, das Web-Frontend bindet auf einem konfigurierbaren Port. Der Worker wird durch ein Bash-Skript orchestriert, das den Python-Verarbeitungsprozess aufruft und im Anschluss die E-Mail-Zustellung sowie das Aufräumen des Arbeitsverzeichnisses übernimmt.

Technologie-Übersicht

• Web-Frontend: Gradio (Python)
• Asynchrone HTTP-Aufrufe: asyncio, aiohttp
• Job-Queue: Gearman (Python-Client gear)
• Dateisperre: filelock
• E-Mail-Versand: sendemail (CLI)
• Orchestrierung des Worker-Laufs: Bash-Skript
• LLM-Anbindung: HTTP/JSON gegen einen Chat-Completions-kompatiblen Endpunkt