Jobs

Jobs sind Indexierungs-Aufträge, die die Ingestion-Pipeline ausführen. Jeder Job verarbeitet eine Datenquelle: Dateien scannen, laden, in Chunks zerlegen und als Vektoren speichern. Jobs werden sequentiell abgearbeitet, um GPU-Konkurrenz zu vermeiden.

Übersicht & Tabelle

Der Jobs-Tab zeigt alle Indexierungs-Aufträge: wartend, laufend, abgeschlossen und fehlgeschlagen. Es gibt keine Sub-Tabs — alles ist in einer zentralen Tabelle mit Filter-Leiste zusammengefasst.

Filter-Leiste

Filter	Beschreibung
Alle	Zeigt alle Jobs (Standard).
Laufend	Nur Jobs mit Status `running` (inkl. pausierte).
Ausstehend	Jobs in der Warteschlange (`pending`).
Erfolgreich	Abgeschlossene Jobs (`success`).
Fehlgeschlagen	Jobs mit Fehler (`error`).
Abgebrochen	Manuell abgebrochene Jobs (`cancelled`).

Tabellen-Spalten

Spalte	Beschreibung	Hinweis
Datenquelle	Name der zugehörigen Datenquelle.	Sortierbar.
Embedding	Verwendetes Embedding-Modell (z.B. `nomic-embed-text`, `voyage-ai`).	Sortierbar.
Typ	Inkr. = Inkrementell (nur neue/geänderte Dateien). Voll = Voll-Indexierung (alle Dateien neu).	Sortierbar.
Status	Aktueller Status als farbiges Badge. Siehe Job-Status.	Sortierbar.
Dateien	Fortschrittsanzeige: verarbeitete / gesamte Dateien mit Fortschrittsbalken. Bei Parallel-Scan: Zwei Balken — Download-Fortschritt (orange) + Ingestion (blau).	Zeigt bei laufenden Jobs auch die aktuelle Datei an.
Restzeit	Geschätzte verbleibende Zeit (ETA), berechnet aus Verarbeitungsrate.	Nur bei laufenden Jobs sichtbar.
Gestartet	Zeitpunkt des Jobstarts.	Sortierbar. Format: `dd.mm hh:mm`
Dauer	Bisherige oder finale Laufzeit.	Bei Resume-Ketten: Gesamtdauer aller Jobs im Tooltip.
Auslöser	Wer den Job ausgelöst hat: manual, cron oder api.	Sortierbar.
Aktionen	Kontextabhängige Buttons (siehe Steuerung).	—

Tipp: Die Tabelle aktualisiert sich bei laufenden Jobs automatisch alle 3 Sekunden (Polling). Das Polling stoppt automatisch nach 3 Zyklen ohne aktive Jobs.

Job-Status

Status	Badge	Beschreibung
`pending`	Ausstehend (grau)	Job wartet in der Warteschlange. Wird automatisch gestartet, sobald kein anderer Job läuft.
`running`	Laufend (grün)	Job wird gerade verarbeitet. Fortschrittsbalken und Restzeit sichtbar.
`running` + pausiert	Pausiert (orange)	Job ist pausiert. Kann fortgesetzt werden — die Pipeline hält beim nächsten Kontrollpunkt an.
`success`	Erfolgreich (grün)	Job ist abgeschlossen. Statistiken und Datei-Protokoll verfügbar.
`error`	Fehler (rot)	Job ist fehlgeschlagen. Fehlermeldung im Detail-Panel sichtbar.
`cancelled`	Abgebrochen (orange)	Job wurde manuell abgebrochen. Bereits verarbeitete Dateien behalten ihren Hash.
Ghost	Ghost (rot)	Spezialfall: Job steht als `running` in der DB, aber der Worker-Prozess ist nicht mehr aktiv. Siehe Ghost-Erkennung.

Status-Übergänge

pending ──→ running ──→ success
              │    │
              │    └──→ error
              │    │
              │    └──→ cancelled (manuell)
              │
              └──→ cancelled (aus Warteschlange entfernt)

error ──→ (Auto-Resume) ──→ pending (neuer Job mit resumed_from_job)

Alle End-Status (success/error/cancelled) ──→ (manuell löschen)

Steuerung: Pause, Abbruch, Löschen

Die verfügbaren Aktionen hängen vom aktuellen Status ab:

