README.md aktualisiert
This commit is contained in:
parent
11830c060a
commit
8f8d480c43
226
README.md
226
README.md
|
|
@ -1,208 +1,78 @@
|
|||
\# 📄 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 Tool verarbeitet sensible Finanzdaten vollständig lokal.
|
||||
|
||||
|
||||
## Supported Model
|
||||
|
||||
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.
|
||||
Das System ist auf das folgende Modell optimiert, welches sich im Verzeichnis `models/` befinden muss:
|
||||
|
||||
* **Modell:** Qwen3.5-4B-Instruct
|
||||
* **Format:** GGUF
|
||||
* **Quantisierung:** Q8_0
|
||||
|
||||
## Installation (Windows)
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
\---
|
||||
|
||||
|
||||
|
||||
\## 🚀 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. Verzeichnisstruktur vorbereiten
|
||||
|
||||
Laden sie die requirements.txt und app.py herunter und plazieren Sie die in das Projektverzeichniss.
|
||||
|
||||
- models
|
||||
- requirements.txt
|
||||
- app.py
|
||||
|
||||
### 3. Virtuelle Umgebung (venv) erstellen und aktivieren
|
||||
```cmd
|
||||
python -m venv venv
|
||||
.\venv\Scripts\activate.bat
|
||||
```
|
||||
|
||||
\[PDF Dokument]
|
||||
### 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
|
||||
|
||||
  ├──> 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)
|
||||
|
||||
**Option A: CPU-Modus **
|
||||
```cmd
|
||||
pip install -r requirements.txt --force-reinstall --no-cache-dir
|
||||
```
|
||||
|
||||
**Option B: Mit GPU-Beschleunigung (Nvidia CUDA)**
|
||||
|
||||
Falls Sie die GPU-Beschleunigung nutzen möchten, müssen vorab folgende Komponenten auf dem System installiert sein:
|
||||
* **Nvidia CUDA Toolkit**
|
||||
* **Visual Studio Build Tools**
|
||||
|
||||
1\. \*\*Stufe 1: Stammdaten via Lokaler KI (LLM)\*\*
|
||||
|
||||
  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.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
```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
|
||||
|
||||
```cmd
|
||||
set GGML_CUDA=1
|
||||
pip install -r requirements.txt --force-reinstall --no-cache-dir
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Use
|
||||
|
||||
\### 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:\*\*
|
||||
|
||||
```bash
|
||||
|
||||
GGML\_CUDA=1 pip install -r requirements.txt --force-reinstall --no-cache-dir
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
\---
|
||||
|
||||
|
||||
|
||||
\## 🎈 Benutzung
|
||||
|
||||
|
||||
|
||||
Starte die Applikation über dein Terminal:
|
||||
|
||||
```bash
|
||||
Starten Sie die Applikation aus Ihrer aktivierten virtuellen Umgebung heraus:
|
||||
|
||||
**Windows:**
|
||||
```cmd
|
||||
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.
|
||||
|
||||
## Notes
|
||||
|
||||
1\. \*\*PDF hochladen:\*\* Ziehe eine herkömmliche Rechnungs-PDF per Drag-and-Drop in die left Spalte der Streamlit-Oberfläche.
|
||||
|
||||
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.
|
||||
Loading…
Reference in New Issue