Připojení externích a vlastních poskytovatelů

Libre WebUI 0.16.0 přidává pracovní prostor Provider connections v Settings > Plugins. Slouží k zapnutí vestavěného poskytovatele, nasměrování kompatibilního pluginu na jiné API, kontrole efektivního katalogu nebo připojení brány hostované ve vlastní režii v důvěryhodné síti.

Libre WebUI nyní podporuje tyto komunikační formáty:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; a
• obsah a volání funkcí Google Gemini.

Vestavěné definice Anthropic a Gemini používají vyhrazené adaptéry vybrané podle identity poskytovatele. Nově importovaný poskytovatel používá sémantiku OpenAI Chat Completions nebo OpenAI Responses. Nasměrování na API kompatibilní s Anthropic či Gemini tyto vestavěné adaptéry automaticky nevybere. Poskytovatel s jinou strukturou požadavku, streamu, nástrojů nebo odpovědi potřebuje adaptér backendu. JSON pluginu popisuje směrování a konfiguraci, nepřekládá nesouvisející protokol.

Otevření Provider connections

1. Přihlaste se a otevřete Settings > Plugins.
2. Vyhledejte poskytovatele v levém panelu.
3. Vyberte ho a zkontrolujte aktivní stav a efektivní katalog modelů.
4. Zapněte poskytovatele pro svůj účet.
5. Configure použijte pouze pro uložení přihlašovacích údajů nebo přepsání připojení.

Konfigurace poskytovatele je ve výchozím stavu zavřená. Správci nejprve vidí nastavení připojení, zatímco ovládání vzorkování, například temperature a limity tokenů, zůstává ve zvlášť sbalené sekci Advanced parameters. Zděděné hodnoty se zobrazují jako nápověda, ne předvyplněné přepsání účtu.

Definice pluginů jsou sdílenou konfigurací instance, takže je mohou importovat, instalovat, aktualizovat a mazat jen správci. Každý ověřený uživatel spravuje vlastní aktivaci, přihlašovací údaje a povolené parametry generování.

Rychlé přidání připojení

Settings > Connections je kratší cesta pro běžný případ: jeden koncový bod kompatibilní s OpenAI a jeden klíč API. Správce vidí kartu místního běhu Ollama s jeho stavem a verzí, seznam existujících připojení a malý formulář pro další.

Přidání vyžaduje zobrazovaný název, úplnou URL Chat Completions a volitelný klíč API. Libre WebUI odvodí ID připojení, nainstaluje definici, uloží klíč na serveru, zapne připojení a zeptá se koncového bodu na poskytované modely. Nalezené modely nahradí zástupný katalog a objeví se ve výběru modelu chatu.

Každý řádek nese koncový bod, počet modelů, stav klíče, přepínač aktivace, obnovení a smazání. Pokročilejší možnosti — režimy Responses API, přepsání Base URL, katalogy podle funkcí a zásady parametrů generování — zůstávají v úplném Settings > Plugins.

Codex (přihlášení ChatGPT)

Vestavěný poskytovatel Codex (ChatGPT) nepotřebuje klíč API. Pokud má server přihlášení Codex CLI (codex login pod uživatelem operačního systému serveru), zobrazí se poskytovatel správcům a nabídne zdokumentovanou rodinu modelů Codex přes relaci ChatGPT. Přístupové tokeny se čtou z auth.json CLI, obnovují stejným klientem OAuth a zapisují zpět, aby CLI fungovalo dál. Hodnoty tokenů se nikdy neprotokolují.

Požadavky odesílá backend, nikdy kontejner úlohy, proto modely fungují i ve Work s běžnou sandboxovanou smyčkou nástrojů. Poskytovatel je pouze pro správce, protože každé volání čerpá předplatné ChatGPT vlastníka serveru. Skryjte ho pomocí CODEX_OAUTH_MODELS_ENABLED=false nebo nastavte jiné přihlášení přes CODEX_HOME.

Výběr vestavěného nebo importovaného poskytovatele

Libre WebUI obsahuje definice pro OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code od Moonshot AI, Hugging Face, GitHub Models, místní MLX LM a další služby. Vestavěnou položku použijte, když její protokol a smlouva ověřování odpovídají službě.

Pro jinou kompatibilní službu může správce importovat definici pluginu JSON. Minimální příklad brány kompatibilní s OpenAI:

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