Status	Verfügbare Aktionen	Beschreibung
`running`	⏸ Pause ✖ Abbrechen	Pause: Unterbricht die Pipeline nach dem aktuellen Batch. Der Job bleibt als `running` in der DB, wird aber als »Pausiert« angezeigt. Abbrechen: Stoppt den Job endgültig. Bestätigung erforderlich.
`running` (pausiert)	▶ Fortsetzen ✖ Abbrechen	Fortsetzen: Hebt die Pause auf — der Worker setzt die Verarbeitung fort.
`pending`	✖ Abbrechen	Entfernt den Job aus der Warteschlange.
`success / error / cancelled`	🗑 Löschen	Löscht den Job-Eintrag und seine Datei-Protokolle aus der Datenbank. Bestätigung erforderlich.

Tipp: Die Steuerung erfolgt über die Datenbank-Spalte requested_action — das macht sie prozessunabhängig. Wenn der Worker-Prozess neustartet, erkennt er die angeforderte Aktion und führt sie aus.

Pipeline-Phasen

Jeder Job durchläuft eine mehrstufige Pipeline. Die aktuelle Phase ist im Detail-Panel und im Fortschrittsbalken sichtbar.

#	Phase	Beschreibung
1	Scanning	Dateien auflisten und File-Hashes berechnen. Bei Parallel-Scan (IMAP/Exchange) läuft der Download im Hintergrund weiter während Phase 2+ bereits beginnt.
2	Diff-Berechnung	Vergleicht die neuen Hashes mit den gespeicherten. Bestimmt welche Dateien neu, geändert oder gelöscht sind. Bei Voll-Indexierung: alle Dateien.
3	Loading	Dateien laden und in Text konvertieren. Nutzt den passenden Loader: PDF, DOCX, XLSX, Markdown, Plaintext, oder DDU (Docling) falls aktiviert.
4	VLM (optional)	Bilder durch das Vision Language Model beschreiben lassen. Nur wenn VLM für die Datenquelle aktiviert ist.
5	Chunking	Text in Chunks zerlegen gemäß der konfigurierten Chunk-Strategie. Auto-Detection erkennt den Dokumenttyp automatisch.
6	Embedding	Chunks vektorisieren (Embedding-Modell) und in Qdrant speichern. Verarbeitung in Batches (konfigurierbar, Standard: 100).
7	Finalisierung	Statistiken schreiben, Caches aktualisieren, Job-Status auf `success` oder `error` setzen.

Tipp — Parallel-Scan: E-Mail-Konnektoren (IMAP, Exchange) nutzen Parallel-Scan: Während Mails heruntergeladen werden, beginnt die Ingestion bereits mit den fertigen Dateien. In der UI sind dann zwei Fortschrittsbalken sichtbar: orange (Download) und blau (Verarbeitung).

Detail-Panel & Statistiken

Klick auf den Expand-Button einer Zeile öffnet das Detail-Panel mit ausführlichen Statistiken zum Job.

Ergebnis-Statistik

Wert	Beschreibung
Dateien gesamt	Gesamtzahl der Dateien im Scan.
Verarbeitet	Erfolgreich geladene und gechunkte Dateien.
Übersprungen	Übersprungen (Hash unverändert bei inkrementeller Indexierung).
Gelöscht	Dateien, die nicht mehr existieren — deren Chunks wurden entfernt.
Chunks erzeugt	Gesamtzahl der neu erzeugten Text-Chunks.
Fehler	Dateien, bei denen ein Fehler aufgetreten ist (Details im Datei-Protokoll).

Feature-Details (bedingt)

Werden nur angezeigt, wenn die jeweilige Funktion aktiv war:

Wert	Beschreibung
DDU Dateien	Dateien, die über Docling Document Understanding verarbeitet wurden.
DDU Fallback	Dateien, bei denen DDU fehlschlug und der Standard-Loader als Fallback genutzt wurde.
VLM Chunks	Durch das Vision Language Model erzeugte Bild-Beschreibungen.
Graph Entitäten / Relationen	Im Wissensgraph extrahierte Entitäten und Beziehungen.
Vektoren (DS)	Anzahl der Vektoren für diese Datenquelle in Qdrant.
Vektoren (gesamt)	Gesamtzahl aller Vektoren in der Qdrant-Collection.

Datei-Protokoll

Im Detail-Panel eines abgeschlossenen Jobs kann das Datei-Protokoll geladen werden. Es zeigt für jede verarbeitete Datei den Status, Parser, Chunks und eventuelle Fehler.

Filter

Filter	Beschreibung
Alle	Alle Dateien.
Erfolg	Erfolgreich verarbeitete Dateien.
Fehler	Dateien mit Fehlern (mit Fehlermeldung und Phase).
Übersprungen	Dateien, die übersprungen wurden (z.B. nicht unterstütztes Format).
Suchfeld	Freitext-Suche im Dateinamen (mit Debouncing).

