Łączenie dostawców zewnętrznych i samodzielnie hostowanych

Libre WebUI 0.16.0 dodaje obszar Połączenia dostawców w Ustawienia > Wtyczki. Służy do aktywacji dołączonego dostawcy, skierowania zgodnej wtyczki do innego API, sprawdzenia efektywnego katalogu lub połączenia samodzielnej bramy w zaufanej sieci.

Libre WebUI obsługuje formaty komunikacji:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; oraz
• treści i wywołania funkcji Google Gemini.

Dołączone Anthropic i Gemini używają specjalnych adapterów wybranych przez tożsamość dostawcy. Nowo importowany dostawca używa semantyki OpenAI Chat Completions albo Responses; wskazanie API zgodnego z Anthropic/Gemini nie wybiera tych adapterów. Inny kształt żądania, strumienia, narzędzia lub odpowiedzi wymaga adaptera zaplecza. JSON opisuje routing i konfigurację, nie tłumaczy obcego protokołu.

Otwieranie Połączeń dostawców

1. Zaloguj się i otwórz Ustawienia > Wtyczki.
2. Wyszukaj dostawcę na liście po lewej.
3. Wybierz go, aby sprawdzić aktywność i efektywny katalog.
4. Aktywuj dla swojego konta.
5. Wybierz Konfiguruj tylko, gdy zapisujesz poświadczenie lub zastępujesz ustawienie.

Konfiguracja jest domyślnie zamknięta. Ustawienia połączenia są pierwsze dla administratorów, a parametry próbkowania w osobno zwiniętej sekcji Parametry zaawansowane. Dziedziczone wartości są wskazówkami, nie wstępnie wpisanymi nadpisaniami konta.

Definicje wtyczek są wspólną konfiguracją instancji, więc tylko administratorzy je importują, instalują, aktualizują i usuwają. Użytkownik kontroluje własną aktywację, poświadczenie i dozwolone ustawienia generowania.

Szybkie dodanie połączenia

Ustawienia > Połączenia to krótsza droga dla jednego punktu zgodnego z OpenAI i klucza API. Administrator widzi kartę lokalnego Ollama ze stanem i wersją, listę połączeń i formularz.

Dodanie wymaga nazwy, pełnego URL chat completions i opcjonalnego klucza. Libre WebUI wyprowadza ID z nazwy, instaluje definicję, zapisuje klucz na serwerze, aktywuje i pyta o modele. Wykryte modele zastępują katalog tymczasowy i pojawiają się w selektorze.

Wiersz pokazuje punkt, liczbę modeli, zapis klucza, aktywność, odświeżenie i usunięcie. Tryby Responses, nadpisania bazowego URL, katalogi per możliwość i polityka parametrów pozostają w pełnym Ustawienia > Wtyczki.

Codex (logowanie ChatGPT)

Dołączony Codex (ChatGPT) nie wymaga klucza API. Gdy serwer ma logowanie Codex CLI (codex login jako użytkownik systemu serwera), dostawca pojawia się administratorom i oferuje udokumentowaną rodzinę przez sesję ChatGPT. Tokeny są czytane z auth.json CLI, odświeżane tym samym klientem OAuth i zapisywane z powrotem; wartości nie pojawiają się w logach.

Żądania pochodzą z zaplecza, nigdy kontenera zadania, więc modele obsługują Work z normalną pętlą narzędzi. Dostawca jest tylko dla administratorów, bo każde wywołanie zużywa subskrypcję ChatGPT właściciela serwera. Ukryj go przez CODEX_OAUTH_MODELS_ENABLED=false lub wskaż inne logowanie przez CODEX_HOME.

Wybór dostawcy dołączonego lub importowanego

Libre WebUI zawiera OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code Moonshot AI, Hugging Face, GitHub Models, lokalny MLX LM i inne usługi. Zacznij od dołączonej pozycji, gdy protokół i uwierzytelnianie pasują.

Administrator może importować JSON dla innej zgodnej usługi. Minimalna brama zgodna z 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"]
}

