123 lines
4.8 KiB
Markdown
123 lines
4.8 KiB
Markdown
# 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.
|
|
|
|
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:
|
|
|
|
* **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)
|
|
|
|
### 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
|
|
```
|
|
|
|
### 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:
|
|
|
|
**Option A: Mit GPU-Beschleunigung (Nvidia CUDA)**
|
|
```cmd
|
|
set GGML_CUDA=1
|
|
pip install -r requirements.txt --force-reinstall --no-cache-dir
|
|
```
|
|
|
|
**Option B: Reiner CPU-Modus (Keine Nvidia-Grafikkarte vorhanden)**
|
|
```cmd
|
|
pip install -r requirements.txt --force-reinstall --no-cache-dir
|
|
```
|
|
|
|
---
|
|
|
|
## Installation (Linux)
|
|
|
|
### 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
|
|
mkdir models
|
|
```
|
|
|
|
### 3. Virtuelle Umgebung (venv) erstellen und aktivieren
|
|
```bash
|
|
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:
|
|
|
|
**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.
|
|
|
|
## Notes
|
|
|
|
### 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. |