Spalten

Spalte	Beschreibung	Sortierbar
Datei	Dateiname (vollständiger Pfad im Tooltip).	Ja
Größe	Dateigröße (KB/MB).	Ja
Parser	Verwendeter Parser (pdf, docx, plain, ddu, ...). Markierung »(FB)« bei Fallback.	Ja
Chunks	Anzahl erzeugter Chunks.	Ja
Strategie	Erkannte Chunk-Strategie (code, markdown, narrative).	Nein
Dauer	Verarbeitungszeit (ms oder s).	Ja
Status	success (grün), error (rot), skipped (grau).	Ja

Bei Dateien mit Status error wird eine zusätzliche Zeile mit der Fehlermeldung und der betroffenen Phase angezeigt (z.B. [loading], [vlm], [chunking], [embedding]).

Tipp: Das Datei-Protokoll wird lazy-loaded — es wird erst beim Öffnen vom Server geholt, nicht bei jedem Tabellen-Refresh. Die Info-Leiste zeigt die Gesamt-Chunk-Anzahl und die durchschnittliche Verarbeitungsdauer pro Datei.

Resume-Ketten & Auto-Recovery

Wenn ein Job durch einen Crash oder Service-Neustart unterbrochen wird, erstellt der Worker beim Neustart automatisch einen Resume-Job. Dieser setzt die Verarbeitung dort fort, wo der vorherige Job aufgehört hat (inkrementell über File-Hashes).

Wie es funktioniert

Job #42 läuft, Worker stürzt ab → Status wird auf error gesetzt
Worker startet neu, erkennt den »stale« Job
Neuer Job #43 wird mit resumed_from_job = 42 eingereiht
Job #43 verarbeitet nur noch die fehlenden Dateien (Hash-basiert)

Darstellung in der UI

Status-Badge: Zeigt »2× Restart« neben dem Status (als kleine Badge)
Dauer: Gesamtdauer aller Jobs der Kette im Tooltip (z.B. »45m 30s (ges.)«)
Detail-Panel: Zeigt eine Verlaufs-Tabelle mit allen Jobs der Kette: ID, Status, Zeitpunkte, Dauer, Fehler

Tipp: Resume-Ketten sind kein Grund zur Sorge — sie zeigen, dass das System sich selbst heilt. Ein einzelner Restart ist bei langen Indexierungen (mehrere Stunden) normal, z.B. nach einem geplanten Service-Neustart.

Ghost-Erkennung

Ein Ghost-Job ist ein Job, der in der Datenbank als running steht, aber dessen Worker-Prozess nicht mehr aktiv ist. Das kann passieren, wenn der Worker-Service abgestürzt ist, ohne den Job-Status zu aktualisieren.

Erkennung

Ein Job gilt als Ghost, wenn:

Status = running in der DB
Letzter Heartbeat älter als 300 Sekunden (5 Minuten), ODER
Kein Heartbeat vorhanden UND started_at älter als 60 Sekunden

Heartbeat-System

Der Worker schreibt alle 30 Sekunden einen Zeitstempel in stats_json.heartbeat. Bleibt dieser Zeitstempel aus, erkennt die UI den Job als Ghost.

Was tun bei Ghost-Jobs?

Prüfen ob der Worker-Service läuft: systemctl status kiara-worker
Falls gestoppt: Neustart mit systemctl start kiara-worker
Der Worker erkennt den Ghost beim Start automatisch und startet einen Resume-Job
Falls kein Auto-Resume: Job manuell abbrechen und neu starten

Historie bereinigen

Der Button »Historie bereinigen« in der Filter-Leiste löscht abgeschlossene Jobs, die älter als eine konfigurierbare Anzahl von Tagen sind.

Feld	Standard	Beschreibung
`Tage`	`30`	Jobs mit `finished_at` älter als N Tage werden gelöscht. Betrifft nur End-Status (`success`, `error`, `cancelled`). Laufende und ausstehende Jobs sind nicht betroffen.

Tipp: Regelmäßiges Bereinigen hält die Job-Tabelle übersichtlich. Die Datei-Protokolle (File-Logs) werden zusammen mit dem Job gelöscht — bei vielen Jobs mit vielen Dateien kann das die Datenbankgröße merklich reduzieren.

Worker-Service

Der Worker läuft als eigenständiger systemd-Service (kiara-worker.service) und ist für die Abarbeitung der Job-Queue verantwortlich.

