Перейти к основному содержимому

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

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 описывает маршрутизацию и конфигурацию, но не преобразует чужой протокол.

Открытие подключений​

  1. Войдите, откройте Настройки > Плагины.
  2. Найдите слева.
  3. Выберите для состояния и каталога.
  4. Активируйте для аккаунта.
  5. Выберите Настроить только для учётных данных или переопределения подключения.

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

Определения являются общей конфигурацией инстанции, поэтому импортировать, устанавливать, обновлять и удалять их могут только администраторы. Каждый пользователь управляет собственной активацией, учётными данными и разрешёнными параметрами генерации.

Быстрое добавление​

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

Нужны отображаемое имя, полный URL дополнений чата и необязательный ключ. Libre выводит ID подключения, устанавливает определение, хранит ключ на сервере, активирует подключение и запрашивает список моделей. Обнаруженные модели заменяют временный каталог и появляются в селекторе.

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

Codex (вход ChatGPT)​

Codex (ChatGPT) не требует ключа API. После codex login от имени системного пользователя сервера он появляется у администраторов и предлагает через сессию ChatGPT модели GPT-6 Astra, GPT-6.1 Sol (gpt-6.1-sol), GPT-6.1 Terra (gpt-6.1-terra), GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, Terra, Luna, GPT-5.5 и GPT-5.3 Codex Spark в пределах доступа вошедшей учётной записи. Токены читаются из auth.json, обновляются тем же клиентом OAuth и записываются обратно; значения не журналируются.

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

Amazon Bedrock​

Встроенный провайдер Amazon Bedrock принимает API-ключ Bedrock, краткосрочный или долгосрочный, из консоли Amazon Bedrock. Сохраните его в настройках провайдера или задайте AWS_BEARER_TOKEN_BEDROCK на сервере. AWS SDK, пара ключей доступа и подпись IAM не нужны.

Libre WebUI обращается к конечной точке bedrock-mantle.<region>.api.aws выбранного Region и перечисляет все модели, которые аккаунт может там вызывать, так же как OpenRouter перечисляет свой каталог. Модели, которые аккаунт пока не может использовать, например из-за режима хранения данных, в список не попадают. Выберите Region в настройке Region. Она лишь переключает между хостами Bedrock, поэтому ключ никогда не будет отправлен куда-либо ещё, а её изменение сохраняет сохранённый ключ.

Модели Claude (anthropic.*) работают через Anthropic Messages API Bedrock, поэтому рассуждение, инструменты и лимиты токенов ведут себя так же, как у провайдера Anthropic. Все остальные модели используют Chat Completions. Bedrock предоставляет некоторые семейства через второй маршрут Chat Completions; Libre WebUI пробует этот маршрут, когда Bedrock сообщает, что модель находится там, и запоминает это. Чат, Work и движок Strands могут использовать все эти модели, а использование отображается в аналитике под провайдером.

В коммерческих регионах AWS предоставляет Claude Haiku 5.5 и Claude Sonnet 5.5 только через bedrock-runtime, с межрегиональными профилями инференса, поэтому список моделей Mantle никогда их не содержит. Каталог добавляет global.anthropic.claude-haiku-5-5 и global.anthropic.claude-sonnet-5-5, а любой ID профиля инференса Claude (global., us., eu., au. или jp.) отправляется с тем же ключом API на bedrock-runtime.<region>.amazonaws.com/anthropic/v1/messages выбранного региона. Ключ по-прежнему уходит только на два хоста Bedrock этого региона. Вашему аккаунту по-прежнему нужен доступ к модели в Amazon Bedrock.

Встроенный провайдер Modal обращается к общему маршрутизатору инференса Modal, https://inference.us-west.modal.direct/v1, через Chat Completions. Он работает с Shared Endpoints в вашем рабочем пространстве Modal, которые Modal тарифицирует за токены.

  1. Создайте Shared Endpoint для каждой нужной модели на вкладке Endpoints в панели Modal или командой modal endpoint create --shared --model moonshotai/Kimi-K3.
  2. Создайте прокси-токен в настройках панели Modal или командой modal workspace proxy-tokens create.
  3. Соедините ID токена и секрет точкой, wk-<id>.ws-<secret>, и сохраните результат как API-ключ провайдера или задайте MODAL_PROXY_TOKEN на сервере.

Затем Libre WebUI перечисляет все конечные точки, доступные токену, из /v1/models маршрутизатора, с контекстным окном и признаком того, рассуждает ли модель. Маршрутизатор знает модель только по имени хоста её конечной точки, например acme--ep-muse-spark-open-816b-a42b-server.us-west.modal.direct, поэтому именно этот ID модели отправляет Libre WebUI; селектор моделей показывает её по имени конечной точки, здесь "Muse Spark Open 816B A42B". Модель без конечной точки в вашем рабочем пространстве отвечает unknown inference model.

