Architektur¶

Die Architektur folgt einer schichtenbasierten Struktur mit klar getrennten Verantwortlichkeiten zwischen Bedienoberfläche, Dokumentenverarbeitung, Chunking, Übersetzungs-Engine und LLM-Anbindung. Die Verarbeitung ist durchgängig asynchron umgesetzt; einzelne Übersetzungsanfragen werden parallel an den LLM-Endpunkt geschickt und über einen Rate-Limiter koordiniert. Charakteristisch ist die einheitliche Pipeline: Unabhängig vom Eingabeformat überführt eine Konvertierungsschicht den Inhalt zunächst in eine strukturierte Markdown-Darstellung, sodass alle nachgelagerten Schritte mit derselben Repräsentation arbeiten.

Auf einen Blick¶

Schichtenarchitektur: Bedienoberfläche → Dokumentenverarbeitung → Chunking → Übersetzungs-Engine → LLM-Client
Einheitliche Markdown-Zwischenrepräsentation für alle Eingabeformate
Asynchrone Ausführung über asyncio mit konfigurierbarer Worker-Anzahl
Rate-Limiter (Token-Bucket) zur Koordinierung der Anfragen an den LLM-Endpunkt
Tabellen- und codeblock-sensibles Chunking mit Boundary-Erkennung an Satz- und Absatzgrenzen
Kontextübergabe zwischen aufeinanderfolgenden Chunk-Übersetzungen
YAML-basierte Konfiguration mit Pydantic-Validierung; Standalone-Betrieb über einen einzelnen Python-Prozess

Komponenten und Workflow¶

Schichten und ihre Rolle¶

Die Anwendung besteht aus folgenden Hauptschichten:

Bedienoberfläche (src/ui, src/app.py): Gradio-basiertes Web-Interface mit Eingabe-, Ausgabe- und Steuerungsbereich, ergänzt um Export-Handler und URL-Parameter-Tracking.
Dokumentenverarbeitung (src/document_processing): Format-spezifische Prozessoren (PDF, Word, Text/Markdown) und ein Markdown-Konverter, der die unterschiedlichen Eingaben in eine einheitliche Markdown-Repräsentation überführt.
Chunking (src/chunking): Token-basierte Segmentierung mit Boundary-Erkennung, Tabellen-Awareness und Codeblock-Erkennung.
Übersetzungs-Engine (src/translation): Tabellen-bewusste Engine mit paralleler Ausführung, Wiederholungslogik und Kontextverwaltung pro Abschnitt.
LLM-Client (src/llm_client.py): Asynchroner HTTP-Client für OpenAI-kompatible Endpunkte mit thread-sicherer Sitzungsverwaltung und Exponential-Backoff.
Konfiguration (src/config.py, config/): Pydantic-validierte Einstellungen aus YAML-Dateien für LLM, Chunking, Parallelisierung, Sprachen und Export.

Datenfluss¶

flowchart TB
    User["Nutzer"] --> UI["Bedienoberfläche<br/>(Gradio)"]

    UI --> Dispatch{"Eingabe?"}
    Dispatch -->|"Datei"| DocProc["Dokumentenverarbeitung"]
    Dispatch -->|"Text"| Direct["Direkte Übernahme"]

    DocProc --> PDF["PDF-Prozessor<br/>(pymupdf4llm / PyMuPDF)"]
    DocProc --> DOCX["Word-Prozessor<br/>(python-docx)"]
    DocProc --> MDTXT["Markdown- / Text-<br/>Prozessor"]

    PDF --> MDConv["Markdown-Konverter"]
    DOCX --> MDConv
    MDTXT --> MDConv
    Direct --> MDConv

    MDConv --> Chunker["Chunker<br/>(token- und tabellenbewusst)"]

    Chunker --> Engine["Übersetzungs-Engine"]
    Engine --> Context["Kontextverwaltung<br/>(Glossar, Vorgänger-Kontext, Stil)"]
    Engine --> RateLimiter["Rate-Limiter"]
    RateLimiter --> LLMClient["LLM-Client"]
    LLMClient --> LLM["OpenAI-kompatibler<br/>LLM-Endpunkt"]
    LLM --> LLMClient
    LLMClient --> Engine

    Engine --> Reassembly["Reassemblierung<br/>(Strukturerhalt, Tabellen-Rekonstruktion)"]
    Reassembly --> Export["Export-Handler"]
    Export --> Word["Word"]
    Export --> MD["Markdown"]
    Export --> HTML["HTML"]
    Word --> User
    MD --> User
    HTML --> User

    Config["YAML-Konfiguration"] -.-> Engine
    Config -.-> Chunker
    Config -.-> LLMClient

