Pluginy

Libre WebUI používá pluginy k připojení externích poskytovatelů AI a funkcí modelů vedle místní Ollama.

Typy pluginů

Typ	Účel
Chat/completion	Textové a chatové modely z API poskytovatelů
Embeddings	Vektorové embeddingy pro dokumenty a paměť
Generování obrázků	Obrazové modely a backendy typu ComfyUI
Text na řeč	Poskytovatelé syntézy hlasu
Řeč na text	Poskytovatelé přepisu
Generování zvuku	Poskytovatelé zvuku
Generování videa	Asynchronní poskytovatelé videa

Pluginy mohou vystavit statické mapy modelů a podle podpory obnovovat dostupné modely z API.

Vestavěné rodiny poskytovatelů

Libre WebUI obsahuje definice běžných služeb:

OpenAI a API kompatibilní s OpenAI
Anthropic
Google Gemini
Groq
Kimi Code od Moonshot AI
Mistral
OpenRouter
Hugging Face
GitHub Models
MLX LM pro místní inferenci Apple Silicon
ComfyUI
ElevenLabs

Katalogy se často mění. Pokud plugin podporuje živé hledání, považujte rozhraní za zdroj pravdy.

Vlastnictví a autorizace

Definice pluginů jsou sdílenou konfigurací instance. Každá trasa /api/plugins vyžaduje ověření a jen správci mohou definici nahrát, nainstalovat, aktualizovat nebo smazat. Aktivace je jiná: každý ověřený uživatel zapíná sdílený plugin jen pro svůj účet. Stav je v SQLite, přežije restart a neovlivní ostatní.

Při upgradu se globální seznam .status.json jednou zkopíruje existujícím účtům, ale jen pro definice přesně odpovídající kompilovaným kotvám důvěry. Starší vlastní či stínující definice zůstávají v karanténě a nové účty začínají bez aktivních pluginů.

Vestavěná definice je důvěryhodná jen při shodě normalizovaného obsahu s hashem backendu. Zapisovatelné definice se schvalují v SQLite podle normalizované cesty a úplného hashe. Instalace, aktualizace či nový import správce schválení zaznamená; přímá změna souboru ho zneplatní. Schválení a aktualizace před nahrazením souboru vymažou aktivaci všech účtů, takže každý musí prověřenou definici znovu zapnout. Vlastní definice před upgradem musí správce znovu importovat, než mohou být v katalogu, hledat modely, přijmout údaje či spustit funkci.

Proměnné se dělí podle účelu. Známé proměnné směrování mohou ukládat jen správci:

endpoint, base_url, api_path, models_endpoint, api_url, image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint, voice_clone_endpoint, api_mode, model a model_id. Deklarované config.endpoint_variable, config.models_endpoint_variable nebo config.voice_clone_endpoint_variable funkce jsou také směrováním i pod jiným názvem.

Běžní uživatelé mohou ukládat generování jako temperature a streamování. Jejich staré řádky směrování se ignorují, nevrací jako nastavené a úplný reset je odstraní. Pozdější povýšení role tak potichu neoživí neaktivní trasu.

Přihlašovací údaje

Přihlašovací údaje mohou pocházet z proměnných prostředí nebo nastavení uživatele.

Příklady prostředí:

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=...

Ve sdílené instalaci jsou lepší údaje uživatele, protože řídí vlastní účtování a limity. Klíče prostředí se hodí pro jednoho uživatele, demo nebo spravovanou instalaci.

Klíč prostředí je fallback jen při směrování a ověřování nezastíněné vestavěné definice. Import, zapisovatelná definice stínící ID nebo přepsání správce vyžadují údaje stejného účtu. Libre před fallbackem porovná kořen, pole ověřování, koncové body a selektory i známé definice a výchozí hodnoty proměnných. Kompilovaný hash manifestu zůstává autoritou, i když starší a vestavěný adresář sdílejí cestu; přepsaný manifest balíčku si důvěru nevytvoří.

Pravidlo platí pro hledání, Chat, Work, dostupnost a katalogy a brání vlastnímu bodu či starému manifestu získat operátorem spravované tajemství.

Údaje uživatele jsou při uložení svázány se zdrojem, úplným hashem, smlouvou ověřování, koncovými body, selektory a směrováním. Změna je znepřístupní do nového prověření a uložení. Starší nevázané údaje se přijmou jen na přesně ukotvené vestavěné trase a při prvním použití se vazba zapíše před vrácením klíče.

