Zum Inhalt

TextWerkstatt — Architektur

TextWerkstatt ist als containerisierte Web-Anwendung mit klarer Schichtentrennung aufgebaut. Eine Gradio-basierte Oberfläche kommuniziert mit einer asynchronen Verarbeitungsschicht, die Aufgaben je nach Modus an einen einfachen Chat-Pfad oder eine mehrstufige Pipeline weiterleitet. Backend-seitig werden ausschließlich interne Dienste angesprochen — zwei OpenAI-kompatible LLM-Endpunkte sowie ein Embedder und ein Reranker für semantisches Retrieval und Faktenabgleich.

Auf einen Blick

  • Schichtenmodell: Oberfläche, Modus-Router, Pipeline und Intent-Handler, Speicher (Inventar, Versionsliste, Scope), Konnektoren (LLM, Embedder, Reranker, Datei-Reader), Exporter.
  • Asynchrone Verarbeitung mit Semaphore-basierter Parallelisierungssteuerung pro Backend-Dienst.
  • Zwei Modi mit gemeinsamem Profil-Kontext: Chat-Pfad und mehrstufige Pipeline.
  • Zwei LLM-Slots (Primary, Fast) mit konfigurierbarer Modellfamilie und automatischer Reasoning-Steuerung.
  • Inventar als zentrale Datenstruktur für Retrieval und Halluzinations-Zweitcheck.
  • Versionsverwaltung mit Cursor-Modell und Markierung abgezweigter Stände.
  • Containerisiertes Deployment hinter Reverse-Proxy mit Streaming-Unterstützung für lange Läufe.

Architekturbeschreibung

Komponenten

Die Anwendung gliedert sich in sieben funktionale Schichten.

Oberfläche. Eine Gradio-Oberfläche stellt Eingabefeld, Datei-Upload, Profil-Auswahl, Modus-Anzeige, Arbeitsplan-Vorschau, Versionsliste und Export-Buttons bereit. Sie kommuniziert über die Gradio-eigene Streaming-Schnittstelle mit dem Backend.

Modus-Router. Beim Ersteinstieg entscheidet der Modus-Router anhand des Aufgabenprofils, des Material-Umfangs und der Eingabelänge, ob der Chat-Pfad oder die Pipeline ausgeführt wird. Bestimmte Profile sind grundsätzlich der Pipeline zugewiesen; eine manuelle Auswahl ist ebenfalls möglich.

Verarbeitung. Der Chat-Pfad führt einen einzelnen Modellaufruf mit dem profilspezifischen System-Prompt aus. Die Pipeline durchläuft fünf Phasen: eine LLM-gestützte Bestandsaufnahme des Materials mit Erkennung von Schlüsselelementen, Lücken und offenen Rückfragen; eine Dekomposition in einen Arbeitsplan mit Abschnittsstruktur, Anweisungen und Qualitätskriterien; eine sequentielle Abschnittsverarbeitung; eine Qualitätsprüfung gegen Material und Kriterien mit optionaler Korrekturschleife; sowie eine abschließende Homogenisierung des Gesamtdokuments.

Inventar und Retrieval. Hochgeladenes Material wird optional inventarisiert: Ein LLM segmentiert das Dokument in semantische Einheiten (z.B. TOPs, Beschlüsse, Kapitel, Kriterien, Codeblöcke), die mit Titel, Kurzabriss und Volltext erfasst werden. Jeder Eintrag erhält einen Embedding-Vektor; der gesamte Index wird im Speicher gehalten. Pipeline-Schritte, die material-bezogenes Retrieval benötigen, fragen den Index per Cosinus-Ähnlichkeit ab und lassen die Treffer optional durch den Reranker nachsortieren.

Intent-Router und Scope. Nach der Erstgenerierung wandelt der Intent-Router jede Folge-Eingabe in eine klassifizierte Operation um. Klassifikationen mit hoher Konfidenz werden direkt ausgeführt, mittlere lösen eine Bestätigung aus, niedrige eine Rückfrage. Der Scope-Manager begrenzt Operationen auf Gesamtdokument, Abschnitt oder Absatz und bestimmt, welche Edit-Strategie greift — Volltext, abschnittsweise oder chirurgisch.

Speicher. Drei In-Memory-Strukturen halten den Sitzungszustand: das Inventar mit Embeddings, eine cursor-basierte Versionsliste mit Verzweigungs-Markierung und der aktuelle Scope. Es findet keine persistente Datenhaltung statt; jede Sitzung beginnt mit leerem Zustand.

Exporter. Drei Exporter erzeugen Word-, Markdown- und Text-Dateien mit Herkunfts-Footer. Der Word-Exporter konvertiert die intern verwendete Markdown-Repräsentation in strukturierte .docx-Dokumente.

Workflow-Diagramm

flowchart TB
    User[Nutzende] --> UI[Gradio-Oberfläche]
    UI --> Upload[Datei-Reader]
    Upload --> Inventar[Inventarisierung]
    Inventar --> Embedder[(Embedder)]
    Inventar --> Index[Inventar-Index]

    UI --> Router{Modus-Router}
    Router -->"kurz / einfach"| Chat[Schnellmodus / Chat]
    Router -->"umfangreich / komplex"| Pipeline

    subgraph Pipeline[Werkstatt-Pipeline]
        direction TB
        P1[1. Analyse] --> P2[2. Arbeitsplan]
        P2 --> P3[3. Abschnittsverarbeitung]
        P3 --> P4[4. Qualitätsprüfung]
        P4 --> P5[5. Homogenisierung]
    end

    Chat --> LLM_P[(Primäres LLM)]
    P1 --> LLM_P
    P2 --> LLM_P
    P3 --> LLM_F[(Schnelles LLM)]
    P4 --> LLM_P
    P4 --> SemCheck[Semantischer Faktenabgleich]
    SemCheck --> Embedder
    SemCheck --> Index
    P5 --> LLM_P

    Index --> P3
    Reranker[(Reranker)] --> P3

    Pipeline --> Doc[Ergebnis-Dokument]
    Chat --> Doc

    Doc --> History[Versionsliste]
    Doc --> Intent{Intent-Router}
    Intent --> Scope[Scope: gesamt / Abschnitt / Absatz]
    Scope --> Handler[Handler: deterministisch / LLM / LLM+Retrieval]
    Handler --> LLM_P
    Handler --> LLM_F
    Handler --> Doc

    Doc --> Export[Exporter]
    Export --> Word[Word .docx]
    Export --> MD[Markdown .md]
    Export --> Text[Text .txt]

