Forbind tredjepartsudbydere og selvhostede udbydere

Libre WebUI 0.16.0 tilføjer det fokuserede arbejdsområde Provider connections i Settings > Plugins. Brug det til at aktivere en medfølgende udbyder, pege et kompatibelt plugin på et andet API, gennemgå det effektive modelkatalog eller forbinde en selvhostet gateway på et betroet netværk.

Libre WebUI understøtter i øjeblikket følgende wire-formater:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; og
• Google Gemini-indhold og funktionskald.

De medfølgende definitioner til Anthropic og Gemini bruger dedikerede adaptere, som vælges ud fra deres udbyderidentitet. En nyimporteret udbyder bruger semantikken fra OpenAI Chat Completions eller OpenAI Responses. Hvis den peges på et API, der er kompatibelt med Anthropic eller Gemini, vælges de medfølgende adaptere ikke automatisk. En udbyder med en anden struktur for anmodninger, streaming, værktøjskald eller svar kræver en backendadapter. Plugin-JSON beskriver routing og konfiguration; det oversætter ikke en ikke-relateret protokol.

Åbn Provider connections

1. Log ind, og åbn Settings > Plugins.
2. Søg i udbyderlisten i venstre panel.
3. Vælg en udbyder for at gennemgå dens aktive tilstand og effektive modelkatalog.
4. Aktivér udbyderen for din konto.
5. Vælg kun Configure, når du skal gemme legitimationsoplysninger eller tilsidesætte en forbindelsesindstilling.

Udbyderkonfigurationen er lukket som standard. Forbindelsesindstillingerne vises først for administratorer, mens samplingkontroller som temperature og tokengrænser ligger under den separate, sammenklappede sektion Advanced parameters. Nedarvede standardværdier vises som hints i stedet for forudfyldte kontotilsidesættelser.

Plugindefinitioner er fælles instanskonfiguration, så kun administratorer kan importere, installere, opdatere eller slette dem. Hver godkendt bruger styrer sin egen aktiveringstilstand, sine legitimationsoplysninger og sine tilladte genereringsindstillinger.

Tilføj hurtigt en forbindelse

Settings > Connections er en kortere vej til det almindelige tilfælde: ét OpenAI-kompatibelt slutpunkt og én API-nøgle. Administratorer ser et kort for den lokale Ollama-kørselstid med sundhed og version, en liste over eksisterende OpenAI-kompatible forbindelser og en lille formular til at tilføje en ny.

En forbindelse kræver et visningsnavn, den fulde URL til Chat Completions og en valgfri API-nøgle. Libre WebUI afleder forbindelses-ID'et fra navnet, installerer udbyderdefinitionen, gemmer nøglen på serversiden, aktiverer forbindelsen og spørger slutpunktet, hvilke modeller det leverer. De registrerede modeller erstatter pladsholderkataloget og vises i Chat-modelvælgeren.

Hver række indeholder slutpunkt, modelantal, om en nøgle er gemt, en aktiveringskontakt, modelopdatering og sletning. Alt ud over dette — Responses API-tilstande, tilsidesættelser af Base URL, kataloger pr. funktion og politik for genereringsparametre — findes stadig i det fulde arbejdsområde Settings > Plugins, som er beskrevet ovenfor.

Codex (log ind med ChatGPT)

Den medfølgende udbyder Codex (ChatGPT) kræver ingen API-nøgle. Når serveren har et Codex CLI-login (codex login som serverens operativsystembruger), vises udbyderen for administratorer og tilbyder den dokumenterede Codex-modelfamilie gennem ChatGPT-sessionen. Adgangstokens læses fra CLI'ens egen auth.json, opdateres gennem samme OAuth-klient som CLI'en bruger og skrives tilbage, så CLI'en fortsat fungerer. Tokenværdier vises aldrig i logfiler.

Da anmodningerne foretages af backend — aldrig inde fra en opgavecontainer — kan modellerne også drive Work med den normale sandkassebaserede værktøjsløkke. Udbyderen er kun til administratorer, fordi hvert kald bruger serverejerens ChatGPT-abonnement. Skjul den helt med CODEX_OAUTH_MODELS_ENABLED=false, eller peg på et andet login med CODEX_HOME.

Vælg en medfølgende eller importeret udbyder

Libre WebUI indeholder definitioner til OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code fra Moonshot AI, Hugging Face, GitHub Models, lokal MLX LM og andre model- eller medietjenester. Start med en medfølgende post, når dens protokol og godkendelseskontrakt passer til den tjeneste, du vil bruge.

Til en anden kompatibel tjeneste kan en administrator importere en plugin-JSON-definition. Dette minimale eksempel beskriver en OpenAI-kompatibel 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"]
}

Importér filen fra Settings > Plugins, aktivér den, og gem API-nøglen til den konto, der skal bruge forbindelsen. Føj forbindelsesvariabler til definitionen, når administratorer har brug for redigerbare felter til Base URL, sti, modelsøgning eller funktionsspecifikke slutpunkter. Den medfølgende plugins/openai.json er et komplet eksempel.

