Anleitung für „AI Rating & Tagging (für Darktable) v3.1“

Diese Anleitung erklärt die Installation, Konfiguration und Nutzung des Lua-Scripts „AI Rating & Tagging (für darktable) v3.1“. Das Script integriert sich in darktable und ermöglicht die KI-gestützte Bewertung und Tagging von Bildern mithilfe einer lokalen LLM (z.B LMStudio-API). Es ist für persönliche, nicht-kommerzielle Nutzung gedacht.

1. Einführung

Das Script analysiert Bilder mit einer lokalen KI (z. B. über LMStudio), generiert Bewertungen (Ratings) und Tags (Tagging) und schreibt diese in darktable sowie optionale XMP-Sidecar-Dateien. Es verwendet eine zentrale JSON-Konfigurationsdatei für Einstellungen wie API-Parameter, Bildverarbeitung und Prompts.

Wichtige Hinweise:

Das Script erfordert eine funktionierende lokale LMStudio-Installation mit einem kompatiblen LLM (z. B. vision-fähige Modelle wie GPT-4V-ähnliche).
Darktable Version 9.0.0 oder höher kompatibel.
Teste das Script zunächst mit wenigen Bildern, um die Konfiguration zu validieren.

2. Voraussetzungen

Bevor du das Script installierst, stelle sicher, dass folgende Komponenten vorhanden sind:

