Плагіни

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

Типи плагінів

Тип	Призначення
Чат / доповнення	Текстові й чат-моделі API провайдерів
Векторні подання	Пошук у документах і пам’яті
Зображення	Моделі зображень і сервери на кшталт ComfyUI
Текст у мовлення	Провайдери синтезу голосу
Мова в текст	Провайдери транскрипції
Генерування звуку	Провайдери звукового вмісту
Генерування відео	Асинхронні провайдери відео

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

Вбудовані родини провайдерів

Libre WebUI містить визначення для:

• OpenAI та сумісних API
• Anthropic
• Google Gemini
• Groq
• Kimi Code від Moonshot AI
• Mistral
• OpenRouter
• Hugging Face
• GitHub Models
• MLX LM для локального Apple Silicon
• ComfyUI
• ElevenLabs

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

Власність та авторизація

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

Під час оновлення старий глобальний список .status.json один раз копіюється на наявні облікові записи, але лише для визначень, що точно відповідають скомпільованим якорям довіри Libre WebUI. Старі власні або shadow-визначення лишаються в карантині й неактивні. Нові облікові записи починають без активних плагінів.

Вбудоване визначення довірене лише тоді, коли нормалізований вміст збігається з хешем сервера. Записувані визначення схвалюються в SQLite за нормалізованим шляхом і повним хешем. Установлення, оновлення або повторний імпорт записує схвалення; пряма зміна файлу скасовує його. Схвалення й оновлення очищають активацію всіх облікових записів перед заміною, тому користувачі мають повторно активувати перевірене визначення. Старі власні визначення треба повторно імпортувати, перш ніж вони з’являться в каталогах, виявлятимуть моделі, прийматимуть облікові дані або виконуватимуть можливість.

Змінні поділено за призначенням. Лише адміністратори можуть зберігати відомі змінні маршрутизації:

endpoint, base_url, api_path, models_endpoint, api_url, image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint, voice_clone_endpoint, api_mode, model, model_id. Оголошені можливістю config.endpoint_variable, config.models_endpoint_variable або config.voice_clone_endpoint_variable також вважаються маршрутизацією незалежно від назви.

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

Облікові дані

Вони можуть надходити із середовища або налаштувань користувача.

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=sk-or-...
KIMI_API_KEY=...
GITHUB_API_KEY=github_pat_...
ELEVENLABS_API_KEY=...

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

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

Це правило діє для виявлення, Chat, Work, перевірок доступності й каталогів. Воно не дає власній точці або старому маніфесту отримати секрет оператора.

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

Провайдери, сумісні з OpenAI

Плагін може визначати:

• Повний URL API
• Змінну середовища ключа
• Поведінку чату
• Підтримку векторних подань
• Виявлення моделей
• Резервну карту моделей

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

Генерування зображень OpenAI

Вбудований OpenAI використовує https://api.openai.com/v1/images/generations. Поточна модель — gpt-image-2; застарілі gpt-image-1.5, gpt-image-1, gpt-image-1-mini лишаються для сумісних наявних розгортань, але нові мають вибирати gpt-image-2.

Зображення використовують ті самі ефективні облікові дані, що Chat: ключ користувача або резерв вбудованого провайдера. Окремий необов’язковий image_endpoint не дає власній точці чату випадково отримати запит зображення; порожнє поле успадковує вбудовану Image API.

Вибір зображення прив’язаний до провайдера. За однакових ID запит отримує лише вибраний у панелі. Відповіді GPT Image містять base64, який Libre перетворює на зображення в застосунку й зберігає в галереї користувача. Маршрути потребують автентифікації та pluginId разом із model. Поле n може бути цілим JSON від 1 до 10; числові рядки й дроби відхиляються до провайдера.

Режими Chat Completions і Responses API

Плагіни доповнення можуть використовувати chat_completions або responses; вбудований OpenAI пропонує вибір у Налаштування → Плагіни.

Порядок налаштувань:

1. Повне перевизначення endpoint.
2. base_url та необов’язковий api_path.
3. Старий endpoint плагіна.

Значення, що точно збігається з маніфестом, вважається типовим, а не перевизначенням, щоб старе збережене значення не затіняло новий Base URL після оновлення. Справді власна повна точка має найвищий пріоритет.

