README.md

---
license: apache-2.0
language:
- de
- en
tags:
- ocr
- vision
- german
- invoice-extraction
- gguf
- llama-cpp
- ollama
pipeline_tag: image-text-to-text
---

# 👁 German-OCR-3.1

> **Das deutsche Vision-OCR-Modell von [Keyvan.ai](https://german-ocr.de) — Teil der German-OCR-3 Kollektion.**

```bash
ollama run Keyvan/german-ocr-3.1
```

---

## Die Geschichte

German-OCR-3 begann als kleine Idee: ein Modell, das **deutsche Geschäftsdokumente**
wirklich versteht — Rechnungen, Briefe, Bescheide, Quittungen, Verträge.
Nicht „auch deutsch", sondern auf deutsche Bürokratie und deutsches Layout spezialisiert.

Die **3.1-Generation** ist die feinabgestimmte, engineered + optimierte Version dieser
Kollektion. Zwei spezialisierte Modelle:

| Modell | Rolle |
|---|---|
| **👁 German-OCR-3.1** *(du bist hier)* | Vision-OCR — Bild rein, sauberes JSON raus |
| 🇩🇪 [**German-Text-3.1**](https://ollama.com/Keyvan/german-text-3.1) | Text-Assistent für Übersetzung, Zusammenfassung, Analyse, Chat |

OCR-3.1 wurde mit harten Regeln für **Halluzinations-Vermeidung** konfiguriert:
lieber `null` als geraten, Originalschreibweise behalten, sender vs. recipient
sauber trennen — das alles ist Pflicht in der Engineering-Konfiguration.

---

## ✨ Was kann das Modell?

**Bild rein → Strukturiertes JSON raus.**

| Doc-Typ | Erkennt |
|---|---|
| 🧾 **Rechnung** | sender, recipient, IBAN, USt-ID, line_items, amount_net/vat/total, due_date, payment_terms |
| 📬 **Brief** | sender, recipient, Betreff, Datum, Aktenzeichen |
| 📋 **Formular** | Felder, Werte, Unterschriften-Felder |
| 🧾 **Quittung** | Händler, Datum, Positionen, Summe, Steuersatz |
| ⚖️ **Bescheid** | Behörde, Aktenzeichen, Empfänger, Betrag, Frist |
| 📄 **Vertrag** | Parteien, Datum, Schlüsselklauseln |

### JSON Output Schema

```json
{
  "document_type": "invoice",
  "language": "de",
  "invoice_number": "...",
  "invoice_date": "YYYY-MM-DD",
  "due_date": "YYYY-MM-DD",
  "sender":    {"name": "...", "address": "...", "vat_id": "...", "iban": "..."},
  "recipient": {"name": "...", "address": "...", "customer_id": "..."},
  "line_items": [
    {"position": 1, "description": "...", "quantity": 1, "unit": "Stueck",
     "unit_price_net": 0.00, "amount_net": 0.00, "vat_rate": 19}
  ],
  "amount_net": 0.00, "amount_vat": 0.00, "amount_total": 0.00,
  "currency": "EUR",
  "notes": []
}
```

**Garantien:**
- ✅ JSON-Validität
- ✅ `null` statt erfundener Werte (Halluzinations-Stop-Regel)
- ✅ Originalschreibweise + Umlaute
- ✅ ISO-Datum, Punkt-Dezimal, EUR-Code
- ✅ sender ≠ recipient klar getrennt

---

## 🚀 Quick Start

### Ollama (1 Zeile)

```bash
ollama run Keyvan/german-ocr-3.1
```

API mit Bild:

```bash
curl http://localhost:11434/api/chat -d '{
  "model": "Keyvan/german-ocr-3.1",
  "messages": [{
    "role": "user",
    "content": "Extrahiere als JSON.",
    "images": ["BASE64_IMAGE_HERE"]
  }],
  "think": false
}'
```

### llama-server (HF GGUF, Two-File-Pattern)

```bash
hf download Keyven/german-ocr-3.1 \
  german-ocr-3.1-Q8_0.gguf \
  mmproj-german-ocr-3.1-F16.gguf

llama-server \
  -m german-ocr-3.1-Q8_0.gguf \
  --mmproj mmproj-german-ocr-3.1-F16.gguf \
  --port 8080 -ngl 99
```

---

## 📦 Files (auf [HuggingFace](https://huggingface.co/Keyven/german-ocr-3.1))

| File | Größe | Use case |
|---|---|---|
| `german-ocr-3.1-Q4_K_M.gguf` | 941 MB | Compact / Edge |
| `german-ocr-3.1-Q8_0.gguf` | 1.6 GB | ⭐ **Recommended** |
| `german-ocr-3.1-F16.gguf` | 2.9 GB | Full precision |
| `mmproj-german-ocr-3.1-F16.gguf` | 1.3 GB | **Required** für Vision (llama-server) |

> **Hinweis**: Über Ollama Hub bekommst du das Modell als single-package mit Vision —
> der mmproj-Sidecar wird nur für die manuelle llama-server-Route benötigt.

---

## 🛠 Hardware

| Variant | RAM (CPU) | VRAM (GPU) |
|---|---|---|
| Q4 + Vision | 4 GB | 4 GB |
| Q8 + Vision | 6 GB | 6 GB |
| F16 + Vision | 10 GB | 10 GB |

GPU empfohlen für Echtzeit-OCR. Context: **32 768 Tokens**.

---

## 🤝 German-OCR Familie

| | Was | Wo |
|---|---|---|
| 👁 **German-OCR-3.1** | Vision-OCR (du bist hier) | [ollama.com](https://ollama.com/Keyvan/german-ocr-3.1) · [HF](https://huggingface.co/Keyven/german-ocr-3.1) |
| 🇩🇪 **German-Text-3.1** | Text-Assistent | [ollama.com](https://ollama.com/Keyvan/german-text-3.1) · [HF](https://huggingface.co/Keyven/german-text-3.1) |
| ☁️ **German-OCR Cloud API** | Managed Service mit höherer Genauigkeit | [german-ocr.de](https://german-ocr.de) |
| 📝 **German-OCR for Word** | Office Add-in | [office.german-ocr.de](https://office.german-ocr.de) |

---

## 📜 License & Credits

**Apache License 2.0** — kommerzielle Nutzung mit Attribution erlaubt.

**NOTICE**: Aufgebaut auf [Qwen3.5](https://qwenlm.github.io/) von Alibaba Cloud.
Die German-OCR-3.1-Kollektion ist eine in Deutschland engineered + optimierte
Distribution für deutsche Geschäftsdokumente. Architecture credit: Qwen Team.

Build mit ❤️ in 🇩🇪 von **[Keyvan Hardani](https://german-ocr.de)**.