OpenWebUI API: чат с любой веб-страницей на ваших моделях

Если вы пользуетесь OpenWebUI, самое сложное уже позади. Модели настроены, ключи собраны в одном месте: возможно, это Ollama на домашнем сервере, пара облачных провайдеров и несколько собственных workspace-моделей, которые вы довели до ума.

Чего OpenWebUI не умеет, так это работать внутри страниц, которые вы просматриваете. Чтобы спросить модель о статье, PDF или странице документации, которую вы читаете, текст всё равно приходится копировать и вставлять в другую вкладку.

Здесь и пригодится SurfMind. OpenWebUI — это не только чат-интерфейс. Через OpenWebUI API он работает ещё и как API-сервер, поэтому SurfMind может использовать его как бэкенд. Модели вы по-прежнему настраиваете в OpenWebUI, а SurfMind становится для них интерфейсом в браузере.

В этом руководстве разберём, что такое OpenWebUI API, как он связан с SurfMind, какие именно URL вставлять и как исправить ошибки, с которыми люди сталкиваются на практике.

OpenWebUI и SurfMind: похожи внешне, но решают разные задачи

На первый взгляд это конкуренты. Оба — интерфейсы для ИИ, оба подключаются ко множеству LLM-провайдеров, и в обоих можно общаться с моделями. Но предназначены они для разных задач:

OpenWebUI — это ИИ-пространство на вашем собственном сервере. SurfMind — это ИИ внутри браузера, которым вы уже пользуетесь. Важнее всего строка, выделенная жирным. Раз OpenWebUI умеет отдавать ваши модели через API, эти два инструмента отлично дополняют друг друга.

Зачем подключать OpenWebUI к SurfMind?

Представьте типичную конфигурацию. У вас есть OpenWebUI на домашнем сервере или небольшом VPS, а за ним:

• Llama, Qwen или Gemma, запущенные локально через Ollama
• модели GPT или Claude через облачный API-ключ
• модель, которую vLLM раздаёт с вашей собственной видеокарты
• несколько workspace-моделей, созданных в OpenWebUI, у каждой свой системный промпт и настройки

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

Можно, конечно, заново добавить каждого провайдера в SurfMind по одному: сначала Ollama, потом ключ OpenAI, потом эндпоинт vLLM. Это утомительно, ключи начинают дублироваться, а созданные вами workspace-модели всё равно не переедут.

А можно добавить одно подключение: SurfMind → OpenWebUI. Все модели, которые видит OpenWebUI, появятся в селекторе моделей SurfMind. Модели, пользователи и права доступа остаются в OpenWebUI, где вы ими и так управляете, а SurfMind позволяет пользоваться ими прямо в браузере.

Это ещё и удобный способ поделиться конфигурацией. Если команда работает с одним экземпляром OpenWebUI, каждый может создать свой API-ключ и пользоваться моделями команды прямо из браузера. Права у всех будут те же, что и в OpenWebUI, а ключи провайдеров никому раздавать не придётся.

Шаг 1: создайте API-ключ OpenWebUI

По умолчанию API-ключи отключены, поэтому в первый раз на это уйдёт минута.

Если вы администратор, включите API-ключи:

1. Войдите в OpenWebUI под учётной записью администратора.
2. Перейдите в Settings → Admin → Authentication.
3. Включите переключатель API Keys и нажмите Save.

Если вы не администратор, попросите своего администратора выдать вам разрешение API Keys. Оно настраивается в Admin Panel → Users → Groups: либо в Default Permissions для всех, либо для конкретной группы.

Затем сгенерируйте ключ:

1. Нажмите на значок профиля в левом нижнем углу.
2. Откройте Settings → Account.
3. В разделе API keys нажмите Show рядом с Secrets. По умолчанию раздел свёрнут, так что если там пусто — это нормально.
4. Нажмите Create new secret key и скопируйте ключ. Он начинается с sk-.

