Zum Hauptinhalt springen

Plugins

Libre WebUI verwendet Plugins, um neben lokalem Ollama externe KI-Anbieter und Modellfähigkeiten anzubinden.

Plugin-Typen​

TypZweck
Chat/VervollständigungText- und Chatmodelle aus Anbieter-APIs
EinbettungenVektoreinbettungen für Dokumentensuche und Speicher
BilderzeugungBildmodelle und ComfyUI-ähnliche Backends
Text zu SpracheAnbieter für Sprachsynthese
Sprache zu TextTranskriptionsanbieter
AudioerzeugungAnbieter für Klang- und Audioerzeugung
VideoerzeugungAnbieter für asynchrone Videoerzeugung

Plugins können statische Modellkarten bereitstellen und, sofern unterstützt, verfügbare Modelle aus Anbieter-APIs aktualisieren.

Gebündelte Anbieterfamilien​

Libre WebUI enthält Definitionen für verbreitete Dienste:

  • OpenAI und OpenAI-kompatible APIs
  • Anthropic
  • Google Gemini
  • Groq
  • Kimi Code von Moonshot AI
  • Mistral
  • OpenRouter
  • Hugging Face
  • GitHub Models
  • MLX LM für lokale Inferenz auf Apple Silicon
  • ComfyUI
  • ElevenLabs

Anbieterkataloge ändern sich häufig. Unterstützt ein Plugin Live-Ermittlung, gilt die Oberfläche als aktuelle Quelle.

Besitz und Autorisierung​

Plugin-Definitionen sind gemeinsame Instanzkonfiguration. Alle /api/plugins-Routen erfordern Authentifizierung und nur Administratoren dürfen Definitionen hochladen, installieren, aktualisieren oder löschen. Die Aktivierung ist kontospezifisch: Jeder authentifizierte Benutzer kann ein gemeinsames Plugin nur für das eigene Konto aktivieren oder deaktivieren. Der Zustand liegt in SQLite und überlebt Backendneustarts, ohne andere Konten zu beeinflussen.

Beim Upgrade wird die alte globale Aktivierungsliste .status.json einmal in vorhandene Konten kopiert, aber nur für Definitionen, die exakt den kompilierten Vertrauensankern entsprechen. Alte benutzerdefinierte oder überschattende Definitionen bleiben unter Quarantäne und inaktiv. Später erstellte Konten beginnen ohne aktive Plugins.

Gebündelte Definitionen sind nur vertrauenswürdig, wenn ihr normalisierter Inhalt einem im Backend kompilierten Hash entspricht. Beschreibbare Definitionen werden in SQLite nach normalisiertem Quellpfad und vollständigem Hash genehmigt. Installation, Aktualisierung oder Reimport durch einen Administrator zeichnet dies auf; direkte Dateiänderungen entwerten die Genehmigung. Genehmigung und Updates löschen die Aktivierung aller Konten vor dem Ersatz, sodass jeder Benutzer die geprüfte Definition erneut aktivieren muss. Vor dem Upgrade vorhandene benutzerdefinierte Definitionen müssen reimportiert werden, bevor sie erscheinen, Modelle ermitteln, Zugangsdaten akzeptieren oder Fähigkeiten ausführen.

Pluginvariablen sind nach Zweck getrennt. Nur Administratoren speichern erkannte Verbindungsvariablen:

endpoint, base_url, api_path, models_endpoint, api_url, image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint, voice_clone_endpoint, api_mode, model und model_id. Auch eine von der Fähigkeit deklarierte config.endpoint_variable, config.models_endpoint_variable oder config.voice_clone_endpoint_variable ist Routing, selbst bei anderem Namen.

Nichtadministratoren können Generierungssteuerungen wie Temperatur oder Streamingpräferenzen speichern. Alte Routingzeilen dieser Konten werden ignoriert, nicht als konfigurierte Werte ausgegeben und bei vollständiger Variablenrücksetzung entfernt. Dadurch belebt eine spätere Rollenänderung keine inaktive Route.

Zugangsdaten​

Zugangsdaten können aus Umgebungsvariablen oder Benutzereinstellungen stammen.

