Open WebUI · Справочник интегратора

Каталог материалов

Проверенные статьи, документация и обсуждения. Русскоязычные кейсы закрывают RAG, MCP-агентов и production в Kubernetes; по Pipe/Filter Functions, RBAC, SSO и масштабированию единственный полный источник — официальная документация (EN). Фильтруйте по темам или ищите по названию.

Hermes-агент ↔ Open WebUI

Hermes — внешний оркестратор (Telegram, GPT-5.5), поэтому его интеграция с OWUI строится не через UI, а через API-слой и общие инструменты. Четыре рабочих паттерна — от простого шлюза до общего MCP-моста. Опорные документы: API Endpoints и Backend-Controlled API Flow.

P1OWUI как inference-шлюз: Hermes спрашивает — OWUI отвечает с RAG

Самый быстрый паттерн: Hermes дергает OpenAI-совместимый эндпоинт OWUI и получает ответ модели, обогащённый knowledge-коллекцией. Вся маршрутизация моделей (vLLM, внешние API), RBAC и контроль доступа остаются на стороне OWUI. Ключ — из Settings → Account → API Keys (нужен включённый ENABLE_API_KEYS).

hermes → owui · chat completions + knowledge collection

# RAG-ответ из коллекции OWUI прямо в Telegram-диалог Hermes
curl -X POST https://owui.example.com/api/chat/completions \
  -H "Authorization: Bearer $OWUI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-35b-a3b",
    "messages": [{"role": "user", "content": "Требования 44-ФЗ к обеспечению заявки?"}],
    "files": [{"type": "collection", "id": "knowledge-collection-id"}]
  }'