Importujte soubor v Settings > Plugins, zapněte ho a uložte klíč API pro účet, který připojení použije. Proměnné připojení přidejte, když správci potřebují upravovat Base URL, cestu, hledání modelů nebo koncový bod funkce. Vestavěný plugins/openai.json je úplným příkladem.

U brány záměrně bez ověřování v důvěryhodné síti nastavte auth.header a auth.key_env na prázdné řetězce a vynechte auth.prefix. Libre WebUI pak nebude klíč vyžadovat ani odesílat.

Volba Chat Completions nebo Responses

Pluginy dokončování kompatibilní s OpenAI mohou použít jeden z režimů:

Režim API	Výchozí cesta požadavku	Typické pole
chat_completions	/chat/completions	messages
responses	/responses	input

Vestavěný poskytovatel OpenAI nabízí API Mode. Libre WebUI mapuje dokončený i streamovaný výstup Responses zpět do Chat a Work včetně omezeného stavu opakovaného přehrání pro uvažování a nástroje.

Změna režimu ovlivní výchozí cestu operace, nikoli protokol upstream serveru. Responses vyberte jen tehdy, když server podporuje odpovídající požadavky a události.

Nastavení Base URL nebo úplného koncového bodu

Libre WebUI řeší trasu dokončování v tomto pořadí:

1. Nestandardní úplné přepsání endpoint.
2. base_url plus volitelná api_path.
3. Koncový bod deklarovaný definicí pluginu.

Base URL použijte pro kořen API:

https://gateway.example/v1

Bez vlastní cesty odesílá Chat Completions požadavky na:

https://gateway.example/v1/chat/completions

Responses je odesílá na:

https://gateway.example/v1/responses

API Path použijte, když poskytovatel nabízí operaci na jiné cestě relativní ke kořenu. Legacy Full Endpoint použijte pouze pro úplnou URL operace; skutečný úplný koncový bod má přednost před Base URL a API Path.

Známé přípony /chat/completions, /completions, /responses také určují sémantiku požadavku. Neznámá vlastní cesta zachovává výslovně vybraný režim API.

Po změně trasy nebo klíče poskytovatele znovu uložte před testem v Chat. Když plugin deklaruje ověřování, vlastní trasa vyžaduje údaje uložené stejným účtem. Plugin bez ověřování může nechat obě pole prázdná. Libre WebUI neposílá operátorem spravovaný klíč prostředí do uživatelské destinace; fallback je jen pro důvěryhodnou vestavěnou trasu.

Hledání a údržba ID modelů

Vyberte aktivního poskytovatele chatu a použijte Refresh models. Libre WebUI znovu načte katalog poskytovatele i seznam modelů Chat.

Hledání běží také automaticky: katalog aktivního poskytovatele se obnoví, když chybí nebo je starší než PLUGIN_MODEL_DISCOVERY_TTL_MS. Refresh models vynutí okamžitou kontrolu a oznámí výsledek:

Výsledek	Význam
Katalog aktualizován	Poskytovatel odpověděl a seznam se liší od uloženého
Katalog je aktuální	Poskytovatel odpověděl stejným seznamem
Je potřeba klíč API	Není použitelný klíč, požadavek se neodeslal a starý katalog se zobrazuje
Katalog nelze načíst	Poskytovatel není dosažitelný nebo nevrátil použitelná data

Klíč nastavený pouze v prostředí se nepoužije pro nainstalovanou definici místo vestavěné; zpráva tuto situaci vysvětlí. Modely řeči, obrázků a embeddingů nalezené v katalogu se zobrazí se štítky funkcí, ale ne ve výběru modelu Chat.

Pro trasu kompatibilní s OpenAI se URL seznamu vybere takto:

• trasa končící /models se použije beze změny;
• známá přípona /chat/completions, /completions, /responses, /embeddings nebo /messages se nahradí /models; a
• jinak se /models přidá.

Obě ukázkové trasy odvodí stejnou URL:

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

Pokud odvození nevytvoří správnou URL, vystavte models_endpoint v poli variables:

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

Zděděná nebo správcem uložená hodnota má přednost. Vlastnost models_endpoint na nejvyšší úrovni manifestu se nečte. Odpověď musí obsahovat objekty modelů v poli data:

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

Nalezená ID se ukládají pro uživatele a nepřepisují sdílený soubor pluginu. Pokud poskytovatel kompatibilní hledání nepodporuje, udržujte záložní ID v model_map JSON. Katalog Provider connections je jen pro čtení; štítky funkcí popisují trasu, nejsou kontrolou zdraví.

