Jobs

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

Uebersicht & Tabelle

Der Jobs-Tab zeigt alle Indexierungs-Auftraege: 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 zugehoerigen Datenquelle.	Sortierbar.
Embedding	Verwendetes Embedding-Modell (z.B. `nomic-embed-text`, `voyage-ai`).	Sortierbar.
Typ	Inkr. = Inkrementell (nur neue/geaenderte 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	Geschaetzte 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.
Ausloser	Wer den Job ausgeloest hat: manual, cron oder api.	Sortierbar.
Aktionen	Kontextabhaengige 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 laeuft.
`running`	Laufend (gruen)	Job wird gerade verarbeitet. Fortschrittsbalken und Restzeit sichtbar.
`running` + pausiert	Pausiert (orange)	Job ist pausiert. Kann fortgesetzt werden — die Pipeline haelt beim naechsten Kontrollpunkt an.
`success`	Erfolgreich (gruen)	Job ist abgeschlossen. Statistiken und Datei-Protokoll verfuegbar.
`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-Uebergaenge

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 loeschen)

Steuerung: Pause, Abbruch, Loeschen

Die verfuegbaren Aktionen haengen vom aktuellen Status ab:

Status	Verfuegbare 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 endgueltig. Bestaetigung 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`	🗑 Loeschen	Loescht den Job-Eintrag und seine Datei-Protokolle aus der Datenbank. Bestaetigung erforderlich.

Tipp: Die Steuerung erfolgt ueber die Datenbank-Spalte requested_action — das macht sie prozessunabhaengig. Wenn der Worker-Prozess neustartet, erkennt er die angeforderte Aktion und fuehrt sie aus.

Pipeline-Phasen

Jeder Job durchlaeuft 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) laeuft der Download im Hintergrund weiter waehrend Phase 2+ bereits beginnt.
2	Diff-Berechnung	Vergleicht die neuen Hashes mit den gespeicherten. Bestimmt welche Dateien neu, geaendert oder geloescht 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 fuer die Datenquelle aktiviert ist.
5	Chunking	Text in Chunks zerlegen gemaess 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: Waehrend 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 oeffnet das Detail-Panel mit ausfuehrlichen Statistiken zum Job.

Ergebnis-Statistik

Wert	Beschreibung
Dateien gesamt	Gesamtzahl der Dateien im Scan.
Verarbeitet	Erfolgreich geladene und gechunkte Dateien.
Uebersprungen	Uebersprungen (Hash unveraendert bei inkrementeller Indexierung).
Geloescht	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 ueber 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 Entitaeten / Relationen	Im Wissensgraph extrahierte Entitaeten und Beziehungen.
Vektoren (DS)	Anzahl der Vektoren fuer 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 fuer 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).
Uebersprungen	Dateien, die uebersprungen wurden (z.B. nicht unterstuetztes Format).
Suchfeld	Freitext-Suche im Dateinamen (mit Debouncing).

Spalten

Spalte	Beschreibung	Sortierbar
Datei	Dateiname (vollstaendiger Pfad im Tooltip).	Ja
Groesse	Dateigroesse (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 (gruen), error (rot), skipped (grau).	Ja

Bei Dateien mit Status error wird eine zusaetzliche 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 Oeffnen 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 aufgehoert hat (inkrementell ueber File-Hashes).

Wie es funktioniert

Job #42 laeuft, Worker stuerzt 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 abgestuerzt ist, ohne den Job-Status zu aktualisieren.

Erkennung

Ein Job gilt als Ghost, wenn:

Status = running in der DB
Letzter Heartbeat aelter als 300 Sekunden (5 Minuten), ODER
Kein Heartbeat vorhanden UND started_at aelter 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?

Pruefen ob der Worker-Service laeuft: 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 loescht abgeschlossene Jobs, die aelter als eine konfigurierbare Anzahl von Tagen sind.

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

Tipp: Regelmaessiges Bereinigen haelt die Job-Tabelle uebersichtlich. Die Datei-Protokolle (File-Logs) werden zusammen mit dem Job geloescht — bei vielen Jobs mit vielen Dateien kann das die Datenbankgroesse merklich reduzieren.

Worker-Service

Der Worker laeuft als eigenstaendiger systemd-Service (kiara-worker.service) und ist fuer die Abarbeitung der Job-Queue verantwortlich.

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

Achtung: Vor einem Neustart von kiara-worker immer pruefen, ob ein Job laeuft! Ein harter Restart waehrend einer Indexierung fuehrt zu einem Ghost-Job, der beim naechsten Start zwar automatisch fortgesetzt wird, aber unnoetige 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 fuer 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 koennen fuer Spezialfaelle angepasst werden. Der Circuit-Breaker (10 Fehler) ist bewusst konservativ — er verhindert, dass ein defektes DDU-Backend stundenlang Timeouts produziert.

API-Endpunkte

Die vollstaendige API-Referenz fuer Jobs wird dynamisch aus der Admin-Registry generiert und ist im API-Katalog verfuegbar:

Jobs-API — Jobs auflisten, starten, pausieren, abbrechen, loeschen, Historie bereinigen, Datei-Protokolle

Troubleshooting

Problem	Moegliche Ursache	Loesung
Job bleibt auf »Ausstehend«	Worker-Service laeuft nicht, oder ein anderer Job blockiert die Queue.	`systemctl status kiara-worker` pruefen. Falls ein anderer Job haengt: diesen abbrechen oder den Worker neustarten.
Job als »Ghost« markiert	Worker-Prozess wurde beendet waehrend 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 pruefen: 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 zaehlt nicht hoch	Job ist in der Hashing-Phase (Scan) — Progress wird erst nach dem Scan aktualisiert.	Abwarten. Bei grossen 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 Aenderung der Chunk-Strategie oder DDU-Einstellung noetig.
0 Chunks nach erfolgreichem Job	Alle Dateien uebersprungen (Hashes unveraendert) oder keine unterstuetzten Dateitypen.	Datei-Protokoll pruefen. Falls alle `skipped`: Dateien haben sich nicht geaendert — das ist bei inkrementeller Indexierung normal. Falls keine Dateien: Dateityp-Filter der Datenquelle pruefen.
Pause reagiert nicht sofort	Der Worker prueft `requested_action` nur an definierten Kontrollpunkten (zwischen Batches).	Abwarten — die Pause wird spaetestens nach dem aktuellen Batch wirksam (wenige Sekunden).
»Bereits ein aktiver Job«	Fuer diese Datenquelle laeuft oder wartet bereits ein Job.	Pro Datenquelle kann nur ein Job gleichzeitig aktiv sein. Den bestehenden Job abwarten oder abbrechen.