Beispiele:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=sk-or-...
KIMI_API_KEY=...
GITHUB_API_KEY=github_pat_...
ELEVENLABS_API_KEY=...

In gemeinsamen Bereitstellungen sind benutzerspezifische Zugangsdaten meist besser, weil jeder Abrechnung und Limits kontrolliert. Umgebungsschlüssel eignen sich für Einzelbenutzer, Demos oder verwaltete Bereitstellungen.

Ein Umgebungsschlüssel ist nur Fallback, solange die Anfrage Routing und Authentifizierung einer nicht überschatteten gebündelten Definition nutzt. Eine importierte Definition, eine beschreibbare Definition mit gebündelter ID oder ein vom Administrator gespeichertes Routing erfordert Zugangsdaten desselben Kontos. Libre WebUI vergleicht Root-Endpunkt, Authentifizierungsfelder, Fähigkeitsendpunkte und Selektoren sowie Routingdefinitionen und Standards, bevor Fallback erlaubt wird. Der kompilierte Manifest-Hash bleibt auch bei gemeinsamem Legacy-/Bundlepfad maßgeblich; ein überschriebenes Paketmanifest schafft kein Vertrauen.

Die Regel gilt für Ermittlung, Chat, Work, Verfügbarkeitsprüfungen und Fähigkeitskataloge. Sie verhindert, dass ein benutzerdefinierter Endpunkt oder altes Manifest ein Betreibergeheimnis erhält.

Benutzerschlüssel werden bei der Speicherung an effektive Quelle, vollständigen Hash, Authentifizierungsvertrag, Fähigkeitsendpunkte und -selektoren sowie Routingwerte gebunden. Änderungen machen alte Zugangsdaten unzugänglich, bis der Benutzer das Ziel prüft und neu speichert. Alte ungebundene Daten werden nur auf einer exakt verankerten gebündelten Route akzeptiert; die erste erfolgreiche Nutzung schreibt die Bindung vor Rückgabe des entschlüsselten Schlüssels.

OpenAI-kompatible Anbieter​

Viele Anbieter bieten OpenAI-kompatible APIs. Ein Plugin kann definieren:

  • vollständige API-Endpunkt-URL;
  • Umgebungsvariable des API-Schlüssels;
  • Chat-Endpunktverhalten;
  • Einbettungsunterstützung;
  • Modellermittlung;
  • optionale Fallback-Modellkarte.

Ohne Live-Ermittlung verwendet Libre WebUI die konfigurierte Karte. Importiertes Plugin-JSON konfiguriert Anbieter, die bereits ein unterstütztes Drahtformat sprechen: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages oder Gemini. JSON übersetzt kein beliebiges proprietäres Protokoll; abweichende Anfrage-, Streaming-, Werkzeug- oder Antwortformen benötigen einen kleinen Backendadapter.

OpenAI-Bilderzeugung​

Der gebündelte OpenAI-Anbieter stellt die Image API unter https://api.openai.com/v1/images/generations bereit. Aktuell ist gpt-image-2. Der Katalog behält die veralteten IDs gpt-image-1.5, gpt-image-1 und gpt-image-1-mini für bestehende Bereitstellungen; neue Konfigurationen sollen gpt-image-2 wählen.

Die Bilderzeugung nutzt dieselben effektiven OpenAI-Zugangsdaten wie Chat: den gespeicherten Benutzerschlüssel oder den Umgebungsschlüssel der vertrauenswürdigen Definition. Ein getrenntes optionales image_endpoint verhindert, dass ein eigener Chat-Endpunkt Bildanfragen erhält. Leer bedeutet die gebündelte Image API.

Bildauswahlen sind anbieterspezifisch. Bei derselben Modell-ID sendet Libre WebUI nur an den im Bildbereich ausgewählten Anbieter. GPT Image liefert Base64-Daten, die Libre in ein Bild umwandelt und in der Galerie des Benutzers speichert. Routen erfordern Authentifizierung; direkte Anfragen müssen pluginId und model enthalten. n darf eine JSON-Ganzzahl von 1 bis 10 sein; Zahlenzeichenfolgen und Brüche werden vor dem Anbieter abgewiesen.