darktable: Version 9.0.0 oder neuer (kostenlos erhältlich unter darktable.org).
Lua-Unterstützung: darktable enthält Lua standardmäßig. Stelle sicher, dass Lua-Module wie json, socket.http und ltn12 verfügbar sind (meist vorinstalliert).
LMStudio: Eine lokale Installation von LMStudio (kostenlos unter lmstudio.ai). Du benötigst ein vision-fähiges Modell (z. B. ein Modell, das Bilder verarbeiten kann, wie LLaVA oder ähnliche).
Lokaler LLM-Server: Starte LMStudio und lade ein kompatibles Modell. Der Server muss auf einem lokalen Port (z. B. http://localhost:1234) laufen und die OpenAI-kompatible API unterstützen.
Betriebssystem: Linux, Windows oder macOS (getestet auf Linux).
Hardware: Ausreichend RAM und GPU für das LLM (empfohlen: mindestens 16 GB RAM, GPU mit 8 GB VRAM).

3. Installation

Script herunterladen:
- Speichere das Lua-Script als ai_rating_tagging.lua in deinem darktable Lua-Script-Verzeichnis. Standardmäßig ist das:
  - Linux: ~/.config/darktable/lua/
  - Windows: %APPDATA%\darktable\lua\
  - macOS: ~/Library/Application Support/darktable/lua/
- Erstelle das Verzeichnis, falls es nicht existiert.
Eigene Konfigurationsdatei erstellen (Optional):
- Erstelle eine Datei namens ai_config.json im selben Verzeichnis wie das Script.
- Verwende die folgende Beispiel-Konfiguration als Vorlage (kopiere und passe sie an):
  jsonCopy{„api_settings“:{„lmstudio_api_url“:“http://localhost:1234/v1/chat/completions“,“model_tag“:“local-model“,“max_tokens“:800,“temperature“:0.2,“retry_attempts“:3,“retry_delay“:2},“image_settings“:{„max_width“:800,“max_height“:600,“jpeg_quality“:85},“rating_scale“:[{„score“:0,“rating“:0},{„score“:20,“rating“:1},{„score“:40,“rating“:2},{„score“:60,“rating“:3},{„score“:80,“rating“:4},{„score“:100,“rating“:5}],“system_prompt“:“Du bist ein KI-Assistent für Bildbewertung. Analysiere das Bild und gib eine Bewertung von 0-100 sowie relevante Tags.“,“user_prompt“:“Bewerte dieses Bild auf einer Skala von 0-100 basierend auf Komposition, Belichtung und Ästhetik. Gib auch 3-5 relevante Tags in einer kommagetrennten Liste nach ‚### KEYWORDS:‘ an.“}
  - Erklärung der Felder:
    - api_settings: URL und Parameter für die LMStudio-API.
    - image_settings: Maximale Größe und Qualität für Bild-Exporte (zur Reduzierung der Datenmenge).
    - rating_scale: Mapping von KI-Scores zu darktable-Sternen (0-5 Sterne).
    - system_prompt und user_prompt: Anweisungen für die KI (passe sie an deine Bedürfnisse an).
Script aktivieren:
- Starte darktable neu.
- Das Script sollte automatisch laden. Überprüfe die Konsole auf Fehlermeldungen (z. B. „Script erfolgreich geladen – Version 3.1“).
- Im Lighttable-Modus sollte rechts ein neuer Panel „AI Rating & Tagging v3.1“ erscheinen.

4. Konfiguration

ai_config.json anpassen: Bearbeite die Datei mit einem Texteditor. Ändere die Prompts, um die KI-Ausgaben zu optimieren (z. B. für spezifische Genres wie Porträts oder Landschaften).
Rating-Skala: Passe die rating_scale an, um die Sternen-Bewertungen zu ändern (z. B. strengere Kriterien).
API-Tests: Stelle sicher, dass LMStudio läuft und die URL korrekt ist. Das Script prüft die Erreichbarkeit automatisch.

5. Nutzung

Bilder auswählen:
- Öffne darktable im Lighttable-Modus.
- Wähle ein oder mehrere Bilder aus (z. B. mit Strg+Klick).
Einstellungen anpassen:
- Im Panel „AI Rating & Tagging v3.1“ findest du Checkboxen:
  - Bewertung überschreiben: Aktiviert/deaktiviert das Schreiben der KI-Bewertung (Sterne) in darktable.
  - Beschreibung überschreiben: Aktiviert/deaktiviert das Schreiben der KI-Beschreibung.
  - Tagging überschreiben: Aktiviert/deaktiviert das Hinzufügen von KI-Tags.
  - XMP Rating überschreiben: Erlaubt das Überschreiben vorhandener .rate.xmp-Dateien.
  - Fortschritt auf Bildschirm anzeigen: Zeigt detaillierte Ausgaben direkt in darktable an.
- Diese Einstellungen werden gespeichert und beim nächsten Start wiederhergestellt.
KI-Bewertung starten:
- Klicke auf „AI-Bewertung“.
- Das Script exportiert Bilder (falls nötig), sendet sie an die KI und wendet die Ergebnisse an.
- Fortschritt wird in der Konsole und optional auf dem Bildschirm angezeigt.
- Verwende „Stop“, um den Prozess abzubrechen.
Ergebnisse überprüfen:
- Bewertungen (Sterne) und Tags erscheinen in den Bild-Metadaten.
- Beschreibungen werden in das Beschreibungsfeld geschrieben.
- XMP-Dateien werden im Bildverzeichnis erstellt (z. B. bild.jpg.rate.xmp).
Fehlerbehebung:
- API nicht erreichbar: Überprüfe, ob LMStudio läuft und die URL in ai_config.json korrekt ist.
- Ungültige Antwort: Passe die Prompts an, um sicherzustellen, dass die KI das erwartete Format liefert (z. B. „### KEYWORDS: tag1, tag2“).
- Script lädt nicht: Stelle sicher, dass die Datei im richtigen Verzeichnis liegt und darktable neu gestartet wurde.
- Speicherfehler: Reduziere max_width/max_height in der Konfiguration für große Bilder.
- Debug-Ausgaben: Aktiviere VERBOSE_DEBUG im Script-Code für detaillierte Logs.

6. Lizenz

Das Script ist unter einer benutzerdefinierten Lizenz veröffentlicht, die kostenlose persönliche Nutzung erlaubt, aber kommerzielle Verwendung verbietet. Der vollständige Lizenztext ist im Script-Code enthalten. Für kommerzielle Anfragen kontaktiere den Autor.

7. Support und Updates

Dokumentation: Besuche www.net-fx.de für detaillierte Hilfe und Beispiele.
Fehler melden: Kontaktiere den Autor (Christoph Fischer) über die Website.
Updates: Überprüfe regelmäßig auf neue Versionen. Änderungen werden in den Versionshinweisen dokumentiert.