Fapiao Extraktor

1.1 Was ist das XteVision Invoice Extractor?

Das XteVision Invoice Extractor ist ein eigenständiger Node.js-Server zur Extraktion strukturierter Daten aus chinesischen Rechnungs-PDFs und zur Speicherung der Ergebnisse in CSV-Dateien. Diese Version läuft eigenständig – ohne ComfyUI – und kann daher auf jeder Maschine mit Node.js und optional mit einem Ollama-Visionmodell eingesetzt werden.

1.2 Kernfähigkeiten

• PDF-Verarbeitung: Umwandlung von Rechnungs-PDFs in Bilder und Textextraktion mittels OCR
• QR-Code-Decodierung: Auslesen der chinesischen Steuer-QR-Codes für autoritative Beträge und Nummern
• LLM-Integration: Nutzung eines Ollama-Visionmodells (z. B. qwen2.5vl:latest) für intelligente Feldextraktion
• CSV-Export: Schreiben von UTF-8-BOM-CSV-Dateien mit voller Chinese-Unterstützung und Excel-Kompatibilität
• Batch-Verarbeitung: Verarbeitung ganzer Ordner von Rechnungen auf einmal
• Web-UI: Bedienschnittstelle zur einfachen oder Batch-Verarbeitung

1.3 Zielgruppe

• Hauptzielgruppe: Finanz- und Buchhaltungsteams, die viele chinesische Rechnungs-PDFs schnell und genau digitalisieren wollen
• Nebenzielgruppe: Entwickler, die die Rechnungsextraktion in größere Buchhaltungs- oder ERP-Workflows integrieren

2.1 High-Level-Architektur

┌─────────────────────────────────────────────────────────────┐
│                    XteVision Invoice Extractor                     │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│  │   PDF    │──▶│   QR     │──▶│  Ollama  │──▶│   CSV    │ │
│  │Processor │   │ Decoder  │   │Extractor │   │  Writer  │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘ │
│       │              │              │              │        │
│       ▼              ▼              ▼              ▼        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Invoice Data Merger                      │  │
│  │   (QR data = Ground Truth for amounts & numbers)      │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

2.2 Kommunikationsablauf

1. Frontend → Server: PDF-Ordnerpfad über Web-UI oder REST-API hochladen
2. PDF-Processor: Rasterung der Seiten bei 300 DPI und OCR (Chinese + English)
3. QR Decoder: Erkennen und Decodieren der Steuer-QR-Codes; Parsen von Betrag, Datum und Rechnungsnummer
4. LLM Extractor: Senden von Bild und OCR-Text am Ollama-Visionmodell für Firmennamen, Steuersatz, Produkttyp und Hinweise
5. Data Merger: Zusammenführen von QR- (Ground Truth) und LLM-Daten, dann Schreiben der CSV

2.3 Bereitstellungsmodell

Der Server ist auf eigenständige, selbstgehostete Ausführung ausgelegt:

• läuft als eigenständiger Node.js-Server auf eigener Hardware
• kein ComfyUI, PyTorch oder GPU erforderlich – CPU-basiert
• das Ollama-Modell kann lokal oder auf einem Remote-Host laufen (setze OLLAMA_URL)
• alle Rechnungsdaten bleiben auf dem lokalen Server – keine Cloud-Abhängigkeit

• Node.js ≥ 18.0.0
• Ollama mit installiertem Visionmodell (z. B. qwen2.5vl:latest)
• Tesseract-OCR für die Textextraktion (mit Chinese-Sprachdaten)
• Poppler (optional, für bessere PDF-Renderung)

4.1 macOS

# Homebrew-Pakete installieren
brew install tesseract tesseract-lang poppler

# Chinese-Sprachdaten installieren
brew install tesseract-lang

# Ollama installieren
curl -fsSL https://ollama.com/install.sh | sh

# Visionmodell ziehen
ollama pull qwen2.5vl:latest

4.2 Ubuntu/Debian