Несколько важных моментов из документации OpenWebUI по API-ключам:

• Один ключ на учётную запись. Новый ключ заменяет старый, и старый сразу перестаёт работать. Если ваш ключ уже использует другой инструмент, то после создания нового ключа для SurfMind тот инструмент потеряет доступ. Чтобы этого избежать, заведите для SurfMind отдельную учётную запись без прав администратора.
• Ключ действует от вашего имени. Он видит те же модели и имеет те же права, что и учётная запись, которая его создала.
• Не используйте JWT-токен, который администраторы видят в той же панели. Это токен вашей браузерной сессии, и у него истекает срок действия.

Шаг 2: добавьте OpenWebUI в SurfMind

В SurfMind нажмите на название модели внизу панели, затем Show all → Custom → Add Custom Models. Выберите универсальную предустановку OpenAI-compatible и заполните поля:

Если OpenWebUI работает на том же компьютере, что и браузер, хост обычно http://localhost:3000 (типичный проброс порта в Docker) или http://localhost:8080 (установка через pip или без контейнера):

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models

Сохраните, выберите одну из своих моделей OpenWebUI в списке, откройте любую статью и попросите SurfMind её пересказать.

Две ошибки с путём, которых стоит избегать. Вставляйте полный эндпоинт, оканчивающийся на /api/chat/completions, а не просто хост или /api. Поле API URL в SurfMind не дописывает путь за вас. И нигде не добавляйте /v1: ни /api/v1/chat/completions, ни /v1/chat/completions не являются эндпоинтом чата OpenWebUI.

Решение проблем: «модели загружаются, а чат не работает»

Это самая частая жалоба от пользователей OpenWebUI, поэтому ей отведён отдельный раздел. Если модели появляются в выпадающем списке, значит, хост, ключ и сетевой путь в порядке. Сбой происходит именно в запросе к чату. Проверьте пункты ниже по порядку.

Сначала проверьте без SurfMind. Быстрый curl из терминала покажет, где проблема — в OpenWebUI или в настройках SurfMind. Подставьте свой хост, ключ и id модели:

curl -X POST https://openwebui.example.com/api/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:latest", "messages": [{"role": "user", "content": "Say hi"}]}'

Указывайте id модели в точности так, как он отображается в списке моделей SurfMind (или в ответе GET /api/models). Если запрос проходит, перепроверьте поля в SurfMind. Если нет, полученная ошибка укажет на одну из причин ниже.

1. Неверный путь к чату. Models URL и API URL — это разные поля, поэтому одно может быть верным, а другое нет. Убедитесь, что API URL оканчивается ровно на /api/chat/completions: без /v1, без завершающего слеша и без опечаток.

2. Чат блокируют ограничения эндпоинтов. Администраторы могут включить API Key Endpoint Restrictions — список маршрутов, к которым разрешено обращаться с API-ключами. Если в нём есть /api/models, но нет /api/chat/completions, возникнет именно такая проблема, обычно в виде 403. Попросите администратора добавить /api/chat/completions.

3. Настройка модели принудительно задаёт режим стриминга. В OpenWebUI есть параметр Stream Chat Response: он задаётся для каждой модели в расширенных параметрах или как значение по умолчанию в Settings → Admin → Models. Согласно документации OpenWebUI, этот параметр определяет, будет ли ответ передаваться потоком, независимо от того, что запросил клиент. Если модель принудительно переведена в режим, которого клиент не ждёт, ответ может прийти в формате, который клиент не сумеет прочитать. Если чат не работает только с некоторыми моделями, проверьте у них эту настройку и верните её в Default.

4. Обратный прокси «съедает» заголовок Authorization. Если OpenWebUI стоит за шлюзом, который использует Authorization для собственного входа (basic auth, SSO, API-шлюз), ваш ключ до OpenWebUI просто не доходит. OpenWebUI принимает ключ и в отдельном заголовке — по умолчанию x-api-key. В этом случае выберите x-api-key в поле API Key Header в SurfMind. Если администратор переименовал заголовок через CUSTOM_API_KEY_HEADER, прокси должен пропускать именно его.