Til en gateway uden godkendelse på et betroet netværk skal både auth.header og auth.key_env sættes til tomme strenge, og auth.prefix skal udelades. Libre WebUI kræver eller sender derefter ingen API-nøgle til pluginet.

Vælg Chat Completions eller Responses

OpenAI-kompatible completionplugins kan bruge en af API-tilstandene:

API-tilstand	Standardsti for anmodning	Typisk anmodningsfelt
chat_completions	/chat/completions	messages
responses	/responses	input

Den medfølgende OpenAI-udbyder viser API Mode i sin konfiguration. Libre WebUI mapper færdige og streamede Responses-resultater tilbage til Chat og Work, herunder afgrænset replay-tilstand til ræsonnering og værktøjskald.

En ændring af tilstanden påvirker standardstien for operationen. Den ændrer ikke protokollen, som upstream-serveren taler, så vælg kun Responses, når serveren implementerer kompatible strukturer til Responses-anmodninger og -hændelser.

Konfigurer Base URL eller et fuldt slutpunkt

Libre WebUI vælger en completionrute i denne rækkefølge:

1. En fuld, ikke-standardmæssig tilsidesættelse af endpoint.
2. base_url plus en valgfri api_path.
3. Slutpunktet, der er erklæret i plugindefinitionen.

Brug Base URL til API-roden:

https://gateway.example/v1

Uden en tilpasset sti sender Chat Completions-tilstanden anmodninger til:

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

Responses-tilstanden sender dem i stedet til:

https://gateway.example/v1/responses

Brug API Path, når udbyderen udstiller en kompatibel operation på en anden sti relativt til roden. Brug kun Legacy Full Endpoint, når du skal angive hele operations-URL'en. Et reelt fuldt slutpunkt har forrang for Base URL og API Path.

Kendte slutpunktssuffikser som /chat/completions, /completions og /responses identificerer også anmodningens semantik. En tilpasset, ukendt operationssti beholder den eksplicit valgte API-tilstand.

Efter ændring af rute eller API-nøgle skal udbyderen gemmes igen, før Chat testes. Når pluginet erklærer godkendelse, kræver en tilpasset forbindelsesrute legitimationsoplysninger gemt af samme konto. Et plugin uden godkendelse kan lade begge godkendelsesfelter være tomme. Libre WebUI sender ikke en operatørstyret miljønøgle til en brugerdefineret destination. Miljøfallback er forbeholdt den betroede, medfølgende rute.

Find eller vedligehold model-ID'er

Vælg en aktiv chatudbyder, og brug Refresh models til at køre modelsøgning. Libre WebUI genindlæser både den valgte udbyders katalog og Chats modelliste.

Modelsøgning kører også automatisk. En aktiv udbyders katalog søges igen, når det mangler eller er ældre end PLUGIN_MODEL_DISCOVERY_TTL_MS, så de viste modeller følger udbyderen og ikke tidspunktet for aktivering. Refresh models gennemtvinger en øjeblikkelig kontrol og rapporterer resultatet:

Resultat	Betydning
Kataloget blev opdateret	Udbyderen svarede, og modellisten adskiller sig fra den gemte
Kataloget er allerede aktuelt	Udbyderen svarede med samme liste
API-nøgle kræves	Ingen brugbar nøgle, så ingen anmodning blev sendt; forrige katalog vises
Kataloget kunne ikke indlæses	Udbyderen kunne ikke nås eller returnerede intet brugbart

En nøgle, der kun findes i miljøet, bruges ikke til en udbyder, som kører en installeret definition i stedet for den medfølgende. Meddelelsen forklarer dette, når det gælder. Tale-, billed- og embeddingmodeller, der findes i udbyderens katalog, vises her med funktionslabels, men holdes ude af Chat-modelvælgeren.

Til en OpenAI-kompatibel rute vælges URL'en til modellisten sådan:

• en rute, der slutter med /models, bruges uændret;
• et kendt operationssuffiks som /chat/completions, /completions, /responses, /embeddings eller /messages erstattes med /models; og
• ellers føjes /models til ruten.

For eksempel giver begge completionruter samme søge-URL:

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

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

Når afledningen ikke kan skabe den korrekte fulde URL, skal models_endpoint udstilles i pluginets variables-array:

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

Den nedarvede standard eller den administratorgemte værdi har forrang for den afledte adresse. Manifestegenskaben models_endpoint på øverste niveau læses ikke. Søgningen forventer et OpenAI-kompatibelt svar med modelobjekter i et data-array:

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

Registrerede ID'er gemmes pr. bruger og omskriver ikke den fælles pluginfil. Hvis udbyderen ikke implementerer kompatibel søgning, skal reserve-model-ID'er vedligeholdes i model_map i plugin-JSON. Kataloget i Provider connections er skrivebeskyttet. Funktionslabels beskriver, hvilken pluginrute der viser en model; de er ikke sundhedstjek.