Importuj w Ustawienia > Wtyczki, aktywuj i zapisz klucz dla konta. Dodaj zmienne połączenia, gdy administratorzy mają edytować bazowy URL, ścieżkę, wykrywanie lub punkty per możliwość. Pełny przykład: plugins/openai.json.

Dla celowo nieuwierzytelnionej bramy w zaufanej sieci ustaw auth.header i auth.key_env jako puste ciągi i pomiń auth.prefix. Libre nie wymaga ani nie wysyła klucza.

Chat Completions lub Responses

Wtyczki zgodne z OpenAI obsługują dwa tryby:

Tryb API	Domyślna ścieżka	Typowe pole
chat_completions	/chat/completions	messages
responses	/responses	input

Dołączony OpenAI udostępnia Tryb API. Libre mapuje gotowe i strumieniowe Responses do Chat i Work, w tym ograniczony stan odtwarzania rozumowania i narzędzi.

Zmiana trybu wpływa na domyślną ścieżkę, nie protokół upstream. Wybierz Responses tylko przy zgodnych kształtach żądań i zdarzeń.

Bazowy URL lub pełny punkt końcowy

Trasa jest rozwiązywana kolejno:

1. Niedomyślne pełne nadpisanie endpoint.
2. base_url i opcjonalne api_path.
3. Punkt z definicji.

Bazowy URL korzenia API:

https://gateway.example/v1

Chat Completions bez ścieżki wysyła do:

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

Responses do:

https://gateway.example/v1/responses

Użyj Ścieżki API dla zgodnej operacji względnej. Starszy pełny punkt tylko dla kompletnego URL; pełny ma pierwszeństwo.

Znane przyrostki /chat/completions, /completions, /responses też określają semantykę. Nieznana ścieżka zachowuje jawny tryb.

Po zmianie trasy lub klucza zapisz dostawcę przed testem. Trasa niestandardowa wymagająca uwierzytelniania potrzebuje poświadczenia tego samego konta. Wtyczka bez uwierzytelniania zostawia pola puste. Libre WebUI nie wysyła zarządzanego klucza środowiskowego do celu użytkownika; fallback środowiska jest tylko dla zaufanej trasy dołączonej.

Wykrywanie i utrzymywanie identyfikatorów modeli

Wybierz aktywnego dostawcę czatu i Odśwież modele. Libre przeładuje jego katalog i listę Chat.

Wykrywanie działa też automatycznie, gdy katalogu brak lub jest starszy niż PLUGIN_MODEL_DISCOVERY_TTL_MS. Odśwież modele wymusza kontrolę:

Wynik	Znaczenie
Katalog zaktualizowany	Dostawca odpowiedział inną listą
Katalog jest aktualny	Dostawca zwrócił tę samą listę
Potrzebny klucz API	Brak klucza, brak żądania; stary katalog pozostaje
Nie można wczytać katalogu	Dostawca nieosiągalny lub brak użytecznych danych

Klucz tylko w środowisku nie jest używany dla zainstalowanej zamiast dołączonej definicji; komunikat to wyjaśnia. Modele mowy, obrazów i osadzania są tu widoczne z etykietami, ale nie trafiają do selektora czatu.

Dla trasy zgodnej z OpenAI URL modeli jest wybierany tak:

• trasa kończąca się /models bez zmian;
• znany przyrostek /chat/completions, /completions, /responses, /embeddings lub /messages zastąpiony /models; albo
• dołączone /models.

Obie trasy dają ten sam URL:

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

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

Gdy wyprowadzenie jest niewłaściwe, wystaw models_endpoint w variables:

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

Wartość dziedziczona lub zapisana przez administratora ma pierwszeństwo. Właściwość najwyższego poziomu models_endpoint nie jest czytana. Odpowiedź ma mieć obiekty w data:

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

Wykryte ID są per użytkownik i nie zmieniają pliku. Bez zgodnego wykrywania utrzymuj model_map. Katalog jest tylko do odczytu; etykiety mówią, która trasa wymienia model, nie sprawdzają zdrowia.