Eigenschaft	Wert	Beschreibung
Service	`kiara-worker.service`	systemd-Unit, gesteuert über `systemctl`.
Poll-Intervall	2 Sekunden	Wie oft die Queue auf neue Jobs geprüft wird.
Concurrency	1 (sequentiell)	Nur ein Job gleichzeitig — verhindert GPU-Konkurrenz beim Embedding.
Heartbeat	alle 30 Sekunden	Schreibt Zeitstempel in `stats_json` für Ghost-Erkennung.
Stale-Recovery	Beim Start	Erkennt Ghost-Jobs und startet automatische Resume-Jobs.

Achtung: Vor einem Neustart von kiara-worker immer prüfen, ob ein Job läuft! Ein harter Restart während einer Indexierung führt zu einem Ghost-Job, der beim nächsten Start zwar automatisch fortgesetzt wird, aber unnötige Wartezeit verursacht.

Konfiguration & Konstanten

Konstante	Wert	Beschreibung
`INGESTION_WORKER_POLL_INTERVAL`	2s	Sekunden zwischen Queue-Checks des Workers.
`INGESTION_HEARTBEAT_TIMEOUT`	300s	Maximales Alter des Heartbeats bevor ein Job als Ghost gilt.
`INGESTION_STARTUP_GRACE`	60s	Karenzzeit für frisch gestartete Jobs ohne Heartbeat.
`INGESTION_MAX_CONSECUTIVE_ERRORS`	10	Circuit-Breaker: Pipeline bricht nach 10 aufeinanderfolgenden Fehlern ab.
`HASH_CHECKPOINT_INTERVAL`	100	Alle 100 Dateien werden die Hashes persistiert (Crash-Schutz).
`BACKEND_WAIT_INTERVAL_SECS`	5s	Wartezeit vor Retry bei Backend-Fehlern (Ollama, DDU).

Tipp: Diese Werte sind in kiara/shared/constants.py definiert und können für Spezialfälle angepasst werden. Der Circuit-Breaker (10 Fehler) ist bewusst konservativ — er verhindert, dass ein defektes DDU-Backend stundenlang Timeouts produziert.

API-Endpunkte

Die vollständige API-Referenz für Jobs wird dynamisch aus der Admin-Registry generiert und ist im API-Katalog verfügbar:

Jobs-API — Jobs auflisten, starten, pausieren, abbrechen, löschen, Historie bereinigen, Datei-Protokolle

Troubleshooting

Problem	Mögliche Ursache	Lösung
Job bleibt auf »Ausstehend«	Worker-Service läuft nicht, oder ein anderer Job blockiert die Queue.	`systemctl status kiara-worker` prüfen. Falls ein anderer Job hängt: diesen abbrechen oder den Worker neustarten.
Job als »Ghost« markiert	Worker-Prozess wurde beendet während ein Job lief.	Worker neustarten: `systemctl restart kiara-worker`. Der Worker erstellt automatisch einen Resume-Job.
Circuit-Breaker (10 Fehler in Folge)	Systematisches Problem: DDU nicht erreichbar, Embedding-Backend down, Berechtigungsfehler.	Datei-Protokoll prüfen: Welche Phase? Welche Fehlermeldung? DDU: `systemctl status docling-proxy` auf 10.0.12.16. Ollama: `curl http://10.0.12.16:11434/api/tags`.
Fortschritt zählt nicht hoch	Job ist in der Hashing-Phase (Scan) — Progress wird erst nach dem Scan aktualisiert.	Abwarten. Bei großen Datenquellen (>10.000 Dateien) kann die Scan-Phase mehrere Minuten dauern, ohne dass der Fortschrittsbalken sich bewegt.
Voll-Indexierung dauert sehr lange	Alle Dateien werden neu verarbeitet — bei DDU ca. 5-30s pro Datei.	Inkrementelle Indexierung bevorzugen. Voll-Indexierung nur nach Änderung der Chunk-Strategie oder DDU-Einstellung nötig.
0 Chunks nach erfolgreichem Job	Alle Dateien übersprungen (Hashes unverändert) oder keine unterstützten Dateitypen.	Datei-Protokoll prüfen. Falls alle `skipped`: Dateien haben sich nicht geändert — das ist bei inkrementeller Indexierung normal. Falls keine Dateien: Dateityp-Filter der Datenquelle prüfen.
Pause reagiert nicht sofort	Der Worker prüft `requested_action` nur an definierten Kontrollpunkten (zwischen Batches).	Abwarten — die Pause wird spätestens nach dem aktuellen Batch wirksam (wenige Sekunden).
»Bereits ein aktiver Job«	Für diese Datenquelle läuft oder wartet bereits ein Job.	Pro Datenquelle kann nur ein Job gleichzeitig aktiv sein. Den bestehenden Job abwarten oder abbrechen.