Model-ID'er er ikke globalt unikke. Chat gemmer det rå model-ID sammen med den nøjagtige identitet for Ollama- eller pluginudbyderen, så en Ollama-model og flere plugins sikkert kan udstille samme navn. Hvis den gemte udbyder bliver utilgængelig, viser Libre WebUI valget som utilgængeligt i stedet for lydløst at route anmodningen til en anden udbyder.

Konfigurer billedgenerering separat

Den medfølgende OpenAI-udbyder udstiller billedgenerering gennem https://api.openai.com/v1/images/generations og bruger i øjeblikket gpt-image-2 som standard for nye konfigurationer. Ældre GPT Image-ID'er forbliver i reservekataloget til kompatible eksisterende installationer.

Chat- og billedruter er bevidst adskilt. En tilpasset Chat Base URL modtager ikke automatisk billedanmodninger. Lad image_endpoint være tom for at bruge det billedslutpunkt, pluginet erklærer, eller sæt den til den komplette kompatible Image API-operations-URL, når udbyderen leverer en.

Billedvalg er knyttet til udbyderen ligesom Chat-valg. Hvis to aktive plugins udstiller samme billedmodel-ID, sender Libre WebUI kun anmodningen til den udbyder, der er valgt i billedpanelet.

Forbind en HTTP-gateway sikkert

Udbyderslutpunkter kan bruge absolutte HTTP- eller HTTPS-URL'er. HTTP er nyttigt til en selvhostet gateway på et betroet LAN, Tailscale-netværk eller privat containernetværk, men sender API-nøgler, prompter, værktøjsresultater og genereret indhold uden transportkryptering. Foretræk HTTPS, når ruten krydser en netværksgrænse, eller gatewayen understøtter TLS.

Anmodninger kommer fra Libre WebUI-backend, ikke fra browseren. Vælg en adresse, som backend kan nå:

Backendplacering	Eksempel på udbyderrod
Indbygget proces, samme maskine	http://127.0.0.1:8081/v1
Docker Compose-tjeneste	http://ai-gateway:8080/v1
Container til understøttet vært	http://host.docker.internal:8081/v1
Betroet LAN- eller Tailscale-vært	http://192.168.1.20:8081/v1

Inde i en container identificerer localhost selve Libre WebUI-containeren. Det identificerer ikke en anden Compose-tjeneste og når ikke automatisk værten.

Libre WebUI accepterer kun HTTP- og HTTPS-URL'er til udbydere, validerer den endelige destination før valg af legitimationsoplysninger og følger ikke omdirigeringer for udbyder- eller søgeanmodninger. Konfigurer den endelige operations-URL direkte.

Verificer gatewayen før aktivering

Test modelsøgning fra den maskine eller container, der kører Libre WebUI-backend:

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

Test derefter den operation, der svarer til den valgte API-tilstand.

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

Når begge kald fungerer, skal du konfigurere samme rute, tilstand, legitimationsoplysninger og model-ID i Provider connections. Aktivér udbyderen, vælg Refresh models, og vælg derefter dens udbydertilknyttede model i Chat. Work kan også bruge den, når modellen pålideligt understøtter værktøjskald.

Fejlfinding

Symptom	Kontrollér
Anmodninger når stadig det medfølgende slutpunkt	Fjern en gammel fuld slutpunktstilsidesættelse, og gem den ønskede Base URL og API Path
Udbyderen modtager forkert payload	Match API Mode med upstream-protokollen Chat Completions eller Responses, og verificer det endelige suffiks
Refresh models returnerer ingen ID'er	Test /models, verificer formen data[].id, udstil/konfigurer models_endpoint, eller vedligehold model_map
En tidligere model er tilbage efter ruteændring	Gem forbindelsesændringen; Libre WebUI rydder brugerens gamle registrerede katalog før opdatering
API-nøglen rapporteres som manglende	Gem legitimationsoplysninger pr. bruger til den tilpassede rute; den medfølgende miljøfallback følger ikke tilsidesættelser
En Docker-installation kan ikke nå localhost	Brug gatewayens Compose-tjenestenavn, et understøttet værtsalias eller en privat netværksadresse, der kan nås
Chat virker, men billedgenerering gør ikke	Konfigurer en separat fuld image_endpoint, og vælg en model, som billedfunktionen udstiller
Chat virker, men Work afviser modellen	Bekræft, at modellen understøtter kompatible værktøjskald; almindelig tekst-completion er ikke nok
Udbyderen returnerer en omdirigering	Konfigurer den endelige validerede URL direkte; Libre WebUI følger bevidst ikke udbyderomdirigeringer

Læs Plugins for detaljer om routing, legitimationsoplysninger, replay-tilstand og godkendelsesadfærd. Se Fejlfinding for installationsspecifikke fejl.

Tak til fællesskabet

Denne vejledning og oplevelsen Provider connections i Libre WebUI 0.16.0 blev formet af ZhengJin (@fangzhengjin), hvis detaljerede feedback om tredjepartsudbydere og AI-assisterede UX-koncept i #163 bidrog til arbejdsgangen.

Relateret dokumentation

• Plugins
• Arbejde med modeller
• MLX LM på Apple Silicon
• Work: isolerede arbejdsområder
• Fejlfinding