Типові шляхи — /chat/completions і /responses. base_url має бути коренем, як https://api.example.com/v1; api_path задає іншу відносну операцію. Повна точка містить увесь шлях і має пріоритет. Відомі суфікси /chat/completions, /completions, /responses визначають семантику; власні шляхи зберігають api_mode.

JSON може задати ті самі значення:

{
  "endpoint": "https://api.example.com/v1/chat/completions",
  "api_mode": "responses",
  "base_url": "https://api.example.com/v1",
  "api_path": "/responses"
}

Responses використовує input, max_output_tokens, спрощені function tools, store: false і запитує зашифрований вміст міркування для продовження без стану. Готовий і потоковий результат нормалізується до подій Libre. Стан відтворення зберігається лише коли впорядкований масив output Item має не більше 64 Items і 90 KB; Items не обрізаються. Потрібні унікальні непорожні ID й типи, структури повідомлень, міркування й function-call перевіряються до побічного ефекту. Завеликий стан Chat повертається до видимої історії. Chat відкидає сирі function-call Items без відповідних результатів. Work із інструментами без точного обмеженого стану відхиляється до виконання побічного ефекту.

SQLite шифрує збережений стан провайдера разом із повідомленням; Work тримає службовий стан у прихованих рядках контексту, яких API повідомлень не повертає. Хеш області прив’язує відтворення до провайдера, моделі, режиму Responses, остаточної точки й одностороннього відбитка облікових даних. При зміні, зокрема ротації ключа, Libre використовує нормалізовану історію, не передаючи Items через межу автентифікації. Активний Work також перевіряє маршрут і ключ перед кожним раундом; зміна зупиняє запуск до передачі попереднього стану.

Стан інструментів має вміститися в ліміт відтворення та повну обгортку 100 KB до побічного ефекту. Після перерваного пакета відсутній результат відновлюється з точним ID виклику й попередженням про невідомий результат, щоб провайдер перевірив робочу область, а не повторив можливий ефект. Незавершений Responses не вважається успішним; incomplete_details.reason зберігається й показується.

Виявлення виводить /models зі шляху операції, наприклад https://api.example.com/v1/responses → https://api.example.com/v1/models. Без сумісної точки можна використовувати model_map. Виявлення обмежене змінними й даними користувача та зберігається для нього, не в спільному маніфесті. Воно запускається після активації, оновлення, зміни ключа або маршруту й скидання; звичайні параметри генерації не викликають мережі.

Також воно запускається самостійно для активного провайдера без каталогу або старшого за PLUGIN_MODEL_DISCOVERY_TTL_MS. Відступ не дає постійно опитувати недоступного провайдера, а строк зупиняє повільного; запізніле оновлення видно в наступному запиті. Остаточний URL перевіряється до читання ключа, зокрема з імпортованого маніфесту. Виявлення й можливості не переходять за перенаправленням. Налаштуйте кінцеві Chat, Work, список моделей, зображення, embedding, STT, TTS, клонування, аудіо й відео безпосередньо.

Точки можуть бути HTTP або HTTPS. HTTP передає ключі, промпти, результати й вміст без шифрування, тому використовуйте лише для власного шлюзу в довіреній мережі; віддавайте перевагу HTTPS/TLS. Запити виходять із сервера. У контейнері використовуйте адресу служби, як http://ai-gateway:8080/v1, а localhost означає сам контейнер Libre. Маршрути можливостей визначають точки й дані для автентифікованого користувача. Неавтентифікованого однокористувацького режиму немає.

Кінцеві точки окремих можливостей

Перевизначення Chat ізольовано від зображень, embedding, STT, TTS, аудіо й відео. Багатофункціональний плагін може виставити image_endpoint, embedding_endpoint, stt_endpoint, tts_endpoint або змінну з config.endpoint_variable. Клонування так само використовує config.voice_clone_endpoint_variable. Порожнє поле бере точку можливості з плагіна; загальний Chat endpoint ніколи не є перевизначенням можливості.

GitHub Models успадковує models.github.ai/inference/chat/completions, якщо поле порожнє. Hugging Face використовує маршрути hf-inference/models/{model} і специфічні дані для embedding, зображень і TTS, а не кінцеву точку Chat.

Перевизначення кінцевої точки