ID modelů nejsou globálně jedinečná. Chat ukládá surové ID spolu s přesnou identitou Ollama či pluginu, takže více poskytovatelů může bezpečně nabízet stejný název. Když uložený poskytovatel zmizí, Libre WebUI zobrazí volbu jako nedostupnou a potichu ji nepřesměruje.

Samostatné nastavení generování obrázků

Vestavěný OpenAI poskytuje obrázky přes https://api.openai.com/v1/images/generations a pro nové konfigurace používá gpt-image-2. Starší ID GPT Image zůstávají v záloze pro kompatibilní existující instalace.

Trasy Chat a obrázků jsou záměrně oddělené. Vlastní Chat Base URL automaticky nepřijímá obrázkové požadavky. Prázdný image_endpoint použije koncový bod pluginu; jinak zadejte úplnou kompatibilní URL operace Image API.

Výběr obrázku je svázán s poskytovatelem. Pokud dva aktivní pluginy nabízejí stejné ID, Libre WebUI odešle požadavek jen poskytovateli vybranému v panelu obrázků.

Bezpečné připojení brány HTTP

Koncové body mohou používat absolutní HTTP nebo HTTPS. HTTP se hodí pro vlastní bránu v důvěryhodném LAN, Tailscale nebo síti kontejnerů, ale posílá klíče, prompty, výsledky a obsah bez transportního šifrování. Při překročení hranice sítě upřednostněte HTTPS.

Požadavky pocházejí z backendu, ne prohlížeče. Vyberte dosažitelnou adresu:

Umístění backendu	Příklad kořene poskytovatele
Nativní proces na stejném stroji	http://127.0.0.1:8081/v1
Služba Docker Compose	http://ai-gateway:8080/v1
Kontejner na podporovaného hostitele	http://host.docker.internal:8081/v1
Důvěryhodný hostitel LAN/Tailscale	http://192.168.1.20:8081/v1

V kontejneru localhost označuje samotný kontejner Libre WebUI, ne jinou službu ani hostitele.

Libre WebUI přijímá jen URL HTTP/HTTPS, před výběrem údajů ověřuje konečnou destinaci a nenásleduje přesměrování poskytovatele či hledání. Nastavte konečnou URL přímo.

Ověření brány před aktivací

Otestujte hledání modelů ze stroje nebo kontejneru backendu:

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

Poté otestujte operaci odpovídající režimu API.

Chat Completions:

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses:

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

Po úspěchu nastavte stejnou trasu, režim, údaje a ID v Provider connections. Zapněte poskytovatele, vyberte Refresh models a poté jeho model v Chat. Work ho může použít, pokud spolehlivě podporuje nástroje.

Řešení problémů

Příznak	Kontrola
Požadavky stále míří na vestavěný bod	Odstraňte staré úplné přepsání a uložte zamýšlené Base URL a API Path
Poskytovatel dostává nesprávná data	Slaďte API Mode s protokolem Chat Completions nebo Responses a ověřte příponu
Refresh models nevrátí ID	Otestujte /models, tvar data[].id, nastavte models_endpoint nebo udržujte model_map
Starý model zůstane po změně trasy	Uložte připojení; Libre WebUI před obnovením smaže starý nalezený katalog uživatele
Chybí klíč API	Uložte údaje uživatele pro vlastní trasu; vestavěný fallback prostředí přepsání nenásleduje
Docker nedosáhne localhost	Použijte název služby Compose, podporovaný alias nebo dosažitelnou soukromou adresu
Chat funguje, obrázky ne	Nastavte samostatný úplný image_endpoint a vyberte model obrazové funkce
Chat funguje, Work model odmítne	Ověřte podporu kompatibilních nástrojů; samotné textové dokončování nestačí
Poskytovatel vrací přesměrování	Nastavte konečnou ověřenou URL; Libre WebUI přesměrování záměrně nenásleduje

Podrobnosti směrování, údajů, replay stavu a autorizace popisují Pluginy. Instalační chyby řeší Řešení problémů.

Poděkování komunitě

Tuto příručku a prostředí Provider connections v Libre WebUI 0.16.0 ovlivnil ZhengJin (@fangzhengjin), jehož detailní zpětná vazba a koncept UX s AI v #163 pomohly pracovní postup definovat.

Související dokumentace

• Pluginy
• Práce s modely
• MLX LM na Apple Silicon
• Work: izolované pracovní prostory
• Řešení problémů