Poskytovatelé kompatibilní s OpenAI

Mnoho poskytovatelů nabízí API kompatibilní s OpenAI. Plugin může definovat:

Úplnou URL koncového bodu API
Proměnnou prostředí klíče API
Chování koncového bodu Chat
Podporu embeddingů
Hledání modelů
Volitelnou záložní mapu

Bez živého hledání použije Libre nastavenou mapu. Importovaný JSON konfiguruje formáty OpenAI Chat Completions, Responses, Anthropic Messages a Gemini. Samotný JSON nepřeloží libovolný proprietární protokol; jiná struktura potřebuje adaptér backendu.

Generování obrázků OpenAI

Vestavěný OpenAI nabízí Image API na https://api.openai.com/v1/images/generations. Aktuální je gpt-image-2; starší gpt-image-1.5, gpt-image-1, gpt-image-1-mini zůstávají pro kompatibilitu. Nové nastavení má vybrat gpt-image-2.

Obrázky používají stejné účinné údaje jako Chat: klíč uživatele nebo fallback důvěryhodné definice. Samostatný volitelný image_endpoint brání odeslání na vlastní Chat bod. Prázdná hodnota zdědí vestavěný Image API.

Volby jsou svázané s poskytovatelem. Při stejném ID odešle Libre požadavek jen vybranému. GPT Image vrací base64, které Libre převede a uloží do galerie uživatele. Trasy vyžadují ověření a přímý požadavek pluginId i model. n smí být celé JSON 1–10; řetězce a zlomky se odmítnou před poskytovatelem.

Režimy API Chat Completions a Responses

OpenAI-kompatibilní pluginy používají chat_completions nebo responses; vestavěný OpenAI volbu nabízí v Settings → Plugins.

Připojení se řeší v pořadí:

Úplné přepsání endpoint.
base_url plus volitelná api_path.
Starší endpoint pluginu.

Hodnota přesně shodná s manifestem je výchozí, ne přepsání, aby staré uložení po upgradu nestínilo nové Base URL. Skutečný vlastní úplný bod má stále nejvyšší prioritu.

Výchozí cesta je /chat/completions nebo /responses. base_url má být kořen jako https://api.example.com/v1; api_path slouží jiné relativní cestě. Úplný bod musí zahrnout operaci a má přednost. Známá přípona určuje sémantiku; vlastní cesta zachová api_mode.

Importovaný JSON může zadat stejné výchozí hodnoty:

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

Požadavky Responses používají input, max_output_tokens, zploštěné funkční nástroje, store: false a žádají šifrované uvažování pro bezstavové pokračování. Dokončený i streamovaný výstup se normalizuje na události Chat a Work. Replay stav se uchová jen, pokud úplné seřazené pole má nejvýše 64 Items a 90 KB. Items zůstávají přesné a pole se nezkracují. Vyžadují jedinečná neprázdná ID a typy a struktury zpráv, uvažování a funkcí se ověří před voláním. Příliš velký Chat použije viditelnou historii a zahodí surové funkční Items, protože neukládá odpovídající výsledky. Work s nástroji bez přesného omezeného replay se odmítne před vedlejším účinkem.

Chat v SQLite šifruje stav s danou zprávou; Work ukládá nástrojový stav do skrytých řádků, které API zpráv nevrací. Hashovaný scope váže replay na stejného poskytovatele, model, režim, konečný bod a jednosměrný otisk údajů. Při změně včetně rotace klíče se použije normalizovaná historie namísto přenosu Items přes hranici. Aktivní Work také otiskne trasu a údaje a před každým kolem je ověří; změna běh zastaví dřív, než další požadavek dostane starý stav.

Stav s nástroji musí vejít do replay limitu i úplného obalu metadata 100 KB před vedlejším účinkem. Po přerušení trvalé dávky se chybějící výsledky obnoví s přesným ID a varováním neznámého výsledku, aby poskytovatel prostor zkontroloval namísto opakování. Neúplný Responses není úspěšný tah; incomplete_details.reason se zachová a zobrazí.

Hledání odvodí /models z obou cest, například https://api.example.com/v1/responses použije https://api.example.com/v1/models. Bez kompatibilního seznamu lze použít ruční model_map. Hledání používá proměnné a údaje aktuálního uživatele a výsledek ukládá pro něj, ne do manifestu. Běží po aktivaci, obnovení, změně klíče či připojení a resetu; nesouvisející generování síť nevyvolá.