Erläuterung des Workflows¶

Der Nutzer übergibt Eingaben entweder als Datei oder als Text. Bei Dateieingaben wählt eine Factory anhand der Dateiendung den passenden Prozessor (PDF, DOCX oder Markdown/Text). Der jeweilige Prozessor erzeugt eine Markdown-Repräsentation des Dokuments; PDF-Eingaben werden bevorzugt über pymupdf4llm verarbeitet, das eine LLM-orientierte Markdown-Ausgabe liefert. Texteingaben gelangen direkt in den Markdown-Konverter.

Die Markdown-Repräsentation wird anschließend dem Chunker übergeben, der den Inhalt in token-basierte Abschnitte zerlegt. Tabellen werden dabei als zusammenhängende Einheit behandelt; eine Boundary-Detektion sorgt dafür, dass Schnittpunkte Satz- und Absatzgrenzen folgen. Das Ergebnis ist eine Liste typisierter Chunks (Text, Tabelle, Codeblock) mit Token-Zählung und Metadaten.

Die Übersetzungs-Engine orchestriert die parallele Übersetzung der Chunks. Jeder Chunk wird mit einem eigenen Kontextobjekt versehen, das das Glossar, den Stil, die Anredeform, die aktuelle Überschrift und Zusammenfassungen vorangegangener Chunks enthält. Die Anfragen werden über einen Token-Bucket-Rate-Limiter gestaffelt und vom LLM-Client an den OpenAI-kompatiblen Endpunkt geschickt. Tabellen-Chunks durchlaufen einen spezialisierten Pfad: Kopfzeilen und Datenzeilen werden getrennt übersetzt und anschließend strukturgetreu rekonstruiert. Schlägt eine Anfrage fehl, wird sie mit exponentiellem Backoff wiederholt.

Sind alle Chunks übersetzt, fügt die Engine sie in der ursprünglichen Reihenfolge wieder zusammen und übergibt das Ergebnis an die Export-Schicht. Diese erzeugt das gewählte Zielformat (Word, Markdown oder HTML) und stellt es zum Download bereit.

Nebenläufigkeit und Robustheit¶

Die Pipeline verwendet einen einzelnen Event-Loop pro Server-Prozess. Der LLM-Client verwaltet einen Pool von HTTP-Sitzungen mit konfigurierbarer Größe und Keepalive-Dauer und überwacht die Verfügbarkeit des Event-Loops. Wiederverwendete Sitzungen reduzieren den Verbindungsaufwand. Ein Rate-Limiter beschränkt die Anzahl der Anfragen pro Sekunde an den LLM-Endpunkt. Bei Fehlern (Timeouts, vorübergehende Verbindungsabbrüche, Rate-Limit-Antworten) greift eine Wiederholungslogik mit exponentiellem Backoff. Schlägt ein Chunk dauerhaft fehl, wird er als „failed" markiert; übrige Chunks werden trotzdem zurückgegeben, sodass möglichst viel der Übersetzung erhalten bleibt.

Konfiguration und Betrieb¶

Sämtliche Einstellungen — LLM-Endpunkt, Modell, Token-Grenzen, Chunk-Größen, Worker-Anzahl, Rate-Limit, Sprachen, verfügbare Stile, Logging und Export-Optionen — sind in YAML-Dateien (config/config.yaml, config/languages.yaml) hinterlegt und werden zur Laufzeit über Pydantic-Modelle validiert. Umgebungsvariablen können einzelne Werte überschreiben. Die Anwendung wird als gewöhnlicher Python-Prozess gestartet (python main.py); die Gradio-Bedienoberfläche steht anschließend über einen konfigurierbaren Port bereit.

Technologie-Übersicht¶

Bedienoberfläche: Gradio (≥ 6.0)
Asynchroner HTTP-Client: aiohttp
PDF-Verarbeitung: pymupdf4llm (bevorzugt), PyMuPDF (Fallback)
Word-Verarbeitung: python-docx
Markdown- und HTML-Verarbeitung: markdown2, beautifulsoup4, lxml
Konfiguration und Validierung: Pydantic (≥ 2.0), pyyaml
Wiederholungslogik: tenacity
Token-Zählung: tiktoken
Spracherkennung: langdetect
System-Monitoring: psutil
Sprache und Laufzeit: Python (≥ 3.8), asyncio-basiert