Zum Inhalt

OpenAI API verwenden

Hier erfährst du, wie du PhotoPrism mit den GPT‑Modellen von OpenAI verwendest, um hochwertige Bildunterschriften und Labels für deine Bilder zu erzeugen.

Setup

Voraussetzungen

  • Um OpenAI‑Dienste nutzen zu können, benötigst du einen gĂĽltigen API‑Key, der ĂĽber OPENAI_API_KEY oder OPENAI_API_KEY_FILE konfiguriert wird.
  • PhotoPrism muss auĂźerdem Netzwerkzugriff auf api.openai.com haben.

Konfiguration

Füge deiner vision.yml‑Datei die folgenden Caption‑ und/oder Label‑Modelle hinzu:

Models:
  - Type: caption
    Model: gpt-6-luna
    Engine: openai
    Run: auto
    Options:
      Detail: low           # optional: Standard ist low
      MaxOutputTokens: 512  # optional: Token-Limit ändern
    Service:
      Key: ${OPENAI_API_KEY}
  - Type: labels
    Model: gpt-6-luna
    Engine: openai
    Run: auto
    Options:
      MaxOutputTokens: 1024 # optional: Token-Limit ändern
    Service:
      Key: ${OPENAI_API_KEY}

Empfehlungen:

  • Lass den Modellnamen exakt so, wie er von OpenAI veröffentlicht wurde. Der Bezeichner wird so gesendet, wie er geschrieben ist, einschlieĂźlich eines Tags nach einem Doppelpunkt; verwende also gpt-6-luna statt gpt-6-luna:latest. FĂĽr Einträge ohne Modellnamen verwendet PhotoPrism OPENAI_MODEL, falls gesetzt, andernfalls gpt-6-luna. Modellbezeichner sind auĂźerdem case‑sensitiv – PhotoPrism ĂĽbernimmt die Schreibweise direkt aus deiner vision.yml, sodass Werte wie QuantTrio/Qwen3-VL-30B-A3B-Instruct-AWQ von Hugging Face oder einem anderen OpenAI‑kompatiblen Katalog unverändert an die Upstream‑API geschickt werden.
  • OpenAI stellt gpt-5-mini, gpt-5-nano und gpt-5 am 11. Dezember 2026 ein. Falls deine vision.yml noch eines dieser Modelle nennt, zum Beispiel weil photoprism vision save den frĂĽheren Standard hineingeschrieben hat, ändere es in ein aktuelles Modell wie gpt-6-luna oder gpt-6.1-terra. Andernfalls schlagen Anfragen fĂĽr Bildunterschriften und Labels fehl, sobald das Modell eingestellt ist.
  • Service.Key kann entfallen, wenn OPENAI_API_KEY bzw. _FILE bereits in der Umgebung gesetzt ist. Ohne SchlĂĽssel werden keine Anfragen an api.openai.com gesendet. Optional kannst du Service.Org und Service.Project setzen, falls dein Account das aus AbrechnungsgrĂĽnden verlangt.
  • Service.Tier setzt optional den OpenAI service_tier (zum Beispiel flex fĂĽr gĂĽnstigere, langsamere Verarbeitung); ohne Angabe wird OpenAIs Standard (auto) verwendet.
  • PhotoPrism wertet Modelle von unten nach oben aus. Wenn du die OpenAI‑Einträge ans Ende der Liste setzt, werden sie bevorzugt, während andere Modelle als Fallback dienen.

Standardmäßig verwendet PhotoPrism den OpenAI‑Responses‑Endpunkt https://api.openai.com/v1/responses mit einem einzelnen 720 px Thumbnail (detail: low). Um einen anderen OpenAI‑kompatiblen Endpunkt zu verwenden, setze OPENAI_BASE_URL auf dessen Basis-URL einschließlich des Versionspfads, z. B. https://llm.example.com/v1. Sie wird dann für alle OpenAI‑Modelle ohne Service.Uri verwendet. Alternativ setzt du für ein einzelnes Modell ein eigenes Service.Uri. Eine Query in der Basis-URL, etwa ?api-version=... für Azure OpenAI, wird ans Ende der Anfrage-URL verschoben; Zugangsdaten gibst du über OPENAI_API_KEY oder Service.Key an, nicht über die URL. Weicht OPENAI_BASE_URL vom Standard ab, protokolliert PhotoPrism beim Start die verwendete Basis-URL mit maskierten Zugangsdaten, sodass du prüfen kannst, welcher Endpunkt die Anfragen erhält.