5. Не совпадает id модели. Выбирайте модель из выпадающего списка, а не вводите вручную. Id моделей Ollama в OpenWebUI включают тег (llama3.2:latest), а у workspace-моделей используется id, который вы им задали, а не отображаемое имя.

6. Сбой у провайдера за OpenWebUI. Когда вышестоящий провайдер отклоняет запрос, OpenWebUI передаёт его код состояния дальше. 429 — это лимит запросов провайдера, а не OpenWebUI или SurfMind. Попробуйте ту же модель в чате самого OpenWebUI. Если и там не работает, проблема на стороне провайдера.

Другие ошибки вкратце

Общие правила для любого собственного эндпоинта (порты, http или https, базовый URL или полный эндпоинт) собраны в нашем руководстве по подключению собственного ИИ.

Что выбрать: OpenWebUI, SurfMind или оба?

Выбирать одно из двух не обязательно.

• Только OpenWebUI отлично подойдёт, если вы в основном ведёте с ИИ долгие разговоры в отдельной вкладке: общаетесь с документами из баз знаний, запускаете пайплайны, управляете моделями для команды.
• Только SurfMind отлично подойдёт, если работа с ИИ у вас чаще всего начинается с того, что открыто на экране, и вас устраивает подключать провайдеров или локальный раннер вроде Ollama напрямую.
• Использовать оба сразу имеет смысл, если вы уже вложились в настройку OpenWebUI и хотите пользоваться ею на любой странице, не настраивая всё дважды.

Разделение простое: OpenWebUI управляет вашими моделями, а SurfMind позволяет использовать их в браузере.

Часто задаваемые вопросы

Есть ли у OpenWebUI API? Да. OpenWebUI API — это REST API с аутентификацией через Bearer-токены. Большинству инструментов нужны два эндпоинта: GET /api/models для списка моделей и POST /api/chat/completions для чата, который принимает запросы в формате OpenAI.

Совместим ли OpenWebUI API с OpenAI? Формат запросов и ответов — да. А вот пути нестандартные: OpenWebUI использует /api/chat/completions вместо /v1/chat/completions. Им может пользоваться любой клиент, в котором можно указать полный URL эндпоинта, например SurfMind.

Где найти API-ключ OpenWebUI? Перейдите в Settings → Account → API keys, нажмите Show, затем Create new secret key. Если раздела нет, администратор должен включить API Keys в Settings → Admin → Authentication и выдать вашей учётной записи разрешение API Keys.

Можно ли использовать workspace-модели OpenWebUI в SurfMind? Да. /api/models возвращает workspace-модели наравне с остальными. При обращении к ним OpenWebUI применяет их сохранённые настройки.

Отправляет ли подключение OpenWebUI мои данные на серверы SurfMind? С собственным эндпоинтом SurfMind отправляет запросы на указанный вами URL — в данном случае на ваш сервер OpenWebUI. Сервер OpenWebUI затем передаёт их выбранной модели. Если модель работает локально, содержимое страницы остаётся на оборудовании, которое вы контролируете.

Это бесплатно? Да. Собственные эндпоинты в SurfMind ничего не стоят, и мы не ограничиваем их использование. Вы платите только своим провайдерам по их тарифам, а за локальные модели — вообще ничего.

Всё ещё не работает?

Если тест с curl проходит, а SurfMind по-прежнему не может общаться с вашими моделями OpenWebUI, напишите нам на wave@surfmind.ai. Укажите ваш API URL (без ключа), HTTP-код ответа и то, со всеми ли моделями возникает сбой или только с некоторыми. Self-hosted-конфигурации бывают очень разными, и такие отчёты помогают нам сделать так, чтобы SurfMind работал с ними без проблем.

Получить SurfMind →