Hledání běží i samo: načtení seznamu obnoví aktivního poskytovatele s chybějícím nebo starším katalogem než PLUGIN_MODEL_DISCOVERY_TTL_MS. Backoff brání sondě každým požadavkem a deadline pomalé odpovědi; pozdější výsledek se použije příště. Konečná URL se ověří před čtením údajů či stavbou hlavičky, i z importu. Hledání a funkce nenásledují HTTP přesměrování. Nastavte přímo koncové body Chat, Work, seznamu, obrázku, embeddingu, přepisu, řeči, klonu, zvuku či videa, aby údaje nepřešly z ověřené URL na neověřenou.

Koncové body mohou být HTTP či HTTPS. HTTP posílá klíče, prompty, výsledky a obsah bez šifrování, proto jen pro vlastní bránu v důvěryhodné síti; s TLS preferujte HTTPS. Požadavky pocházejí z backendu: v kontejneru použijte službu jako http://ai-gateway:8080/v1, zatímco localhost znamená kontejner Libre. Trasy funkcí vybírají proměnné a údaje ověřeného žádajícího účtu. Libre nemá neověřený režim jednoho uživatele.

Koncové body funkcí

Přepsání Chat je odděleno od obrázků, embeddingů, přepisu, TTS, zvuku a videa. Plugin může vystavit image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint nebo proměnnou z config.endpoint_variable; klon hlasu také config.voice_clone_endpoint_variable. Prázdné pole použije deklarovaný bod; obecný Chat endpoint se pro funkci nikdy nepoužije.

Vestavěný GitHub Models při prázdném přepsání zdědí models.github.ai/inference/chat/completions. Hugging Face používá úlohové trasy a payloads hf-inference/models/{model} pro embeddingy, obrázky a TTS, ne svůj Chat bod.

Přepsání koncových bodů

endpoint je úplná URL včetně operace, například https://provider.example/v1/chat/completions, ne jen https://provider.example. Starší import může používat api_url; Libre alias přijme, ale neprázdný endpoint má přednost.

Absolutní HTTP/HTTPS jsou přijaty, jiné protokoly odmítnuty. HTTP patří vlastní bráně v důvěryhodné síti, protože nešifruje údaje. Mimo soukromou hranici používejte HTTPS. Prázdné přepsání použije definici, výslovně neplatné se odmítne místo tichého fallbacku.

Požadavky nenásledují přesměrování. Nastavte konečnou ověřenou URL; redirect se oznámí jako chyba, nepřepošle údaje dál.

Požadavky vznikají v backendu. V kontejneru localhost znamená kontejner, ne hostitele či službu. Použijte název služby brány nebo host.docker.internal, pokud je dostupný.

Hledání modelů

Settings → Plugins obsahuje Provider connections. Vyhledejte poskytovatele vlevo a vpravo zkontrolujte aktivaci a katalog. Konfigurace zůstane sbalená do volby Configure, takže výchozí pohled skrývá koncový bod, údaje a pokročilé generování.

U chatu a dokončování Refresh models spustí hledání a načte katalog i seznam Chat. Katalog je jen pro čtení: řádky jsou nalezená ID uživatele plus mapy funkcí definice. Štítky ukazují trasu, ne zdraví. Ruční či záložní ID přidejte do model_map, ne do řádku.

Při aktivaci hledá Libre s účinným bodem a údaji účtu. Vlastní trasa správce vyžaduje údaje stejného účtu; fallback prostředí jen důvěryhodný manifest. Kompatibilní API odvodí URL:

URL končící /models se použije;
známé přípony /chat/completions, /completions, /responses, /embeddings, /messages se nahradí /models;
jinak se /models přidá.

Plugin může vystavit úplný models_endpoint, který má přednost, podléhá stejné zásadě a nepřesměrovává. Uložení či reset endpoint, api_url, models_endpoint, base_url, api_path, api_mode smaže a obnoví katalog před načtením UI.

Vlastní trasy se ověří před výběrem údajů. U uložené vlastní trasy se nesmí použít klíč prostředí serveru; nastavte klíč uživatele. Fallback je jen pro důvěryhodný bod definice.

Hledání očekává OpenAI-kompatibilní pole data. Aktivace na pokus čeká, aby první obnovení ukázalo katalog. Výsledek se ukládá pro uživatele, nepřepisuje JSON a nesdílí ID s jiným účtem. Bez kompatibilního bodu, při nedostupnosti či jiném tvaru běžná aktivace zachová minulý výsledek. Úmyslná změna připojení starý katalog nejprve smaže a při selhání použije model_map.

