Externe en zelfgehoste providers verbinden

Libre WebUI 0.16.0 voegt een gerichte werkruimte Providerverbindingen toe binnen Instellingen > Plugins. Gebruik deze om een meegeleverde provider te activeren, een compatibele plugin naar een andere API te laten wijzen, de effectieve modelcatalogus te bekijken of een zelfgehoste gateway op een vertrouwd netwerk te verbinden.

Libre WebUI ondersteunt momenteel deze communicatie-indelingen van providers:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; en
• Google Gemini-inhoud en functieaanroepen.

De meegeleverde definities voor Anthropic en Gemini gebruiken speciale adapters die door hun provideridentiteit worden geselecteerd. Een nieuw geïmporteerde provider gebruikt de semantiek van OpenAI Chat Completions of OpenAI Responses; deze naar een Anthropic- of Gemini-compatibele API laten wijzen selecteert de meegeleverde adapters niet. Een provider met een andere vorm voor verzoeken, streaming, toolaanroepen of antwoorden heeft een backendadapter nodig. Plugin-JSON beschrijft routering en configuratie; het vertaalt geen niet-verwant protocol.

Providerverbindingen openen

1. Meld je aan en open Instellingen > Plugins.
2. Zoek in de providerlijst in het linkerpaneel.
3. Selecteer een provider om de actieve status en effectieve modelcatalogus te bekijken.
4. Activeer de provider voor je account.
5. Selecteer Configureren alleen wanneer je een referentie moet opslaan of een verbindingsinstelling wilt overschrijven.

Providerconfiguratie is standaard gesloten. Verbindingsinstellingen verschijnen voor beheerders bovenaan, terwijl steekproefbediening zoals temperatuur en tokenlimieten onder het afzonderlijk ingeklapte gedeelte Geavanceerde parameters blijft. Geërfde standaardwaarden verschijnen als hints in plaats van vooraf ingevulde accountoverschrijvingen.

Plugindefinities zijn gedeelde instantieconfiguratie; alleen beheerders kunnen ze importeren, installeren, bijwerken of verwijderen. Elke geverifieerde gebruiker beheert de eigen activeringsstatus, referentie en toegestane generatie-instellingen.

Snel een verbinding toevoegen

Instellingen > Verbindingen is een kortere route voor het gebruikelijke geval: één OpenAI-compatibel eindpunt en één API-sleutel. Beheerders zien een kaart voor de lokale Ollama-runtime met status en versie, een lijst van bestaande OpenAI-compatibele verbindingen en een klein formulier om er nog een toe te voegen.

Voor een verbinding zijn een weergavenaam, de volledige URL voor chatvoltooiingen en een optionele API-sleutel nodig. Libre WebUI leidt de verbindings-ID af uit de naam, installeert de providerdefinitie, bewaart de sleutel server-side, activeert de verbinding en vraagt welke modellen het eindpunt aanbiedt. De gevonden modellen vervangen de tijdelijke catalogus en verschijnen in de chatmodelkiezer.

Elke rij toont eindpunt, modelaantal, of een sleutel is opgeslagen, een actiefschakelaar, modelvernieuwing en verwijderen. Alles wat verder gaat — Responses API-modi, overschrijvingen van de basis-URL, catalogi per mogelijkheid en beleid voor generatieparameters — blijft in de uitgebreidere werkruimte Instellingen > Plugins hierboven.

Codex (aanmelden met ChatGPT)

De meegeleverde provider Codex (ChatGPT) heeft geen API-sleutel nodig. Wanneer de server een aanmelding van de Codex CLI heeft (codex login als de besturingssysteemgebruiker van de server), verschijnt de provider voor beheerders en biedt via de ChatGPT-sessie de gedocumenteerde Codex-modelfamilie aan. Toegangstokens worden uit het eigen auth.json van de CLI gelezen, vernieuwd via dezelfde OAuth-client als de CLI en teruggeschreven zodat de CLI blijft werken; tokenwaarden verschijnen nooit in logs.

