Підключення сторонніх і самостійно розміщених постачальників

Libre WebUI 0.16.0 додає розділ Підключення постачальників у меню Налаштування > Плагіни. Тут можна активувати вбудованого постачальника, спрямувати сумісний плагін до API, переглянути підсумковий каталог або підключити власний шлюз у довіреній мережі.

Підключення постачальників Libre WebUI із пошуком, вибором, налаштуванням, оновленням моделей і каталогом можливостей.

Підтримуються такі формати:

OpenAI Chat Completions;
OpenAI Responses;
Anthropic Messages; і
вміст і виклики функцій Google Gemini.

Вбудовані визначення Anthropic і Gemini використовують спеціальні адаптери, які вибираються за ідентичністю постачальника. Нове імпортоване визначення використовує семантику Chat Completions або Responses; зазначення сумісного з Anthropic чи Gemini API не вибирає вбудований адаптер. Інша форма запиту, потоку, виклику інструмента або відповіді потребує серверного адаптера. JSON описує маршрутизацію й конфігурацію, але не перетворює чужий протокол.

Відкриття підключень

Увійдіть і відкрийте Налаштування > Плагіни.
Знайдіть постачальника ліворуч.
Виберіть його, щоб переглянути стан і каталог.
Активуйте його для свого облікового запису.
Виберіть Налаштувати лише для облікових даних або перевизначення підключення.

Конфігурацію за замовчуванням згорнуто. Налаштування підключення відображаються адміністраторам першими, а параметри вибірки містяться в окремому згорнутому розділі Розширені параметри. Успадковані значення показуються як підказки, а не як заздалегідь заповнені перевизначення облікового запису.

Визначення є спільною конфігурацією екземпляра, тому імпортувати, встановлювати, оновлювати й видаляти їх можуть лише адміністратори. Кожен користувач керує власною активацією, обліковими даними й дозволеними параметрами створення вмісту.

Швидке додавання

Налаштування > Підключення — короткий шлях для однієї сумісної з OpenAI кінцевої точки та ключа. Адміністратор бачить стан і версію Ollama, список підключень і форму додавання.

Потрібні відображуване ім’я, повний URL кінцевої точки доповнень чату та необов’язковий ключ. Libre виводить ID підключення, установлює визначення, зберігає ключ на сервері, активує підключення й запитує список моделей. Виявлені моделі замінюють тимчасовий каталог і з’являються в селекторі.

У рядку показано кінцеву точку, кількість моделей, наявність ключа, активність, оновлення й видалення. Режими Responses, перевизначення базового URL, каталоги окремих можливостей і політика параметрів залишаються в повному інтерфейсі плагінів.

Codex (вхід через ChatGPT)

Codex (ChatGPT) не потребує ключа API. Після codex login від імені системного користувача сервера він з’являється в адміністраторів і пропонує задокументоване сімейство моделей через сеанс ChatGPT. Токени читаються з auth.json, оновлюються тим самим клієнтом OAuth і записуються назад; значення не потрапляють до журналу.

Запити виконує серверна частина, а не контейнер завдання, тому моделі працюють і в Work. Постачальник доступний лише адміністраторам, оскільки використовує підписку ChatGPT власника сервера. Приховати його можна через CODEX_OAUTH_MODELS_ENABLED=false, а вказати іншу авторизацію — через CODEX_HOME.

Вбудований або імпортований постачальник

Доступні OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code, Hugging Face, GitHub Models, локальний MLX LM та інші. Починайте з вбудованого варіанта, якщо протокол і автентифікація збігаються.

Адміністратор імпортує JSON. Мінімальний шлюз:

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

Імпортуйте визначення, активуйте його та збережіть ключ. Додайте змінні для редагованого базового URL, шляху, виявлення й кінцевих точок окремих можливостей. Повний приклад — plugins/openai.json.

Для шлюзу в довіреній мережі, який навмисно не потребує автентифікації, залиште auth.header і auth.key_env порожніми та приберіть auth.prefix; ключ не знадобиться й не надсилатиметься.

Chat Completions або Responses

Режим	Шлях	Поле
`chat_completions`	`/chat/completions`	`messages`
`responses`	`/responses`	`input`

Вбудований OpenAI пропонує Режим API. Libre перетворює завершений і потоковий вивід Responses для Chat і Work, зокрема обмежений стан відтворення міркувань і викликів інструментів.

Режим змінює шлях за замовчуванням, але не протокол сервера. Вибирайте Responses лише за сумісної форми запитів і подій.

Базовий URL або повна кінцева точка

Порядок:

Нестандартний повний endpoint.
base_url + api_path.
Кінцева точка з визначення плагіна.

Базовий URL:

https://gateway.example/v1

Chat Completions:

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

Responses:

https://gateway.example/v1/responses

Шлях API призначено для відносної операції. Застаріла повна кінцева точка призначена для повного URL; повна кінцева точка має вищий пріоритет.

Суфікси /chat/completions, /completions, /responses визначають семантику. Невідомий шлях зберігає вибраний режим.

Після зміни маршруту або ключа збережіть постачальника перед тестуванням. Користувацький маршрут з автентифікацією потребує облікових даних того самого облікового запису. Варіант без автентифікації залишає поля порожніми. Ключ середовища оператора не надсилається до користувацької точки; резервне значення застосовується лише до довіреного вбудованого маршруту.