Chat-Completions- und Responses-API-Modi​

OpenAI-kompatible Vervollständigungsplugins verwenden chat_completions- oder responses-Semantik. Das gebündelte OpenAI-Plugin bietet die Wahl unter Einstellungen → Plugins.

Verbindungseinstellungen werden so aufgelöst:

  1. vollständige endpoint-Überschreibung;
  2. base_url plus optionales api_path;
  3. altes endpoint des Plugins.

Ein Wert, der exakt dem Manifestendpunkt entspricht, gilt als Vorgabe statt Überschreibung, sodass alte gespeicherte Standards eine neue Basis-URL nicht verdecken. Ein wirklich eigener vollständiger Endpunkt bleibt vorrangig.

Standardpfad ist /chat/completions im Chat-Completions-Modus und /responses im Responses-Modus. base_url soll die API-Wurzel wie https://api.example.com/v1 sein; verwende api_path für einen anderen relativen Pfad. Ein vollständiger Endpunkt enthält den Operationspfad und hat Vorrang. Bekannte Suffixe /chat/completions, /completions oder /responses bestimmen die Semantik; eigene Pfade behalten api_mode.

Importiertes JSON kann dieselben Vorgaben liefern:

{
  "endpoint": "https://api.example.com/v1/chat/completions",
  "api_mode": "responses",
  "base_url": "https://api.example.com/v1",
  "api_path": "/responses"
}

Responses-Anfragen verwenden input, max_output_tokens, abgeflachte Funktionswerkzeuge, store: false und fordern verschlüsselten Denkinhalt für zustandslose Fortsetzung an. Ausgabe wird in Chat-/Work-Ereignisse normalisiert. Wiedergabezustand bleibt nur, wenn das vollständige geordnete Item-Array höchstens 64 Items und 90 KB hat; Items bleiben exakt und Felder werden nie abgeschnitten. Wiedergabefähige Items brauchen eindeutige nicht leere IDs und Typen; Nachrichten-, Denk- und Funktionsstrukturen werden vor Werkzeugausgabe geprüft. Zu großer Chat-Zustand fällt auf sichtbaren normalisierten Verlauf zurück. Chat verwirft rohe Funktionsaufruf-Items, weil passende Ergebnisse nicht persistiert werden. Work-Antworten mit Werkzeugen ohne exakten begrenzten Zustand werden vor Nebenwirkungen abgewiesen.

SQLite-Chat speichert Anbieterzustand verschlüsselt mit der Nachricht; Work legt werkzeugbezogenen Zustand in versteckten Kontextzeilen ab. Ein gehashter Bereich bindet Wiedergabe an Anbieter, Modell, Responses-Modus, finalen Endpunkt und eine Einwegfingerabdruck der Zugangsdaten. Bei Änderung, einschließlich Schlüsselrotation, fällt Libre auf Nachrichtenverlauf zurück, statt anbieterspezifische Items über Authentifizierungsgrenzen zu senden. Eine aktive Work-Ausführung prüft Routing und Zugangsdaten vor jeder Runde; Änderungen stoppen vor der nächsten Anfrage.

Werkzeugzustand muss sowohl in die Wiedergabegrenze als auch die vollständige persistente 100-KB-Metadatenhülle passen, bevor Work Nebenwirkungen ausführt. Bei unterbrochenem Stapel wird jedes fehlende Ergebnis mit exakter Aufruf-ID und Warnung über unbekannten Ausgang wiederhergestellt, damit der Anbieter den Arbeitsbereich prüft statt blind zu wiederholen. Ein unvollständiges Responses-Ergebnis gilt nicht als erfolgreich; incomplete_details.reason bleibt erhalten und wird angezeigt.