Omdat verzoeken door de backend worden gedaan — nooit vanuit een taakcontainer — kunnen deze modellen ook Work aandrijven via de normale toolcyclus in de sandbox. De provider is alleen voor beheerders, omdat elke aanroep het ChatGPT-abonnement van de servereigenaar gebruikt. Verberg de provider volledig met CODEX_OAUTH_MODELS_ENABLED=false of wijs met CODEX_HOME naar een andere aanmelding.

Een meegeleverde of geïmporteerde provider kiezen

Libre WebUI bevat definities voor OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code van Moonshot AI, Hugging Face, GitHub Models, lokale MLX LM en andere model- of mediadiensten. Begin met een meegeleverde vermelding wanneer protocol en verificatiecontract bij de gewenste dienst passen.

Voor een andere compatibele dienst kan een beheerder een JSON-plugindefinitie importeren. Dit minimale voorbeeld beschrijft een OpenAI-compatibele gateway:

{
  "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"]
}

Importeer het bestand via Instellingen > Plugins, activeer het en sla de API-sleutel op voor het account dat de verbinding gebruikt. Voeg verbindingsvariabelen aan de definitie toe wanneer beheerders Basis-URL, pad, detectie of eindpuntvelden per mogelijkheid moeten kunnen bewerken. Het meegeleverde plugins/openai.json is een volledig voorbeeld.

Stel voor een bewust verificatieloze gateway op een vertrouwd netwerk zowel auth.header als auth.key_env in op lege tekenreeksen en laat auth.prefix weg. Libre WebUI vereist of verzendt dan geen API-sleutel voor die plugin.

Chat Completions of Responses kiezen

OpenAI-compatibele voltooiingsplugins kunnen beide API-modi gebruiken:

API-modus	Standaard verzoekpad	Gebruikelijk verzoekveld
chat_completions	/chat/completions	messages
responses	/responses	input

De meegeleverde OpenAI-provider biedt API-modus in de configuratie. Libre WebUI brengt voltooide en gestreamde Responses-uitvoer terug naar Chat en Work, inclusief begrensde herhalingsstatus voor redenering en toolaanroepen.

De modus wijzigen beïnvloedt het standaard bewerkingspad. Het verandert niet het protocol van de upstreamserver; selecteer Responses alleen wanneer die server compatibele vormen voor Responses-verzoeken en -gebeurtenissen implementeert.

Een basis-URL of volledig eindpunt configureren

Libre WebUI bepaalt een voltooiingsroute in deze volgorde:

1. Een niet-standaard overschrijving van het volledige endpoint.
2. base_url plus een optioneel api_path.
3. Het eindpunt uit de plugindefinitie.

Gebruik Basis-URL voor de API-root:

https://gateway.example/v1

Zonder aangepast pad stuurt Chat Completions verzoeken naar:

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

Responses stuurt ze in plaats daarvan naar:

https://gateway.example/v1/responses

Gebruik API-pad wanneer de provider een compatibele bewerking op een ander relatief pad aanbiedt. Gebruik Ouder volledig eindpunt alleen wanneer je de volledige bewerkings-URL moet leveren; een echt volledig eindpunt heeft voorrang op Basis-URL en API-pad.

Bekende achtervoegsels /chat/completions, /completions en /responses bepalen ook de verzoeksemantiek. Een aangepast, onbekend bewerkingspad behoudt de expliciet geselecteerde API-modus.

Sla de provider na een route- of API-sleutelwijziging opnieuw op voordat je Chat test. Wanneer de plugin verificatie declareert, vereist een aangepaste verbindingsroute een referentie die door hetzelfde account is opgeslagen. Een bewust verificatieloze plugin kan beide verificatievelden leeg laten. Libre WebUI stuurt geen door de operator beheerde omgevingssleutel naar een door de gebruiker bepaalde bestemming; terugvallen op de omgeving is voorbehouden aan de vertrouwde meegeleverde route.

Model-ID's detecteren of beheren

Selecteer een actieve chatprovider en gebruik Modellen vernieuwen om detectie uit te voeren. Libre WebUI laadt zowel de catalogus van de geselecteerde provider als de modellijst van Chat opnieuw.