# Systempakete installieren
sudo apt-get update
sudo apt-get install -y tesseract-ocr tesseract-ocr-chi-sim poppler-utils

# Ollama installieren
curl -fsSL https://ollama.com/install.sh | sh

# Visionmodell ziehen
ollama pull qwen2.5vl:latest

4.3 Windows

# Via Chocolatey installieren
choco install tesseract poppler

# Oder herunterladen von:
# Tesseract: https://github.com/UB-Mannheim/tesseract/wiki
# Poppler: https://blog.alivate.com.au/poppler-windows/

# Ollama von https://ollama.com installieren
ollama pull qwen2.5vl:latest

5.1 Installieren & Konfigurieren

# In das Projektverzeichnis wechseln
cd XteVision-standalone

# Abhängigkeiten installieren
npm install

# Konfigurationsumgebung kopieren
cp .env.example .env

# .env an die eigene Umgebung anpassen
# Besonders OLLAMA_URL, wenn Ollama auf einem anderen Host läuft

5.2 Server starten

# Server starten
npm start

# Oder mit Auto-Reload für die Entwicklung
npm run dev

Der Server startet bei http://localhost:3000.

Bearbeite die .env-Datei, um sie an deine Bereitstellung anzupassen. Folgende Schlüssel werden unterstützt:

7.1 Übersicht der Schnittstellen

7.2 Beispiele

Verarbeite eine einzelne Rechnung:

curl -X POST http://localhost:3000/api/process \
  -F "invoice=@/path/to/invoice.pdf" \
  -F "model=qwen2.5vl:latest" \
  -F "filenamePrefix=invoice_data"

Verarbeite einen Ordner von Rechnungen:

curl -X POST http://localhost:3000/api/process-folder \
  -H "Content-Type: application/json" \
  -d '{
    "folderPath": "/path/to/invoices",
    "model": "qwen2.5vl:latest",
    "filenamePrefix": "batch_invoices"
  }'

1. PDF-Verarbeitung: PDF-Seiten in Bilder umwandeln (Standard 300 DPI) und OCR ausführen (Chinese + English).
2. QR-Code-Decodierung: QR-Codes auf Rechnungs-Bildern erkennen und decodieren, dann Rechnungsnummer, Betrag und Datum parsen. QR-Daten gelten als Ground Truth für Beträge.
3. LLM-Extraktion: Bilder und OCR-Text am Ollama-Visionmodell aussenden, um Firmennamen, Steersatz, Produkttyp und Hinweise zu extrahieren.
4. Datenzusammenführung: QR-Daten haben absolute Priorität für Rechnungsnummer, Gesamtbetrag und Datum. LLM-Daten liefern Firmennamen, Steersatz, Produktinhalt und Hinweise. Der Besteuerungsbetrag und die Steuer werden aus dem QR-Gesamtbetrag mit dem LLM-Steersatz neu berechnet.
5. CSV-Erzeugung: Zusammengeführte Daten in eine CSV mit UTF-8-BOM zur Excel-Kompatibilität schreiben und den Anhänge-Modus für die Batch-Verarbeitung unterstützen.

8.1 CSV-Ausgabefelder

9.1 Ollama-Verbindungsprobleme

# Prüfe, ob Ollama läuft
ollama list

# Prüfe die Ollama-API
curl http://localhost:11434/api/tags

# Bei Remote-Ollama in .env setzen
OLLAMA_URL=http://192.168.1.100:11434

9.2 OCR funktioniert nicht

# Prüfe die Tesseract-Installation
tesseract --version

# Verfügbare Sprachen auflisten
tesseract --list-langs

# Chinese-Sprachdaten installieren, falls fehlend
# Ubuntu/Debian:
sudo apt-get install tesseract-ocr-chi-sim
# macOS:
brew install tesseract-lang

9.3 PDF wird nicht korrekt gerendert

# Stellt sicher, dass Poppler installiert ist
# Ubuntu/Debian:
sudo apt-get install poppler-utils
# macOS:
brew install poppler