endpoint — повний URL запиту зі шляхом операції, наприклад https://provider.example/v1/chat/completions, а не лише https://provider.example. Старі конфігурації можуть називати його api_url; непорожній endpoint завжди має пріоритет.

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

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

Запити виходять із сервера. У контейнері localhost — сам контейнер, не хост або інша служба. Використовуйте ім’я служби шлюзу чи host.docker.internal, якщо середовище його надає.

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

У Налаштування → Плагіни є область Підключення провайдерів. Знайдіть і виберіть провайдера, щоб побачити активність і каталог. Конфігурація лишається згорнутою до Налаштувати, приховуючи типові точки, дані та розширені параметри.

Для chat/completion Оновити моделі запускає виявлення та перезавантажує каталог плагіна й Chat. Каталог лише для читання: рядки походять із ID користувача й карт можливостей визначення. Етикетки вказують маршрут, але не є перевіркою стану. Резервні ID додавайте в JSON model_map, не в рядок виявлення.

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

• URL із /models використовується як є;
• /chat/completions, /completions, /responses, /embeddings, /messages замінюються на /models;
• інакше /models додається.

Плагін може виставити повний models_endpoint, що має пріоритет, проходить ту саму політику й не переходить за перенаправленням. Збереження або скидання endpoint, api_url, models_endpoint, base_url, api_path, api_mode очищає та оновлює каталог користувача.

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

Очікується сумісна з OpenAI відповідь з ID у масиві data. Активація чекає спробу, успіх зберігається per користувача й не змінює спільний JSON. Якщо точки немає, провайдер недоступний або форма інша, звичайна активація зберігає попередній результат. Навмисна зміна підключення спочатку очищає застарілий каталог і повертається до model_map, якщо нове виявлення не вдалося.

Стан плагіна, Work, каталоги й маршрути можливостей використовують той самий контекст користувача та межу даних.

Точний вибір провайдера в Chat

ID моделей не унікальні. Ollama й кілька плагінів можуть мати example-model. Chat зберігає сирий ID та необов’язкову ідентичність:

• providerType: "ollama" — локальний або налаштований Ollama;
• providerType: "plugin" із providerId — точний плагін.

Кваліфіковані URL-кодовані значення використовуються лише як безпечні ключі селектора. Провайдер отримує сирий ID. Дублікати лишаються окремими, а повторне відкриття відновлює точний вибір.

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

Старі сеанси можуть мати providerType і providerId порожніми або null. Для сумісності вони лишають стару маршрутизацію за ім’ям, бо провайдера не можна надійно відновити. Селектор показує «провайдера не записано». Новий конкретний вибір записує точну ідентичність. Нові персони зберігають UI-ідентичність persona:<id> і вважаються Ollama.

Налаштування провайдера та успадкування

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

Для адміністраторів перевизначення підключення йдуть першими. Вибірка й спеціальні засоби — під також закритими Розширеними параметрами. Успадковані значення показуються порожніми полями з підказкою, а не копіюються в обліковий запис лише через відкриття панелі.

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

Для власної точки адміністратор лишає поле порожнім, щоб успадкувати вбудований URL, або вводить повний сумісний URL.

Плагіни в Work

Work використовує активні completion і chat разом із Ollama та Ollama Cloud. Запуск приймається, лише якщо:

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

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

Виклики адаптуються до форматів OpenAI, Anthropic і Gemini. Модель повинна підтримувати інструменти; відмова або несумісна відповідь завершує запуск без резервного провайдера.

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

Векторні подання

Плагіни embedding з’являються в налаштуваннях документів. Libre також виявляє ймовірні моделі Ollama: nomic-embed-text, bge, e5, gte та подібні. Якщо нічого не знайдено, локальним кандидатом стає nomic-embed-text.

Нотатки розробнику плагіна

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

Додаючи провайдера:

1. Додайте визначення.
2. Задайте ключ або поля користувача.
3. Реалізуйте виявлення, якщо є список моделей.
4. Додайте відображення запитів для чату, embedding, зображень, TTS або STT.
5. Перевірте відсутній і неправильний ключ та помилки провайдера.

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

• Змінні середовища
• Робота з моделями
• Work: ізольовані робочі області
• Kimi Code
• MLX LM на Apple Silicon