Detectie gebeurt ook automatisch: de catalogus van een actieve provider wordt opnieuw ontdekt wanneer deze ontbreekt of ouder is dan PLUGIN_MODEL_DISCOVERY_TTL_MS, zodat zichtbare modellen de provider volgen in plaats van het activeringsmoment. Modellen vernieuwen forceert direct een controle en meldt de uitkomst:

Resultaat	Betekenis
Catalogus bijgewerkt	De provider antwoordde en de modellijst verschilt van de opgeslagen lijst
Catalogus is al actueel	De provider antwoordde met dezelfde lijst
API-sleutel nodig	Geen bruikbare sleutel, dus geen verzoek gedaan; de vorige catalogus blijft zichtbaar
Catalogus kon niet worden geladen	De provider was onbereikbaar of retourneerde niets bruikbaars

Een sleutel die alleen in de omgeving staat, wordt niet gebruikt voor een provider die een geïnstalleerde definitie uitvoert in plaats van de meegeleverde. Het bericht zegt dit wanneer dat van toepassing is. Spraak-, afbeeldings- en embeddingmodellen in de providercatalogus worden hier met hun functielabels vermeld, maar blijven uit de chatmodelkiezer.

Voor een OpenAI-compatibele route kiest detectie de URL van de modellijst als volgt:

• een route die op /models eindigt, wordt ongewijzigd gebruikt;
• een bekend bewerkingsachtervoegsel zoals /chat/completions, /completions, /responses, /embeddings of /messages wordt vervangen door /models; en
• anders wordt /models aan de route toegevoegd.

Beide voltooiingsroutes hieronder leiden bijvoorbeeld tot dezelfde detectie-URL:

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

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

Als afleiding niet de juiste volledige URL oplevert, bied models_endpoint dan aan in de array variables van de plugin:

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

De geërfde standaardwaarde of door de beheerder opgeslagen waarde heeft voorrang op het afgeleide adres. Een manifestproperty models_endpoint op het hoogste niveau wordt niet gelezen. Detectie verwacht een OpenAI-compatibel antwoord met modelobjecten in een array data:

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

Gevonden ID's worden per gebruiker opgeslagen en herschrijven het gedeelde pluginbestand niet. Als de provider geen compatibele detectie ondersteunt, onderhoud dan terugval-ID's in model_map in het plugin-JSON. De catalogus in Providerverbindingen is alleen-lezen; functielabels beschrijven welke pluginroute een model vermeldt en zijn geen gezondheidscontroles.

Model-ID's zijn niet wereldwijd uniek. Chat bewaart de onbewerkte model-ID samen met de exacte Ollama- of pluginprovideridentiteit, zodat een Ollama-model en meerdere plugins veilig dezelfde naam kunnen aanbieden. Als de opgeslagen provider niet meer beschikbaar is, toont Libre WebUI de selectie als niet beschikbaar in plaats van het verzoek stil naar een andere provider te routeren.

Afbeeldingen genereren afzonderlijk configureren

De meegeleverde OpenAI-provider biedt beeldgeneratie via https://api.openai.com/v1/images/generations en gebruikt voor nieuwe configuraties momenteel standaard gpt-image-2. Oudere GPT Image-ID's blijven in de terugvalcatalogus voor compatibele bestaande implementaties.

Chat- en afbeeldingsroutes zijn bewust geïsoleerd. Een aangepaste Basis-URL voor Chat ontvangt niet automatisch afbeeldingsverzoeken. Laat image_endpoint leeg om het afbeeldingeindpunt uit de plugin te gebruiken, of stel het in op de volledige compatibele bewerkings-URL van de Image API wanneer je provider die biedt.

Afbeeldingskeuzes zijn net als Chat-keuzes per provider gekwalificeerd. Als twee actieve plugins dezelfde afbeeldingsmodel-ID aanbieden, stuurt Libre WebUI het verzoek alleen naar de in het afbeeldingspaneel geselecteerde provider.

Veilig verbinding maken met een HTTP-gateway