Die Modellermittlung leitet /models aus dem Operationspfad ab. Beispielsweise ermittelt https://api.example.com/v1/responses von https://api.example.com/v1/models. Anbieter ohne kompatible Liste nutzen ein manuelles model_map. Ermittlung ist auf Variablen und Zugangsdaten des aktuellen Benutzers begrenzt; Ergebnisse werden pro Benutzer statt im gemeinsamen Manifest gespeichert. Sie läuft nach Aktivierung, Aktualisierung, Schlüssel- oder Verbindungsänderung und Rücksetzung; unrelated Generierungsvariablen lösen kein Netz aus.

Ermittlung läuft auch automatisch, wenn ein aktiver Vervollständigungsanbieter keinen oder einen älteren Katalog als PLUGIN_MODEL_DISCOVERY_TTL_MS hat. Anbieterspezifischer Backoff verhindert ständige Abfragen und ein Zeitlimit Verzögerungen; später fertige Ergebnisse erscheinen in der nächsten Anfrage. Die finale URL wird vor dem Lesen der Zugangsdaten und dem Erstellen von Authorization geprüft, auch aus importierten Manifesten. Ermittlung und Fähigkeitsanfragen folgen keinen HTTP-Weiterleitungen. Konfiguriere die finalen Chat-, Work-, Modelllisten-, Bild-, Einbettungs-, Transkriptions-, Sprach-, Klon-, Audio- oder Videoendpunkte direkt.

Anbieterendpunkte dürfen HTTP oder HTTPS nutzen. HTTP sendet Schlüssel, Prompts, Ergebnisse und Inhalte ohne Transportverschlüsselung; nutze es nur für ein selbst gehostetes Gateway in einem vertrauenswürdigen Netz und bevorzuge HTTPS. Anfragen stammen vom Backend: In Containern verwende eine Dienst-URL wie http://ai-gateway:8080/v1, während localhost den Libre WebUI-Container meint. Fähigkeitsrouten lösen Variablen und Zugangsdaten für das anfragende authentifizierte Konto auf. Libre WebUI hat keinen nicht authentifizierten Einzelbenutzermodus.

Fähigkeitsspezifische Endpunkte​

Chat-Überschreibungen sind von Bild-, Einbettungs-, Transkriptions-, Sprach-, Audio- und Videofähigkeiten getrennt. Mehrfähigkeitsplugins können image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint oder eine Variable aus config.endpoint_variable bereitstellen. Klonrouten können config.voice_clone_endpoint_variable benennen. Leere Felder verwenden den deklarierten Fähigkeitsendpunkt; ein allgemeines Chat-endpoint überschreibt Fähigkeiten nie.

Das gebündelte GitHub Models-Plugin erbt models.github.ai/inference/chat/completions, wenn die optionale Überschreibung leer ist. Hugging Face verwendet aufgabenspezifische hf-inference/models/{model}-Routen und Nutzdaten für Einbettungen, Bilder und Sprache statt des Chat-Endpunkts.

Endpunktüberschreibungen​

endpoint ist die vollständige Anfrage-URL mit Operationspfad. Ein kompatibles Chatplugin verwendet etwa https://provider.example/v1/chat/completions, nicht nur https://provider.example. Alte Konfigurationen können api_url nennen; Libre akzeptiert den Alias, aber ein nicht leeres endpoint hat Vorrang.

Absolute HTTP- und HTTPS-URLs sind erlaubt, andere Protokolle nicht. HTTP ist für vertrauenswürdige selbst gehostete Gateways gedacht. Bevorzuge HTTPS außerhalb privater Grenzen. Leer verwendet den Definitionsendpunkt; eine explizit unsichere Überschreibung wird abgewiesen statt still zurückzufallen.

Anbieteranfragen folgen keinen Weiterleitungen. Konfiguriere die validierte finale Operations-URL; ein Redirect wird als Anbieterfehler gemeldet, ohne Zugangsdaten weiterzugeben.

Anfragen stammen vom Libre WebUI-Backend. In einem Container bezeichnet localhost diesen Container, nicht Host oder andere Dienste. Verwende den Dienstnamen oder host.docker.internal, sofern verfügbar.

Modellermittlung​

Einstellungen → Plugins enthält den Bereich Anbieterverbindungen. Suche links, wähle einen Anbieter und prüfe rechts Aktivierung und Katalog. Die Konfiguration bleibt eingeklappt, bis Konfigurieren gewählt wird, damit Endpunkte, Zugangsdaten und erweiterte Steuerungen nicht standardmäßig sichtbar sind.

