diff --git a/README.md b/README.md index 52ac35f..0475107 100644 --- a/README.md +++ b/README.md @@ -1,208 +1,123 @@ -\# 📄 Enterprise PDF-zu-XRechnung-Konverter (Hybrid-Architektur) +# README +## Description +Dieses Tool konvertiert Rechnungen im PDF-Format vollautomatisch in das offizielle XRechnung-XML-Format (UBL-Standard, Version 3.0). Das System verarbeitet sensible Finanzdaten vollstĂ€ndig lokal auf der eigenen Hardware und verzichtet auf externe Cloud-Schnittstellen. -Dieses Tool ist ein hochprĂ€ziser, datenschutzkonformer Konverter, der herkömmliche B2B-Rechnungen im PDF-Format vollautomatisch in gesetzeskonforme \*\*XRechnung-XMLs (UBL-Standard, Version 3.0)\*\* transformiert. +Die Anwendung nutzt eine Hybrid-Architektur: +* **Stammdaten (Kopfdaten):** Ein lokales Large Language Model (LLM) extrahiert unstrukturierte Metadaten wie Rechnungsnummern, Datumsangaben, Bestell-Referenzen und Kundenadressen. Die Steuerung erfolgt ĂŒber eine strikte JSON-Schema-Grammatik. +* **Positionen (Tabelle):** Ein nativer Python-Algorithmus extrahiert Artikelbeschreibungen, Mengen, Einheiten und Einzelpreise ĂŒber regulĂ€re AusdrĂŒcke (Regex). Die finale Summenberechnung erfolgt finanzmathematisch prĂ€zise ĂŒber das `decimal`-Modul inklusive kaufmĂ€nnischem Runden. +## Supported Model +Das System ist auf das folgende Modell optimiert, welches sich im Verzeichnis `models/` befinden muss: -Das System setzt auf einen \*\*innovativen Hybrid-Ansatz\*\*: Es kombiniert die semantische FlexibilitĂ€t eines modernen, lokalen Large Language Models (LLM) fĂŒr unstrukturierte Kopfdaten mit der unfehlbaren mathematischen PrĂ€zision von nativem Python-Code fĂŒr die Positionstabelle. +* **Modell:** Qwen3.5-4B-Instruct +* **Format:** GGUF +* **Quantisierung:** Q8_0 +Hinweis: Es muss zwingend die Instruct-Variante des Modells verwendet werden. Das Basis-Modell (Base) ist fĂŒr diese Anwendung nicht kompatibel. +## Installation (Windows) -\--- - - - -\## 🚀 Key Features - - - -\* \*\*100 % Lokale AusfĂŒhrung \& DSGVO-konform:\*\* Keine Cloud-APIs (kein OpenAI, Anthropic etc.). Alle Daten verbleiben vollstĂ€ndig auf der eigenen Hardware. Absolute DatensouverĂ€nitĂ€t fĂŒr sensible Finanzdaten. - -\* \*\*Kugelsichere Tabellen-Extraktion:\*\* Positionen, Mengen, Einheiten und Einzelpreise werden mittels optimierter regulĂ€rer AusdrĂŒcke (Regex) fehlerfrei ausgelesen – komplett immun gegen KI-Halluzinationen oder Token-AbbrĂŒche. - -\* \*\*Finanzmathematische PrĂ€zision:\*\* Berechnung aller Netto-, MwSt- und Bruttosummen mittels Pythons `decimal`-Modul inklusive striktem \*\*kaufmĂ€nnischen Runden (`ROUND\_HALF\_UP`)\*\*. Keine Floating-Point-Ungenauigkeiten. - -\* \*\*Human-in-the-Loop Frontend:\*\* Eine interaktive Streamlit-OberflĂ€che erlaubt die sofortige visuelle Kontrolle und manuelle Korrektur aller extrahierten Daten vor dem finalen Export. - -\* \*\*Validierte XML-Ausgabe:\*\* Generiert valides UBL-2.1-Invoice-XML, das die strengen KonformitĂ€tsprĂŒfungen der offiziellen Koordinierungsstelle fĂŒr IT-Standards (KoSIT) fehlerfrei (\*\*0 Fehler\*\*) besteht. - - - -\--- - - - -\## 🛠 Wie es funktioniert (Hybrid-Architektur) - - - -Das Tool teilt die Extraktion in zwei spezialisierte Verarbeitungsstufen auf: - +### 1. Systemvoraussetzungen (Nur fĂŒr GPU-Beschleunigung / Option A) +Falls Sie die GPU-Beschleunigung nutzen möchten, mĂŒssen vorab folgende Komponenten auf dem System installiert sein: +* **Nvidia CUDA Toolkit** (Empfohlen: Version 12.1 bis 12.6) +* **Visual Studio Build Tools** (Bei der Installation muss der Workload *"Desktopentwicklung mit C++"* ausgewĂ€hlt sein, damit der C++ Compiler `cl.exe` verfĂŒgbar ist) +*FĂŒr den reinen CPU-Modus (Option B) werden diese Komponenten nicht benötigt.* +### 2. Verzeichnisstruktur vorbereiten +Erstellen Sie im Projektverzeichnis den Ordner fĂŒr das lokale KI-Modell: +```cmd +mkdir models ``` -\[PDF Dokument] - - │ - - ├──> Stufe 1: Lokale KI (Qwen3.5-Instruct) ──> Extraktion von Metadaten (Kunde, Adresse, Datum, Referenz) - - │ - - └──> Stufe 2: Pure Python Engine (Regex) ──> Extraktion der Artikel (Beschreibung, Menge, Einheit, Preis) - +### 3. Virtuelle Umgebung (venv) erstellen und aktivieren +```cmd +python -m venv venv +.\venv\Scripts\activate.bat ``` +### 4. Modell platzieren +Laden Sie die Modelldatei `Qwen3.5-4B-Instruct-Q8_0.gguf` herunter und platzieren Sie diese im Ordner `models/`. +### 5. AbhĂ€ngigkeiten installieren +WĂ€hlen Sie je nach Systemkonfiguration **eine** der beiden Optionen in der aktivierten Eingabeaufforderung aus: -1\. \*\*Stufe 1: Stammdaten via Lokaler KI (LLM)\*\* +**Option A: Mit GPU-Beschleunigung (Nvidia CUDA)** +```cmd +set GGML_CUDA=1 +pip install -r requirements.txt --force-reinstall --no-cache-dir +``` - Kopfdaten wie Rechnungsnummer, Datumsangaben, Bestell-Referenzen und Kundenadressen wandern auf Rechnungen visuell stark hin und her. Hier glĂ€nzt das lokale KI-Modell: Es versteht den Kontext des gesamten Texts und extrahiert diese unstrukturierten Metadaten zuverlĂ€ssig. Um strukturelle Fehler zu vermeiden, wird die KI ĂŒber eine strikte JSON-Schema-Grammatik (`LlamaGrammar`) gezwungen, die Daten exakt in ein vordefiniertes Pydantic-Schema zu gießen. +**Option B: Reiner CPU-Modus (Keine Nvidia-Grafikkarte vorhanden)** +```cmd +pip install -r requirements.txt --force-reinstall --no-cache-dir +``` +--- +## Installation (Linux) -2\. \*\*Stufe 2: Positionen via Python-Regex\*\* - - Finanztabellen erfordern 0 % Fehlertoleranz. Statt das LLM mit langen Tabellen zu ĂŒberfordern (Gefahr von AbbrĂŒchen oder Zahlendrehern), scannt ein robuster Python-Algorithmus den extrahierten Textstrom nach Mustern von Mengenangaben und Einheiten (z. B. `1,375 Tag(e)` oder `2 Std.`). Er greift sich nachgelagerte Preise, isoliert den zugehörigen Beschreibungstext (auch bei komplexen mehrzeiligen UmbrĂŒchen) und filtert irrelevante Systemtexte automatisch heraus. - - - -\--- - - - -\## đŸ€– Das KI-Modell - - - -Das Tool ist exakt auf das folgende Open-Weights-Modell optimiert: - -\* \*\*Modell:\*\* `Qwen3.5-4B-Instruct` - -\* \*\*Format:\*\* GGUF (optimiert fĂŒr CPU/GPU-Inferenz via `llama-cpp`) - -\* \*\*Quantisierung:\*\* `Q8\_0` (Hohe Genauigkeit bei exzellenter Performance) - - - -\*\*Wichtig:\*\* Es muss zwingend die \*\*`Instruct`\*\*-Version des Modells verwendet werden (`Qwen3.5-4B-Instruct-Q8\_0.gguf`), da das reine Base-Modell nicht in der Lage ist, strukturierte Systemanweisungen und JSON-Grammatiken korrekt zu befolgen. - - - -\--- - - - -\## đŸ’» Installation \& Setup - - - -\### 1. Repository klonen \& Ordnerstruktur vorbereiten +### 1. Systemvoraussetzungen (Nur fĂŒr GPU-Beschleunigung / Option A) +Falls Sie die GPU-Beschleunigung unter Linux nutzen möchten, mĂŒssen vorab folgende Komponenten installiert sein: +* **Nvidia CUDA Toolkit** +* **Build-Essentials** (GCC/G++ Compiler) +### 2. Verzeichnisstruktur vorbereiten ```bash - -git clone \[https://github.com/dein-username/pdf-to-xrechnung.git](https://github.com/dein-username/pdf-to-xrechnung.git) - -cd pdf-to-xrechnung - -mkdir -p models - +mkdir models ``` - - -\### 2. Lokales Modell herrichten - -Lade das GGUF-Modell von Hugging Face (z. B. aus dem Repository von `bartowski`) herunter und platziere es im `models`-Ordner: - -\* \*\*Pfad:\*\* `models/Qwen3.5-4B-Instruct-Q8\_0.gguf` - - - -\### 3. Requirements erstellen (`requirements.txt`) - -FĂŒr ein sauberes und schlankes Repository erstelle eine `requirements.txt` mit folgendem minimalen Inhalt: - -```text - -streamlit==1.58.0 - -llama\_cpp\_python==0.3.32 - -pydantic==2.13.4 - -pymupdf==1.28.0 - -``` - - - -\### 4. AbhĂ€ngigkeiten installieren (inkl. GPU-Beschleunigung) - -Aktiviere deine virtuelle Umgebung (`venv`) und fĂŒhre den passenden Befehl aus, damit das KI-Modell deine Nvidia-Grafikkarte (CUDA) fĂŒr rasend schnelle Antworten nutzt: - - - -\*\*Unter Windows (PowerShell):\*\* - -```powershell - -$env:GGML\_CUDA="1"; pip install -r requirements.txt --force-reinstall --no-cache-dir - -``` - - - -\*\*Unter Linux / macOS:\*\* - +### 3. Virtuelle Umgebung (venv) erstellen und aktivieren ```bash - -GGML\_CUDA=1 pip install -r requirements.txt --force-reinstall --no-cache-dir - +python3 -m venv venv +source venv/bin/activate ``` +### 4. Modell platzieren +Laden Sie die Modelldatei `Qwen3.5-4B-Instruct-Q8_0.gguf` herunter und platzieren Sie diese im Ordner `models/`. +### 5. AbhĂ€ngigkeiten installieren +WĂ€hlen Sie je nach Systemkonfiguration **eine** der beiden Optionen im aktivierten Terminal aus: -\--- - - - -\## 🎈 Benutzung - - - -Starte die Applikation ĂŒber dein Terminal: - +**Option A: Mit GPU-Beschleunigung (Nvidia CUDA)** ```bash +GGML_CUDA=1 pip install -r requirements.txt --force-reinstall --no-cache-dir +``` +**Option B: Reiner CPU-Modus (Keine Nvidia-Grafikkarte vorhanden)** +```bash +pip install -r requirements.txt --force-reinstall --no-cache-dir +``` + +--- + +## Use + +Starten Sie die Applikation aus Ihrer aktivierten virtuellen Umgebung heraus: + +**Windows:** +```cmd streamlit run app.py - ``` +**Linux:** +```bash +streamlit run app.py +``` +Der Konversionsprozess gliedert sich in folgende Schritte: +1. **Dokumenten-Upload:** Laden Sie die Rechnungs-PDF ĂŒber die WeboberflĂ€che hoch. +2. **Extraktion:** Starten Sie die hybride Analyse ĂŒber den dafĂŒr vorgesehenen Button. +3. **Validierung:** PrĂŒfen Sie die extrahierten Kopfdaten und die Positionstabelle in der BenutzeroberflĂ€che. Da alle Felder editierbar sind, können Korrekturen direkt vorgenommen werden. +4. **Export:** Generieren Sie die finale XML-Datei ĂŒber die Export-Funktion und starten Sie den Download. -1\. \*\*PDF hochladen:\*\* Ziehe eine herkömmliche Rechnungs-PDF per Drag-and-Drop in die left Spalte der Streamlit-OberflĂ€che. +## Notes -2\. \*\*Daten extrahieren:\*\* Klicke auf `🚀 Daten extrahieren`. Im Hintergrund analysiert die hybride Engine das Dokument. - -3\. \*\*PrĂŒfen \& Editieren:\*\* In der rechten Spalte erscheinen alle erkannten Kopfdaten sowie die editierbare Positionstabelle. Du kannst jeden Wert manuell anpassen, Zeilen löschen oder hinzufĂŒgen. - -4\. \*\*Exportieren:\*\* Klicke auf `🔒 XRechnung exportieren`. Das Tool berechnet kaufmĂ€nnisch alle Summen und stellt dir die fertige, konforme XML-Datei direkt als Download (`đŸ“„ Download XML`) bereit. - - - -\--- - - - -\## ⚖ Rechtliche \& Finanzmathematische Hinweise - - - -\* \*\*GoBD-KonformitĂ€t:\*\* Dieses Tool generiert das strukturierte XML-Format. Der Nutzer ist selbst dafĂŒr verantwortlich, sowohl die Original-PDF als auch die generierte XML-Datei gemĂ€ĂŸ den GoBD-Richtlinien revisionssicher fĂŒr 10 Jahre zu archivieren. - -\* \*\*PrĂŒfpflicht:\*\* Das Tool arbeitet nach dem Prinzip \*„Human-in-the-Loop“\*. Vor dem XML-Export ist eine kurze visuelle Endkontrolle der extrahierten Daten im Streamlit-Frontend durch den Sachbearbeiter zwingend empfohlen. +### Human-in-the-Loop +Das Tool dient als Automations-Assistent. Vor dem finalen XML-Export ist eine visuelle Endkontrolle der extrahierten Daten (insbesondere Rechnungsnummer und EmpfĂ€ngeradresse) durch den Sachbearbeiter zwingend erforderlich, um KI-Fehlinterpretationen auszuschließen. +### GoBD-KonformitĂ€t +Das Tool generiert ausschließlich das strukturierte XML-Format. FĂŒr die Einhaltung der GoBD-Richtlinien (u. a. die revisionssichere Archivierung der Original-PDF sowie der generierten XML-Datei ĂŒber den gesetzlichen Zeitraum von 10 Jahren) ist der Betreiber der Software selbst verantwortlich. \ No newline at end of file