Providereindpunten mogen absolute HTTP- of HTTPS-URL's gebruiken. HTTP is nuttig voor een zelfgehoste gateway op een vertrouwd LAN, Tailscale-netwerk of privaat containernetwerk, maar verzendt API-sleutels, prompts, toolresultaten en gegenereerde inhoud zonder transportversleuteling. Geef de voorkeur aan HTTPS wanneer de route een netwerkgrens overschrijdt of de gateway TLS ondersteunt.

Verzoeken komen van de Libre WebUI-backend, niet van de browser. Kies een adres dat vanuit die backend bereikbaar is:

Backendlocatie	Voorbeeld van providerroot
Eigen proces, dezelfde machine	http://127.0.0.1:8081/v1
Docker Compose-service	http://ai-gateway:8080/v1
Container naar ondersteunde host	http://host.docker.internal:8081/v1
Vertrouwd LAN- of Tailscale-host	http://192.168.1.20:8081/v1

In een container verwijst localhost naar de Libre WebUI-container zelf. Het verwijst niet naar een andere Compose-service en bereikt niet automatisch de host.

Libre WebUI accepteert alleen HTTP- en HTTPS-provider-URL's, valideert de uiteindelijke bestemming voordat een referentie wordt gekozen en volgt geen omleidingen voor provider- of detectieverzoeken. Configureer de uiteindelijke bewerkings-URL rechtstreeks.

De gateway controleren vóór activering

Test modeldetectie vanaf de machine of container waarop de Libre WebUI-backend draait:

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

Test daarna de bewerking die bij de geselecteerde API-modus hoort.

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
  }'

Wanneer beide aanroepen werken, stel je in Providerverbindingen dezelfde route, modus, referentie en model-ID in. Activeer de provider, kies Modellen vernieuwen en selecteer daarna het per provider gekwalificeerde model in Chat. Work kan het ook gebruiken wanneer het model betrouwbaar toolaanroepen ondersteunt.

Problemen oplossen

Symptoom	Controle
Verzoeken bereiken nog het meegeleverde eindpunt	Verwijder een oude overschrijving van het volledige eindpunt en sla de gewenste Basis-URL en het API-pad op.
De provider ontvangt de verkeerde payload	Stem API-modus af op het upstreamprotocol Chat Completions of Responses en controleer het uiteindelijke achtervoegsel.
Modellen vernieuwen levert geen ID's op	Test /models, controleer de vorm data[].id, bied de variabele models_endpoint aan/configureer die of onderhoud model_map.
Een oud model blijft na een routewijziging	Sla de wijziging op; Libre WebUI wist de verouderde ontdekte catalogus van die gebruiker vóór het vernieuwen.
De API-sleutel wordt als ontbrekend gemeld	Sla een referentie per gebruiker op voor de aangepaste route; terugvallen op de meegeleverde omgeving volgt overschrijvingen niet.
Docker kan localhost niet bereiken	Gebruik de Compose-servicenaam van de gateway, een ondersteunde hostalias of een bereikbaar privénetwerkadres.
Chat werkt maar beeldgeneratie niet	Configureer het afzonderlijke volledige image_endpoint en kies een model uit die afbeeldingsmogelijkheid.
Chat werkt maar Work weigert het model	Controleer compatibele toolaanroepen; gewone tekstvoltooiing is onvoldoende.
De provider retourneert een omleiding	Configureer de uiteindelijke gevalideerde URL rechtstreeks; Libre WebUI volgt bewust geen provideromleidingen.

Lees Plugins voor details over routering, referenties, herhalingsstatus en autorisatie. Zie Problemen oplossen voor implementatiespecifieke fouten.

Erkenning van de gemeenschap

Deze handleiding en de ervaring Providerverbindingen van Libre WebUI 0.16.0 zijn mede gevormd door ZhengJin (@fangzhengjin), wiens gedetailleerde feedback over externe providers en AI-ondersteunde UX-concept in #163 hielpen de werkstroom te bepalen.

Gerelateerde documentatie

• Plugins
• Werken met modellen
• MLX LM op Apple Silicon
• Work: geïsoleerde werkruimten
• Problemen oplossen