Bei Chat- und Vervollständigungsanbietern führt Modelle aktualisieren die Ermittlung aus und lädt Plugin- und Chatkatalog neu. Der Katalog ist schreibgeschützt: Zeilen stammen aus ermittelten Benutzer-IDs und Fähigkeitsmodellkarten. Fähigkeitsbezeichnungen zeigen die auflistende Route, nicht den Zustand. Füge manuelle IDs im JSON-model_map hinzu.

Bei Aktivierung versucht Libre WebUI die Ermittlung mit effektivem Endpunkt und Zugangsdaten des Kontos. Eine eigene Administratorroute benötigt Zugangsdaten desselben Kontos; Umgebungsfallback gilt nur für die vertrauenswürdige Manifestroute. Libre WebUI leitet eine Listen-URL ab:

  • Eine URL mit Ende /models wird unverändert verwendet.
  • Bekannte Suffixe /chat/completions, /completions, /responses, /embeddings oder /messages werden durch /models ersetzt.
  • Sonst wird /models angehängt.

Plugins können ein explizites vollständiges models_endpoint bereitstellen. Es hat Vorrang, folgt derselben Richtlinie und keiner Weiterleitung. Speichern oder Rücksetzen von endpoint, api_url, models_endpoint, base_url, api_path oder api_mode löscht und aktualisiert den Katalog des Benutzers.

Alle eigenen Routen werden vor der Zugangsdatenwahl aufgelöst und geprüft. Eine gespeicherte Route fällt nicht auf einen Serverumgebungsschlüssel zurück; speichere einen Benutzerschlüssel. Umgebungsschlüssel sind dem Definitionsendpunkt vorbehalten.

Ermittlung erwartet eine OpenAI-kompatible Antwort mit Modell-IDs im data-Array. Aktivierung wartet auf den Versuch, damit die erste Liste den Katalog enthalten kann. Erfolgreiche Ergebnisse werden pro Benutzer gespeichert, ohne JSON umzuschreiben oder andere Konten zu informieren. Ohne kompatible Liste, Erreichbarkeit oder Antwortform behält normale Aktivierung das frühere Ergebnis. Eine bewusste Verbindungsänderung löscht es vorher und verwendet bei Fehler das model_map.

Speichern oder Rücksetzen des Routings löscht den alten Katalog vor dem nächsten Versuch, damit Modelle eines Ziels nicht nach einem Routenwechsel auswählbar bleiben.

Pluginzustand, Work-Verfügbarkeit, Kataloge und Fähigkeitsrouten nutzen denselben Benutzerkontext und dieselbe Grenze. Auch Bildmodelle, Endpunkte und Schlüssel werden für den Anfragenden aufgelöst.

Exakte Anbieterauswahl in Chat​

Modell-IDs sind nicht global eindeutig. Ollama und mehrere Plugins können example-model anbieten. Chat speichert daher die rohe ID mit optionaler Identität:

  • providerType: "ollama" bezeichnet die Ollama-Route;
  • providerType: "plugin" plus providerId ein exaktes Plugin.

Anbieterqualifizierte URL-kodierte Werte dienen nur kollisionssicheren Auswahlschlüsseln. Anfragen senden die rohe ID. Doppelte Namen bleiben getrennte Optionen und beim Wiederöffnen wird die exakte Auswahl wiederhergestellt.

Explizite Identität schlägt sicher fehl. Ist das Plugin deaktiviert, entfernt oder bietet das Modell nicht mehr an, bleibt die gespeicherte Auswahl als nicht verfügbar sichtbar und wechselt nicht still zu einem gleichnamigen Anbieter. Reaktiviere oder wähle ausdrücklich neu.

Alte Sitzungen können providerType und providerId nicht gesetzt oder null haben. Sie behalten aus Kompatibilität Namensrouting, weil der ursprüngliche Anbieter nicht rekonstruierbar ist. Die Auswahl zeigt „Anbieter nicht aufgezeichnet“ statt zu raten. Eine konkrete Wahl fixiert künftige Anfragen. Personas behalten persona:<id> und neue werden als Ollama-gestützt erfasst.