Грабли: в files передаётся именно ID коллекции, не имя — иначе ответы будут «без источников» (подтверждено в discussion #9870). И следите за контекстом модели: retrieved-чанки должны помещаться целиком.

P2Управление знаниями по API: Hermes пополняет базу OWUI

Оркестратор может сам загружать документы (протоколы, регламенты, выгрузки из CRM) в knowledge-коллекции. Порядок: POST /api/v1/files/ (multipart) → дождаться окончания обработки по статус-эндпоинту → POST /api/v1/knowledge/{id}/file/add. Индексация асинхронная — добавление файла в коллекцию до завершения парсинга даст пустые эмбеддинги.

P3Backend-controlled flow: диалоги Hermes видны в UI OWUI

Если нужно, чтобы разговоры, инициированные из Telegram, появлялись в веб-интерфейсе OWUI (для аудита или продолжения в браузере), используйте 6-шаговый паттерн из Backend-Controlled API Flow: создать чат с плейсхолдером ассистента (структура history.messages с parentId/childrenIds) → триггернуть completion с chat_id → дождаться ответа → перечитать чат. Верифицировано на v0.6.15; для outlet-фильтров у чистых API-клиентов надёжен второй вызов POST /api/chat/completed.

P4MCP-мост: один инструмент для Hermes и OWUI

Ваше решение обернуть гибридный RAG-движок в MCP-интерфейс здесь играет на руку: OWUI нативно поддерживает MCP с v0.6.31, а Hermes подключает тот же сервер как tool. Один MCP-сервер = единая точка правды для поиска по регуляторным документам, без дублирования логики BM25+pgvector+reranker в двух местах.

Нативное подключение: docs → MCP; для stdio-серверов — прокси mcpo (MCP → OpenAPI).
Вызов MCP-инструментов сервером прямо через API: в теле /api/chat/completions передаются tool-ID вида server:mcp:<server-id>.
Русскоязычный разбор агентного поведения поверх этой связки — цикл «MCP в Open WebUI» (в каталоге, теги mcp).

P5Обратный паттерн: OWUI — фронт, Hermes — «LLM» за OpenAI-совместимым прокси

Зеркало P1: Hermes выставляет собственный /v1/chat/completions (+ /v1/models) и добавляется в OWUI как обычное подключение (Admin → Connections → OpenAI → Add Connection). Пользователь выбирает «модель» hermes-agent в селекторе и получает весь оркестрационный цикл агента — делегирование, retry-caps, quality-control — в привычном чат-интерфейсе с историей, RBAC и мультипользовательским доступом OWUI. Требования к прокси — стандартные для OpenAI-совместимого провайдера.

hermes-proxy · минимальный OpenAI-совместимый фасад (FastAPI)

# Hermes «прикидывается LLM»: два эндпоинта — и он появляется в селекторе OWUI from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
import json, time

app = FastAPI()

@app.get("/v1/models")
def models():  # OWUI дергает его при верификации подключения return {"object": "list", "data": [{"id": "hermes-agent", "object": "model", "owned_by": "hermes"}]}

@app.post("/v1/chat/completions")
async def chat(req: Request):
    body = await req.json()
    # служебные запросы OWUI (заголовки, теги) не должны будить оркестратор: if body.get("metadata", {}).get("task"):
        return _plain("Чат с Hermes")          # короткий ответ без запуска агента async def sse():                          # стриминг прогресса оркестрации в UI async for delta in hermes.run(body["messages"]):
            chunk = {"id": "hermes-1", "object": "chat.completion.chunk",
                     "model": "hermes-agent", "created": int(time.time()),
                     "choices": [{"index": 0, "delta": {"content": delta}, "finish_reason": None}]}
            yield f"data: {json.dumps(chunk, ensure_ascii=False)}\n\n" yield "data: [DONE]\n\n" return StreamingResponse(sse(), media_type="text/event-stream")

Грабли обратного паттерна:

Фоновые задачи OWUI. Генерация заголовков, тегов и follow-up-подсказок — это отдельные completion-запросы. Без отсечки каждый чат будет запускать оркестрацию трижды. Отсекайте по метаданным (как в примере) и/или назначьте лёгкую модель для задач в Admin → Settings → Interface → Task Model.
Верификация подключения. Если /v1/models не реализован, подключение покажет ошибку — это не блокер: chat completions работать будут, просто внесите hermes-agent вручную в Model IDs (Filter).
Таймауты. Оркестрационный цикл с retry и QC-петлями живёт дольше обычного inference — отдавайте SSE-чанки по ходу (прогресс шагов агента), иначе OWUI и реверс-прокси оборвут соединение. Проверьте лимиты Traefik.
Состояние. OWUI шлёт полную историю сообщений в каждом запросе — Hermes не должен полагаться на свою Telegram-сессию; для сквозной привязки используйте session_id/chat_id из тела запроса.
Docker-сеть. Если прокси на хосте, а OWUI в контейнере — host.docker.internal вместо localhost.
Альтернатива без отдельного сервиса: тот же результат даёт Pipe Function внутри OWUI, которая ходит в Hermes по его нативному API — «модель» появляется в селекторе без прокси, но код живёт в OWUI и переиспользовать эндпоинт извне (например, из Codex) уже не выйдет.

Codex CLI ↔ Open WebUI

Codex CLI умеет работать с любым провайдером, говорящим на Chat Completions — значит, ваш OWUI (а за ним vLLM с Qwen/Gemma) может быть бэкендом для кодинг-агента. Официальная точка входа: developers.openai.com/codex/cli. Рабочая конфигурация подтверждена в discussion #15582.

~/.codex/config.toml · OWUI как model_provider

model = "qwen3.6-35b-a3b" # ID модели, как она видна в OWUI model_provider = "openwebui" [model_providers.openwebui] name = "Open WebUI" base_url = "https://owui.example.com/api" # НЕ голый /v1 — см. грабли ниже env_key = "OPENWEBUI_API_KEY" # ключ из Settings → Account wire_api = "chat" # Chat Completions, не Responses API

Симптом	Причина и решение
405 Method Not Allowed	Codex бьёт в путь, которого нет у OWUI. Chat-эндпоинты OWUI: `/api/chat/completions` и compat-слой `/v1/chat/completions`; при `--oss`-флаге Codex ждёт Ollama-совместимый API — с OWUI это не работает (codex #2556). Задавайте провайдера через config.toml, не через `--oss`.
401 при валидном ключе	Проверить `ENABLE_API_KEYS=true`, права роли на API-доступ и ограничения ключа по эндпоинтам (разбор — discussion #22964).
Модель «не найдена»	Codex запрашивает `/models`: ID должен совпадать с тем, что возвращает `GET /api/models` OWUI (включая суффиксы кастомных «моделей»-пресетов).
Хочется входа по аккаунту ChatGPT	Провайдер-специфичный OAuth в core OWUI не принят (не стандарт) — статус обсуждения: #25122. Для Codex-подписки используйте сам Codex CLI напрямую, OWUI подключайте по API-ключу.

Зачем это в вашем стеке: Codex через OWUI получает единый журнал использования, RBAC и лимиты на общем шлюзе — а Hermes может делегировать кодовые задачи тому же провайдеру, что и люди. Тяжёлые фоновые задачи стоит смотреть в сторону Codex cloud (запуск из GitHub PR / Slack), но это уже вне self-hosted контура.

RAG в Open WebUI под русский язык

Дефолтный эмбеддер OWUI (all-MiniLM-L6-v2, 256 токенов, англоцентричный корпус) для русских регуляторных документов непригоден. Консенсус источников — мультиязычный эмбеддер + гибрид + reranker. Опорные страницы: docs → RAG и RAG troubleshooting.

Параметр	Рекомендация	Почему
Embedding	`BAAI/bge-m3` или `deepvk/USER-bge-m3`	1024-мерный dense, контекст до 8192 токенов, 100+ языков; USER-вариант дообучен под русский. Альтернатива — `multilingual-e5-large` (контекст всего 512).
Reranker	`BAAI/bge-reranker-v2-m3` + Hybrid Search	Прямая рекомендация авторов bge-m3: hybrid retrieval → re-ranking.
Chunk / Overlap	512–1024 токенов / 50–100	Кейс Bitrix: chunk 1280 + подчанки 512 + overlap 50% подняли Recall@10 c 0.589 до 0.655 на гибриде.
Top K	initial 20–50 → после reranker 5–10	Широкая выборка на retrieval, жёсткая фильтрация на reranking.
Парсинг документов	Apache Tika (`apache/tika:latest-full`, :9998)	Admin → Documents → Content Extraction = Tika; для сложных PDF/таблиц — Docling (интеграция: issue #10332).
Контекст модели	≥ 8192 (у Ollama дефолт 2048!)	Иначе retrieved-чанки молча обрезаются.

Обязательно: после любой смены embedding-модели — полная переиндексация базы знаний, старые векторы несовместимы. И помните вашу же архитектурную развилку: для сложного гибрида (BM25 + pgvector + Natasha + стоп-словари) встроенный RAG OWUI может остаться «вторым контуром», а основной движок — жить за MCP (паттерн P4 выше).

Production-чеклист

Выжимка из docs → Scaling, разделов по RBAC / SSO и русскоязычного кейса Флант (Kubernetes + Helm, в каталоге).

PostgreSQL вместо SQLite до накопления боевых данных — автоматической миграции нет; пул: DATABASE_POOL_SIZE=15 + overflow.

Общий WEBUI_SECRET_KEY на все реплики — иначе login-loop и 401 при балансировке.

Redis для WebSocket и сессий при >1 реплики; файлы — в S3-совместимое хранилище.

Никакого SQLite на NFS/CephFS: fsync 50–500 мс на commit против ~100 мкс на локальном SSD.

SSO через Keycloak/OIDC: ENABLE_OAUTH_SIGNUP, роли из realm_access.roles, группы из IdP-claims.

RBAC-модель аддитивна: права = роль ∪ все группы; модели и коллекции приватны по умолчанию.

Helm-chart open-webui/open-webui: Postgres/Redis/Tika как subchart-зависимости; миграции — на одном воркере.

Pipelines = legacy. Новую кастомную логику писать как Pipe/Filter Functions, существующие пайплайны — планировать к миграции.

Open WebUI как узел оркестрации: Hermes, Codex и всё, что вокруг

Каталог материалов

Hermes-агент ↔ Open WebUI

P1OWUI как inference-шлюз: Hermes спрашивает — OWUI отвечает с RAG

P2Управление знаниями по API: Hermes пополняет базу OWUI

P3Backend-controlled flow: диалоги Hermes видны в UI OWUI

P4MCP-мост: один инструмент для Hermes и OWUI

P5Обратный паттерн: OWUI — фронт, Hermes — «LLM» за OpenAI-совместимым прокси

Codex CLI ↔ Open WebUI

RAG в Open WebUI под русский язык

Production-чеклист