Виявлення ID моделей

Виберіть активного постачальника й натисніть Оновити моделі. Libre повторно завантажить каталог і Chat.

Автоматичне оновлення відбувається, якщо каталогу немає або він старший за PLUGIN_MODEL_DISCOVERY_TTL_MS. Ручне оновлення повідомляє:

Результат	Значення
Каталог оновлено	Відповідь містить інший список
Уже актуальний	Отримано той самий список
Потрібен ключ API	Запит не надіслано, попередній каталог залишається видимим
Не вдалося завантажити	Кінцева точка недоступна або не повернула даних

Ключ лише із середовища не використовується для встановленого визначення замість вбудованого; повідомлення пояснює це. Моделі мовлення, зображень і вбудовувань видно з мітками можливостей, але не в селекторі чату.

URL списку моделей:

URL з закінченням /models використовується без змін;
відомий суфікс /chat/completions, /completions, /responses, /embeddings або /messages замінюється на /models; або
в решті випадках до шляху додається /models.

Приклад:

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

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

При неправильному виведенні встановіть models_endpoint в variables:

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

Успадковане або збережене адміністратором значення має пріоритет. Властивість models_endpoint верхнього рівня не читається. Очікується сумісна з OpenAI відповідь із масивом data:

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

Ідентифікатори зберігаються для користувача й не перезаписують файл. Без сумісного виявлення підтримуйте model_map. Каталог доступний лише для читання; мітки не є перевіркою працездатності.

Ідентифікатори не є глобально унікальними. Chat зберігає початковий ID разом із точною ідентичністю постачальника. Недоступний постачальник відображається як недоступний, без переспрямування.

Окреме створення зображень

Кінцева точка зображень OpenAI — https://api.openai.com/v1/images/generations; нові конфігурації за замовчуванням використовують gpt-image-2, а старі ID залишаються резервними.

Маршрути чату й зображень ізольовані. Користувацький базовий URL чату не отримує запитів зображень. Порожній image_endpoint використовує визначення плагіна, а повний URL задає сумісну операцію Image API.

Вибір пов’язаний із конкретним постачальником; однаковий ID спрямовується лише до вибраного постачальника.

Безпечний HTTP-шлюз

Допустимі HTTP і HTTPS. HTTP підходить для довіреної LAN, Tailscale або мережі контейнерів, але передає ключі, промпти, результати інструментів і вміст без транспортного шифрування. Віддавайте перевагу HTTPS із TLS.

Запити надходять із серверної частини, тому вибирайте адресу, досяжну з неї:

Розташування	Приклад
Нативно, на тому самому хості	`http://127.0.0.1:8081/v1`
Служба Compose	`http://ai-gateway:8080/v1`
Контейнер → хост	`http://host.docker.internal:8081/v1`
Довірена LAN/Tailscale	`http://192.168.1.20:8081/v1`

localhost усередині контейнера означає сам контейнер, а не сервіс чи хост.

Приймаються лише HTTP і HTTPS; кінцева адреса перевіряється до вибору облікових даних, а переспрямування не виконуються. Налаштуйте остаточний URL безпосередньо.

Перевірка шлюзу

З хоста або контейнера серверної частини:

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

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

Після успішних перевірок задайте той самий маршрут, режим, облікові дані й ID моделі, активуйте постачальника, оновіть моделі та виберіть його. Work зможе використовувати модель за надійної підтримки інструментів.

Усунення неполадок

Симптом	Перевірка
Запити надходять до вбудованої точки	Видаліть старе повне перевизначення та збережіть потрібні базовий URL і шлях API.
Неправильні дані запиту	Зіставте режим API із протоколом і перевірте кінцевий суфікс.
Немає ID моделей	Перевірте `/models`, форму `data[].id`, `models_endpoint` або `model_map`.
Після зміни маршруту залишилася стара модель	Збережіть зміну; застарілий виявлений каталог буде очищено.
Ключ не знайдено	Збережіть облікові дані користувача; вбудоване резервне значення із середовища не діє для перевизначень.
Docker не досягає localhost	Використовуйте ім’я служби, псевдонім хоста або приватну досяжну адресу.
Chat працює, зображення — ні	Налаштуйте повний `image_endpoint` і модель цієї можливості.
Chat працює, Work — ні	Підтвердьте сумісну підтримку викликів інструментів.
Постачальник переспрямовує	Налаштуйте остаточний перевірений URL; переспрямування не виконуються.

Докладніше див. у розділі Плагіни, а про помилки — у розділі Усунення неполадок.

Подяка спільноті

Посібник та інтерфейс версії 0.16.0 сформовано завдяки ZhengJin (@fangzhengjin): докладні відгуки про сторонніх постачальників і створена за допомогою ШІ концепція інтерфейсу в #163 допомогли визначити цей процес.

Відкриття підключень​

Швидке додавання​

Codex (вхід через ChatGPT)​

Вбудований або імпортований постачальник​

Chat Completions або Responses​

Базовий URL або повна кінцева точка​

Виявлення ID моделей​

Окреме створення зображень​

Безпечний HTTP-шлюз​

Перевірка шлюзу​

Усунення неполадок​

Подяка спільноті​

Пов’язані документи​