Nutzungs Tipps

Run Modes

Um unerwartete Kosten zu vermeiden – insbesondere beim Testen neuer Modelle oder Prompts – setze Run: manual und führe die Modelle manuell aus, z.B. mit photoprism vision run -m caption oder photoprism vision run -m labels. Run: auto führt das Modell automatisch aus, nachdem die Indexierung abgeschlossen ist, um den Import nicht auszubremsen. Gleichzeitig bleiben manuelle und geplante Ausführungen möglich.

Mehr erfahren ›

Existierende Kategorien ersetzen

Wenn du bestehende Kategorien des eingebauten Klassifizierungsmodells entfernen möchtest, führe photoprism vision reset -m labels -s image in einem Terminal aus, bevor du alle Kategorien mit OpenAI neu generierst:

photoprism vision run -m labels

Mehr erfahren ›

Benutzerdefinierte Kategorien erstellen

Um die generierten Kategorien an deine Bedürfnisse anzupassen, können die Defaults für System oder Prompt in der vision.yml überschrieben werden:

  • System: You are a PhotoPrism vision model. Emit JSON that matches the provided schema and keep label names short, singular nouns.
  • Prompt: Analyze the image and return label objects with name, confidence (0-1), and topicality (0-1).

Halte die Prompts kurz und behalte die Erinnerung an das JSON-Schema für Kategorien. Für Bildunterschriften und Kategorien in anderen Sprachen solltest du die Basisanweisungen im Prompt auf Englisch belassen und nur die gewünschte Sprache ergänzen (z.B. "Respond in German"). Das funktioniert sowohl für Captions als auch für Label‑Prompts.

Beispiel:

Models:
  - Type: labels
    Model: gpt-6-luna
    Engine: openai
    Run: auto
    Prompt: >
      Analyze the image and return up to 3 label objects with
      German singular name, confidence (0-1), and topicality (0-1).

Caption Prompt anpassen

Wenn du längere Captions, andere Sprachen oder branchenspezifische Beschreibungen benötigst, kannst du die Defaults für System oder Prompt in der vision.yml überschreiben.

  • System: You are a PhotoPrism vision model. Return concise, user-friendly captions that describe the main subjects accurately.
  • Prompt: Provide exactly one sentence describing the key subject and action in the image. Avoid filler words and technical jargon.

Beispiel:

Models:
  - Type: caption
    Model: gpt-6-luna
    Engine: openai
    Run: auto
    Prompt: >
      Provide one or two German sentences describing the key subject and
      action in the image. Avoid filler words and technical jargon.

Troubleshooting

Konfiguration ĂĽberprĂĽfen

Wenn Probleme auftreten, prüfe zuerst, wie PhotoPrism deine vision.yml‑Konfiguration geladen hat. Das geht mit folgendem Befehl:

docker compose exec photoprism photoprism vision ls

Der Befehl gibt die Einstellungen aller unterstützten und konfigurierten Modelltypen aus. Vergleiche das Ergebnis mit deiner vision.yml‑Datei, um zu bestätigen, dass die Konfiguration korrekt geladen wurde, und um Parsing‑Fehler oder Fehlkonfigurationen zu erkennen.

Test Runs durchfĂĽhren

Die folgenden Terminal‑Befehle führen jeweils einen einzelnen Lauf für den angegebenen Modelltyp aus:

photoprism vision run -m labels --count 1 --force
photoprism vision run -m caption --count 1 --force

Wenn du nicht die erwarteten Ergebnisse erhältst oder Fehler bemerkst, kannst du die Befehle erneut mit aktiviertem Trace‑Log‑Modus ausführen, um Anfrage und Antwort zu untersuchen:

photoprism --log-level=trace vision run -m labels --count 1 --force
photoprism --log-level=trace vision run -m caption --count 1 --force