Anbietereinstellungen und Vererbung​

Öffne Einstellungen → Plugins und Konfigurieren. Bereiche sind standardmäßig geschlossen. Administratoren verwalten gemeinsame Definitionen und Routing; andere Benutzer aktivieren, speichern Schlüssel und ändern Generierungssteuerungen, sehen aber Upload, Installation, Export, Löschung oder Routing nicht.

Für Administratoren erscheinen Verbindungsüberschreibungen zuerst. Sampling und Spezialsteuerungen liegen unter Erweiterte Parameter, ebenfalls geschlossen. Geerbte Werte erscheinen als leere Felder mit Anbieterhinweis. Das Öffnen kopiert Manifestvorgaben nicht ins Konto.

Speichern sendet nur in der aktuellen Sitzung geänderte Felder. Leeren eines nicht sensiblen gespeicherten Werts entfernt die Überschreibung und stellt die Vorgabe her; ein leeres maskiertes sensibles Feld bleibt unverändert. Auf Standard zurücksetzen entfernt alle erlaubten Überschreibungen. Bei Fehler bleiben ungespeicherte Werte sichtbar.

Bei eigenen Endpunkten lässt der Administrator leer, um die gebündelte URL zu erben, oder gibt eine vollständige kompatible URL ein.

Plugins in Work​

Work verwendet aktive completion- und chat-Plugins neben Ollama und Ollama Cloud. Ein pluginbasierter Lauf wird nur akzeptiert, wenn:

  • das Plugin aktiv ist;
  • das Modell im ermittelten Katalog oder konfigurierten Modellplan steht;
  • Zugangsdaten für den aktuellen Administrator verfügbar sind.

Work speichert Anbietertyp und Plugin-ID bei Aufgabe und Ausführung, daher richtet sich die Weiterleitung nach dem exakten Anbieter, nicht dem Namen. Ein gleichnamiges Plugin kann eine bestehende Ollama-Aufgabe nicht umleiten.

Work passt Werkzeugaufrufe an native OpenAI-, Anthropic- und Gemini-Formate an. Das Modell muss Werkzeuge unterstützen, auch wenn der Anbieter normale Chatvervollständigung bietet. Ablehnung oder inkompatible Antwort lässt den Lauf fehlschlagen, ohne Fallback.

Ein Remotelauf kann mehrere Anfragen ausführen. Der Anbieter erhält Work-Systemprompt, Kontext, Werkzeugdefinitionen und angeforderte Ergebnisse, die Quellcode, Verzeichnislisten oder Befehlsausgabe enthalten können. Libre WebUI zeigt eine benutzerspezifische ausblendbare Offenlegung; Betreiber sollen Preis-, Aufbewahrungs- und Trainingsrichtlinien vor sensiblen Projekten prüfen.

Einbettungen​

Einbettungsfähige Plugins erscheinen in Dokumenteinstellungen. Libre WebUI erkennt außerdem wahrscheinliche Ollama-Modelle wie nomic-embed-text, bge, e5, gte und ähnliche Namen.

Wird keines ermittelt, verwendet die Oberfläche nomic-embed-text als lokalen Standardkandidaten.

Hinweise zur Plugin-Entwicklung​

Eine Definition soll die Fähigkeit klar beschreiben und keine nicht angebotenen Funktionen vortäuschen. Halte Modellkarten klein und als Fallback nützlich; bevorzuge Ermittlung bei schnellen zuverlässigen Listen-APIs.

Beim Hinzufügen eines Anbieters:

  1. Plugin-Definition hinzufügen.
  2. Zugangsschlüssel oder Benutzerfelder definieren.
  3. Modellermittlung implementieren, falls eine Liste existiert.
  4. Anfragen für Chat, Einbettungen, Bilder, TTS oder STT abbilden.
  5. Fehlenden/falschen Schlüssel und Anbieterfehler testen.

Verwandte Dokumentation​