Das Diagramm zeigt den Datenfluss von der Eingabe bis zum Export. Hochgeladenes Material wird optional inventarisiert, wobei der Embedder Vektoren für jeden Eintrag erzeugt. Der Modus-Router entscheidet zwischen Chat-Pfad und Pipeline. Die Pipeline ruft das primäre Modell für qualitätskritische Phasen (Analyse, Plan, Prüfung, Homogenisierung) und das schnelle Modell für die Abschnittsverarbeitung auf; bei vorhandenem Inventar greifen Abschnittsverarbeitung und Qualitätsprüfung auf den Index zurück, in der Prüfung zusätzlich für den semantischen Faktenabgleich. Folge-Eingaben werden durch den Intent-Router klassifiziert und über einen Scope auf den passenden Dokumentteil angewendet, bevor sie wieder in das Ergebnis-Dokument zurückfließen. Versionsliste und Exporter operieren auf dem aktuellen Dokumentstand.

Rolle der KI-Komponenten

Primäres LLM. Verantwortlich für Schritte, bei denen Qualität und Kohärenz entscheidend sind: Material-Analyse, Erstellung des Arbeitsplans mit abschnittsweiser Aufgabenstruktur, Qualitätsprüfung gegen Kriterien und Material, Korrektur erkannter Mängel und finale Homogenisierung.

Schnelles LLM. Verantwortlich für die abschnittsweise Verarbeitung im Werkstattmodus sowie für kleine Edits durch den Intent-Router. Bei nicht konfiguriertem Sekundärmodell übernimmt das primäre LLM diese Aufgaben.

Embedder. Erzeugt Vektoren für die Inventareinträge sowie für die im semantischen Faktenabgleich extrahierten Aussagen. Erkennt die Endpunkt-Variante (OpenAI-Stil oder HuggingFace TEI) automatisch.

Reranker. Sortiert Retrieval-Kandidaten nach Anfrage-Relevanz nach. Wird optional eingesetzt, wenn der Embedder mehr Kandidaten als nötig liefert; bei Ausfall fällt das System auf die Embedding-Sortierung zurück.

Agentische Pipeline. Die Phasen agieren als spezialisierte Schritte mit eigenen Prompts, Aufgabenstellungen und Modell-Zuordnungen. Statt eines einzelnen Modellaufrufs durchläuft eine komplexe Aufgabe mehrere Stationen, die jeweils ihr Zwischenergebnis dokumentieren und der nächsten Station übergeben.

Nebenläufigkeit und Robustheit

Die Verarbeitung ist durchgängig asynchron. Pro LLM wird ein Semaphor mit konfigurierbarer Tiefe genutzt, um die Anzahl gleichzeitiger Backend-Aufrufe zu begrenzen. Die Gradio-Queue lässt pro Bearbeitung nur eine Pipeline gleichzeitig laufen, sodass kein Wettstreit um Modell-Slots entsteht. Antworten der Modelle werden mit dreistufigem JSON-Parsing dekodiert (direkt, aus Markdown-Codeblock, aus erstem JSON-Block); fällt eine Antwort durch, greift ein Fallback. Pipeline-Phasen kapseln Fehler so, dass einzelne Abschnitts-Fehler den Gesamtlauf nicht abbrechen; nicht-erfolgreiche Abschnitte werden gekennzeichnet. Backend-Calls verfügen über getrennt konfigurierbare Timeouts.

Konfiguration und Deployment

Konfiguriert wird über Umgebungsvariablen einer .env-Datei: Endpunkte und API-Schlüssel der vier Backend-Dienste, Modellfamilien für die Reasoning-Steuerung, Schwellwerte für Modus-Router und semantischen Halluzinations-Check sowie Pipeline-Parameter wie maximale Abschnittszahl und Korrektur-Iterationen. Das Deployment erfolgt als Container; eine Reverse-Proxy-Konfiguration mit aktivem WebSocket-Upgrade, deaktiviertem Buffering und großzügigen Timeouts unterstützt die mehrminütigen Pipeline-Läufe und Datei-Uploads bis 50 MB.

Technologien

  • Oberfläche. Gradio (Python-Framework für interaktive Web-Oberflächen) mit eigenem CSS.
  • LLM-Integration. OpenAI-kompatibler Async-Client (openai-Python-SDK), erweitert um vLLM-spezifische Reasoning-Schalter über chat_template_kwargs.
  • HTTP. httpx als asynchroner HTTP-Client für Embedder- und Reranker-Aufrufe.
  • Datei-Reader. python-docx für Word-Dokumente, pdfminer.six für PDFs, python-pptx für PowerPoint, Standard-Bibliothek für txt/md/csv/html.
  • Word-Export. python-docx mit eigenem Markdown-zu-DOCX-Konverter.
  • Konfiguration. python-dotenv für .env-Dateien.
  • Deployment. Docker-Container, betrieben hinter nginx als Reverse-Proxy mit WebSocket-Upgrade.