Uložení či reset směrování smaže minulý katalog, aby modely staré destinace po změně nezůstaly.

Stav pluginu, dostupnost Work, katalogy a funkce sdílejí kontext a hranici údajů. Obrazové modely, proměnné a údaje se například řeší pro žádajícího uživatele.

Přesný výběr poskytovatele v Chat

ID modelů nejsou globálně jedinečná. Ollama a více pluginů mohou nabízet example-model. Chat proto ukládá surové ID s volitelnou identitou:

providerType: "ollama" určuje Ollama;
providerType: "plugin" plus providerId určuje přesný plugin.

Kvalifikované URL hodnoty jsou jen kolizně bezpečnými klíči výběru; požadavky dál posílají surové ID. Duplicitní názvy zůstávají oddělené a chat obnoví přesnou volbu.

Výslovná identita selhává zavřeně. Po vypnutí, smazání či zmizení modelu Libre zachová volbu jako nedostupnou a nepřepne na stejný název. Poskytovatele zapněte nebo zvolte jiný model.

Starší relace mohou mít providerType a providerId nenastavené či null. Zachovají směrování jen názvem, protože původ nelze spolehlivě určit. Výběr ukáže "provider not recorded" namísto hádání. Konkrétní volba zapíše přesného poskytovatele. Nové persony zachovají persona:<id> a zaznamenají Ollama jako podklad.

Nastavení a dědění poskytovatele

Otevřete Settings → Plugins a Configure. Panely jsou zavřené. Správci řídí definice a směrování; ostatní zapínají poskytovatele, ukládají klíče a generování, ale nevidí nahrání, instalaci, export, smazání ani směrování.

Správci vidí nejprve přepsání. Sampling zůstává v zavřených Advanced parameters. Zděděné hodnoty jsou prázdná pole s nápovědou. Pouhé otevření nekopíruje manifest do účtu.

Uložení posílá jen změněná pole. Vymazání necitlivé hodnoty obnoví výchozí; prázdné maskované citlivé pole se nemění. Reset to Defaults smaže povolená přepsání. Při selhání editor ponechá neuložené hodnoty pro opakování.

U vlastních bodů správce nechá pole prázdné pro zdědění nebo zadá úplnou kompatibilní URL.

Pluginy ve Work

Work může vedle Ollama používat aktivní completion a chat pluginy jen když:

plugin je aktivní;
model je v katalogu uživatele nebo mapě; a
údaje správce jsou dostupné.

Work ukládá typ a ID s úlohou i během; trasa závisí na přesném poskytovateli, ne jen názvu. Plugin stejného názvu nepřevezme existující úlohu.

Work adaptuje nástroje přes OpenAI, Anthropic a Gemini. Model je musí podporovat i při běžném chatu. Odmítnutí či nekompatibilní odpověď selže bez fallbacku.

Vzdálený běh může volat vícekrát a poskytovatel obdrží systémový prompt, kontext, definice a výsledky včetně souborů, adresářů či výstupu. Libre ukáže oznámení uživatele, ale operátor musí před citlivými projekty prověřit ceny, uchovávání a trénování.

Embeddings

Pluginy embeddingů se zobrazí v nastavení dokumentů. Libre také rozpozná pravděpodobné modely Ollama jako nomic-embed-text, bge, e5, gte.

Když model nenajde, UI použije místního kandidáta nomic-embed-text.

Poznámky k vývoji pluginů

Definice má funkci popsat přesně a nepředstírat podporu. Mapy udržujte malé jako zálohu a u rychlého API preferujte hledání.

Při přidání poskytovatele:

Přidejte definici.
Definujte klíč či pole uživatele.
Implementujte hledání, pokud je seznam modelů.
Přidejte mapování chatu, embeddingů, obrázků, TTS či STT.
Otestujte chybějící a chybný klíč a chybu poskytovatele.

Typy pluginů​

Vestavěné rodiny poskytovatelů​

Vlastnictví a autorizace​

Přihlašovací údaje​

Poskytovatelé kompatibilní s OpenAI​

Generování obrázků OpenAI​

Režimy API Chat Completions a Responses​

Koncové body funkcí​

Přepsání koncových bodů​

Hledání modelů​

Přesný výběr poskytovatele v Chat​

Nastavení a dědění poskytovatele​

Pluginy ve Work​

Embeddings​

Poznámky k vývoji pluginů​

Související dokumentace​