ID nie są globalnie unikatowe. Chat zapisuje surowe ID z dokładną tożsamością Ollama lub wtyczki, więc nazwy mogą się powtarzać. Niedostępny zapisany dostawca jest oznaczany jako niedostępny, nie zastępowany.

Oddzielna konfiguracja obrazów

Dołączony OpenAI używa https://api.openai.com/v1/images/generations i domyślnie gpt-image-2 dla nowych konfiguracji. Starsze GPT Image-ID pozostają jako fallback.

Trasy czatu i obrazów są izolowane. Niestandardowy bazowy URL czatu nie dostaje obrazów. Puste image_endpoint używa definicji, a pełny URL ustawia zgodną operację Image API.

Wybór obrazów jest kwalifikowany dostawcą. Przy tym samym ID żądanie trafia tylko do wybranego w panelu.

Bezpieczna brama HTTP

Punkty mogą używać HTTP lub HTTPS. HTTP przydaje się w zaufanym LAN, Tailscale lub sieci kontenerów, ale przesyła klucze, prompty, wyniki i treść bez szyfrowania. Preferuj HTTPS poza granicą sieci lub przy TLS.

Żądania pochodzą z zaplecza, nie przeglądarki. Wybierz osiągalny adres:

Lokalizacja zaplecza	Przykład
Proces natywny, ta sama maszyna	http://127.0.0.1:8081/v1
Usługa Docker Compose	http://ai-gateway:8080/v1
Kontener do obsługiwanego hosta	http://host.docker.internal:8081/v1
Zaufany LAN/Tailscale	http://192.168.1.20:8081/v1

W kontenerze localhost oznacza kontener Libre WebUI, nie inną usługę ani hosta.

Libre przyjmuje tylko HTTP/HTTPS, sprawdza cel przed wyborem poświadczenia i nie śledzi przekierowań. Podaj końcowy URL.

Weryfikacja bramy przed aktywacją

Przetestuj wykrywanie z maszyny/kontenera zaplecza:

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

Następnie operację trybu.

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 sukcesie ustaw tę samą trasę, tryb, poświadczenie i ID. Aktywuj, odśwież, wybierz kwalifikowany model. Work może go użyć przy niezawodnych wywołaniach narzędzi.

Rozwiązywanie problemów

Objaw	Sprawdzenie
Żądania nadal trafiają do dołączonego punktu	Usuń stare pełne nadpisanie, zapisz bazowy URL i ścieżkę.
Dostawca dostaje zły ładunek	Dopasuj tryb do protokołu i końcowego przyrostka.
Odświeżenie nie zwraca ID	Testuj /models, data[].id, ustaw models_endpoint albo utrzymuj model_map.
Stary model zostaje po zmianie	Zapisz zmianę; Libre czyści stary wykryty katalog przed odświeżeniem.
Brak klucza API	Zapisz poświadczenie per użytkownik; fallback środowiska nie podąża za nadpisaniem.
Docker nie osiąga localhost	Użyj nazwy usługi, aliasu hosta lub osiągalnego adresu prywatnego.
Czat działa, obrazy nie	Ustaw osobny pełny image_endpoint i właściwy model.
Czat działa, Work odrzuca	Potwierdź zgodne wywołania narzędzi; tekst nie wystarcza.
Dostawca przekierowuje	Ustaw końcowy sprawdzony URL; Libre nie śledzi przekierowań.

Szczegóły routingu, poświadczeń, odtwarzania i autoryzacji: Wtyczki. Błędy wdrożenia: Rozwiązywanie problemów.

Podziękowanie społeczności

Przewodnik i środowisko Połączeń dostawców 0.16.0 powstały dzięki ZhengJin (@fangzhengjin), którego szczegółowe uwagi i wspomagana przez AI koncepcja UX w #163 pomogły zdefiniować przepływ.

Powiązana dokumentacja

• Wtyczki
• Praca z modelami
• MLX LM na Apple Silicon
• Work: odizolowane obszary robocze
• Rozwiązywanie problemów