Каждый запрос одного разговора несёт один и тот же Modal-Routing-Affinity-Key, выведенный из модели и первого сообщения разговора, поэтому Modal направляет его в контейнер, у которого промпт разговора уже есть в кэше. Work делает то же самое для каждого шага цикла агента в запуске. Кэшированные входные токены стоят долю обычной цены. Когда сжатие контекста переписывает историю, ключ меняется, как рекомендует Modal.

Чтобы обращаться к одной конечной точке напрямую, задайте в поле Полный URL конечной точки API провайдера её URL (modal endpoint info <name> показывает его как service_url) с добавлением /v1/chat/completions. Так достигается Dedicated Endpoint; там модель сохраняет своё имя из Hugging Face, например moonshotai/Kimi-K3, и так же встроенный список называет общие модели Modal, пока токен не сохранён. Shared Endpoints ограничивают число одновременных запросов на модель и сверх лимита отвечают 429.

OpenCode в Work может использовать тот же токен. Если на сервере задан MODAL_PROXY_TOKEN или вход в Modal сохранён через opencode auth login, модель modal/… работает в песочнице, а токен отправляется только на inference.us-west.modal.direct.

Baseten​

Встроенный провайдер Baseten обращается к Model APIs Baseten, https://inference.baseten.co/v1, через Chat Completions. Baseten размещает модели и тарифицирует их за токены, поэтому сначала ничего развёртывать не нужно.

  1. Создайте персональный API-ключ в панели Baseten в разделе Settings > API keys.
  2. Сохраните его как API-ключ провайдера или задайте BASETEN_API_KEY на сервере.

Затем Libre WebUI перечисляет каталог Model APIs из /v1/models, с контекстным окном каждой модели и признаком того, рассуждает ли она. Модели принятия решений Baseten (decision-models/…) отвечают только через System One API Baseten, поэтому они перечисляются как модели принятия решений, а не как модели чата; см. Модели принятия решений. Модели сохраняют слаги Baseten, например zai-org/GLM-5.3 или moonshotai/Kimi-K3; селектор показывает их как "GLM 5.3" от Z.ai и "Kimi K3" от Moonshot AI. Вариант Fast запускает те же веса на выделенных мощностях по собственной цене.

Большинство этих моделей рассуждают по умолчанию. Регулятор рассуждения в чате задаёт reasoning_effort Baseten: Низкий и Высокий отправляются как есть, среднее значение оставляет модели её собственную глубину по умолчанию, а Выключено отправляет none. Очень высокий отправляет high, потому что модели Baseten расходятся в том, какой уровень идёт выше него: одни принимают xhigh, другие только max, а третьи не принимают ни того, ни другого. Baseten документирует несколько исключений: Muse Spark Open и Beam рассуждают всегда, а GLM 5.3 с none всё равно слегка рассуждает. Предыдущие рассуждения отправляются обратно как reasoning_content, который Beam требует для каждого предыдущего ответа.

Каждый запрос одного разговора несёт один и тот же ключ x-session-affinity, выведенный из модели и первого сообщения разговора, поэтому Baseten направляет его в реплику, у которой промпт разговора уже есть в кэше. Work делает то же самое для каждого шага цикла агента в запуске. Когда сжатие контекста переписывает историю, ключ меняется.

Чтобы вместо этого обращаться к выделенному развёртыванию, задайте в поле Полный URL конечной точки API провайдера https://model-<model id>.api.baseten.co/environments/production/sync/v1/chat/completions. Тот же API-ключ работает и там.

OpenCode в Work может использовать тот же ключ. Если на сервере задан BASETEN_API_KEY или вход в Baseten сохранён через opencode auth login, модель baseten/… работает в песочнице, а ключ отправляется только на inference.baseten.co.

Встроенный или импортированный провайдер​

Есть OpenAI, Anthropic, Gemini, Groq, Mistral, DeepSeek, Meta, Modal, Baseten, Amazon Bedrock, 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/completionsmessages
responses/responsesinput

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

Режим меняет путь по умолчанию, но не протокол вышестоящего сервера. Выбирайте Responses только при совместимой форме запросов и событий.

Базовый URL или полная конечная точка​

Порядок:

  1. Нестандартный полный endpoint.
  2. base_url + api_path.
  3. Конечная точка из определения плагина.

Базовый 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
Служба Composehttp://ai-gateway:8080/v1
Контейнер → хостhttp://host.docker.internal:8081/v1
Доверенная LAN/Tailscalehttp://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 помогли определить процесс.

Связанная документация​