OWUI - Open WebUI

Архитектура OWUI 

OWUI - Open WebUI - это веб-интерфейс для работы с моделями искусственного интеллекта.

Документация по OWUI API находится здесь: https://docs.openwebui.com/reference/api-endpoints/

Введение

Open WebUI (OWUI) — это self‑hosted веб‑интерфейс для работы с большими языковыми моделями (LLM), спроектированный как гибкая, расширяемая и безопасная платформа. Его архитектура позволяет использовать разные модели (локальные и облачные), встраивать RAG‑конвейеры, подключать внешние инструменты и выстраивать сложные пайплайны обработки запросов без необходимости писать код. Ниже подробно разобрана архитектура системы, логика взаимодействия компонентов и принципы масштабирования.

---

Стек и уровни архитектуры

Архитектура OWUI строится по трёхуровневой схеме:

• Frontend (SvelteKit): отвечает за пользовательский интерфейс, чат, панель администратора, управление контекстом и файлами, а также за двустороннюю связь с бэкендом через WebSocket.
• Backend (Python + FastAPI): управляет маршрутизацией запросов, авторизацией, интеграциями с провайдерами моделей, RAG‑логикой, плагинами и оркестрацией пайплайнов.
• Хранилище и внешние сервисы: включают основную базу данных (SQLite по умолчанию, PostgreSQL в продакшене), векторные базы данных (ChromaDB, Qdrant, Milvus и др.), файловое хранилище и Redis (для сессий и координации WebSocket в кластере).

Такая модульная структура позволяет разворачивать систему как на одном сервере, так и в высокодоступной конфигурации с горизонтальным масштабированием.

---

Обработка пользовательского запроса: сквозной поток

Путь запроса в OWUI выглядит следующим образом:

1. Вход через фронтенд: пользователь отправляет сообщение в чате; фронтенд передаёт его через WebSocket или REST‑запрос.
2. Аутентификация и валидация: бэкенд проверяет права пользователя, принадлежность к рабочей области, лимиты и политики доступа.
3. Препроцессинг и плагины: применяются фильтры (Filters), Skills (наборы инструкций), а также логика Pipes (пайплайнов) для маршрутизации запроса.
4. Маршрутизация к модели: система выбирает целевую LLM на основе настроек чата, предпочтений пользователя, правил администратора и доступных ресурсов.
5. RAG (при необходимости): если включён RAG, запрос проходит через Embedding‑модель, выполняется поиск по векторной базе, затем Rerank‑модель улучшает выдачу, и только после этого формируется промпт для LLM.
6. Инференс модели: запрос отправляется провайдеру (Ollama, OpenAI‑совместимый API, vLLM и т. п.).
7. Постобработка: применяются дополнительные фильтры, инструменты (Tools), форматирование ответа.
8. Возврат результата: ответ стримится через WebSocket и отображается во фронтенде.

На каждом этапе возможна кастомизация через систему плагинов, что делает архитектуру универсальной для разных сценариев. 

---

Система расширений: Skills, Tools, Pipes, Filters

OWUI предоставляет набор механизмов расширения, которые можно комбинировать:

• Skills — переиспользуемые наборы инструкций в формате Markdown. Они не выполняют код, но задают правила поведения модели (стиль ответов, чеклисты, алгоритмы диагностики и т. д.).
• Tools — исполняемые функции (Python‑скрипты, HTTP‑запросы), которые модель может вызывать для получения внешних данных или выполнения действий.
• Pipes — пайплайны маршрутизации и обработки запросов. Позволяют направлять запросы к разным моделям или цепочкам действий в зависимости от условий.
• Filters — компоненты для пре‑ и постобработки сообщений: цензура, маскирование PII, форматирование, валидация и т. п.

Эти компоненты управляются через интерфейс администратора и могут быть привязаны к пользователям, чатам или моделям, что даёт тонкую настройку поведения системы.

Компонент	Где найти в интерфейсе	Как вызывать пользователю	Добавление	Описание
Pipes	Admin Panel → Functions → Pipes	Пользователь взаимодействует через интерфейс, вводит запрос. Пользователь не делает ничего специального.	1. Перейти в Admin Panel → Functions. 2. Нажать Create, задать название и короткое описание. 3. При необходимости указать параметры. 4. Сохранить. Теперь выбранный Pipe появляется в списке моделей и может быть выбран в чате.	Первое что бросается в глаза, так это предупреждение: "Pipelines are legacy, do not use for new deployments". Рекомендуют использовать Functions. Pipes — это функции, которые обрабатывают входные данные и выдают ответы. Приём запроса:  Pipelines интегрируются с любым клиентом, поддерживающим спецификации API OpenAI. Пользователь взаимодействует через интерфейс, вводит запрос. Обработка запроса: Обработка происходит внутри функции Pipe, которая может обращаться к локальным и/или облачным моделям. Pipe (FAT-01) перехватывает запрос, извлекает сообщение Возврат ответа: Ответ формируется через систему API OpenAI после обработки запроса пайплайном. После обработки данных Pipe генерирует ответ и возвращает его пользователю. Пошагово: Pipe перехватывает запрос, извлекает сообщение. - Проверяет настройки пользователя. - Отправляет запрос в n8n. - Pipe парсит ответ из n8n, возвращает пользователю. Структура класса Pipe в Python: class Pipe:     ├── class Valves:            # Глобальные настройки (один раз — админ)     ├── class UserValves:     # Персональные настройки (каждый пользователь)     ├── __init__()                  # Инициализация экземпляра     └── async pipe()            # Главный метод — точка входа # 1. Проверка типа запроса # 2. Извлечение данных # 3. Обработка # ... # 4. Возврат результата return "Результат"  Свернуть исходный код from pydantic import BaseModel, Field from typing import Optional, Callable, Awaitable   class Pipe:     # ── Глобальные настройки (задаёт админ) ──     class Valves(BaseModel):         setting_1: str = Field(default="", description="Описание")         setting_2: int = Field(default=60, description="Таймаут")       # ── Персональные настройки (задаёт пользователь) ──     class UserValves(BaseModel):         token: str = Field(default="", description="Личный токен")       # ── Инициализация ──     def __init__(self):         self.type = "pipe"            # тип модуля         self.id = "PIPE-ID"           # уникальный ID         self.name = "Название"        # имя в интерфейсе         self.valves = self.Valves()   # экземпляр настроек       # ── Главный метод ──     async def pipe(         self,         body: dict,         __user__: Optional[dict] = None,         __event_emitter__: Callable[[dict], Awaitable[None]] = None,         __event_call__: Callable[[dict], Awaitable[dict]] = None,     ) -> Optional[str]:         # 1. Проверка типа запроса         if not body.get("stream"):             return None           # 2. Извлечение данных         messages = body.get("messages", [])         user_message = messages[-1].get("content", "")           # 3. Обработка         # ...           # 4. Возврат результата         return "Результат"
Tools	Workspace → Tools	Пользователь пишет запрос. Модель сама решает, нужен ли Tool. Пользователь не делает ничего специального.	1. Перейти в Workspace → Tools. 2. Нажать Create, задать название и короткое описание. Указать параметры, и логику. 3. Сохраните. 4. В чате выберите модель, включите Tool Calling (выбрать из списка) и задать запрос. Модель сама решит, что нужно вызвать ваш инструмент, и вернет ответ.	Что такое Tool Call, как модель решает вызвать Tool, структура описания функции Инструменты — это различные способы расширить возможности больших языковых моделей, выйдя за рамки простого генерирования текста. При их использовании можно: искать информацию в интернете, собирать данные, генерировать изображения, воспроизводить речь с помощью искусственного интеллекта и многое другое. Инструменты выполняют произвольный код Python на сервере. Tool Call — это механизм, позволяющий LLM использовать различные инструменты для выполнения задач, вызывать внешние или внутренние функции/инструменты во время генерации ответа. Существует два режима вызова инструментов (Tool Calling Modes): Native (Agentic) Mode (режим агента) — режим по умолчанию с версии v0.10.0, использует встроенные возможности модели для работы с инструментами. Позволяет модели самостоятельно решать, какие инструменты использовать в каждом конкретном случае. Legacy Mode (устаревший режим) — больше не поддерживается, управлял выбором инструментов путём внедрения длинного шаблона промпта, чтобы модель выводила запрос на инструмент в определённом формате.  Модель принимает решение использовать ли инструмент и какой на основе двух вещей: явной инструкции в системном промпте и своего обучения. System Prompt сообщает модели, какие инструменты у неё есть и для чего они предназначены. Например: название инструмента, его описание, в каких случаях его применять. Обученность означает, что модель прошла специальное обучение и научилась распознавать ситуации, когда внешний инструмент полезнее, чем её собственные знания. Механизм прост: получив запрос, модель сначала спрашивает себя — могу ли я ответить сама? Если ответ положительный, она отвечает текстом. Если отрицательный — она ищет подходящий инструмент, описанный в системном промпте, и вызывает его. Итого: модель решает вызвать Tool, когда понимает, что её собственных знаний недостаточно и в системном промпте есть инструмент, подходящий для этого запроса. Структура описания Tool: Название инструмента: что делает Описание: кратко для чего нужен Параметры:   - параметр_1: что это   - параметр_2: что это Когда вызывать: ситуации использования Описания структурированы в виде таблиц, где для каждого инструмента перечислены его параметры и формат вывода. Также в описаниях могут быть указаны условия использования инструмента, например: требования к настройкам (включены ли определённые функции в админ-панели); необходимость прав доступа у пользователя;  зависимости от других настроек (например, прикреплённых знаний или заметок).
Skills	Workspace → Skills	Skills не нужно вызывать вручную. Они работают в фоне и активируются автоматически.	1. Перейти в Workspace → Skills → Нажать Create. 2. Задать название и написать инструкцию в формате Markdown. 3. Сохранить. 4.  В чате выберите модель, включите Skills (выбрать из списка) и задать запрос. Skills активируются автоматически. Можно добавить в чате через знак "$", можно задать модели при её создании.	Навыки — это многократно используемые наборы инструкций на основе Markdown, которые вы прикрепляете к моделям или вызываете в чате. В отличие от инструментов (исполняемых скриптов Python), навыки представляют собой текстовые инструкции: рекомендации по проверке кода, правила написания, руководства по устранению неполадок, рабочие процессы анализа данных. Модель считывает их и следует им. Skills и Tools отличаются по своему назначению и форме.  Skills: представляют собой наборы инструкций в формате Markdown; не содержат исполняемого кода, API-вызовов или системных команд; могут быть привязаны к моделям или активированы в чате по мере необходимости; подходят для документирования правил (например, чеклистов для проверки кода, руководств по стилю написания текстов, алгоритмов устранения неполадок); позволяют модели следовать определённым инструкциям и подходам при выполнении задач. Tools: это исполняемые скрипты (например, на Python); предназначены для выполнения действий, требующих вычислений, обращений к API или системного доступа; предоставляют функциональные возможности, которые Skills лишь описывают. Tool нужен, когда модели требуется получить данные из внешнего источника. Например: запросить информацию из Confluence, выполнить поиск в интернете, обратиться к базе данных. Модель вызывает Tool явно, получает результат и включает его в ответ. Skill нужен, когда требуется изменить сам процесс работы модели. Например: сделать текст более формальным, перевести на другой язык, исправить стиль изложения. Skill срабатывает неявно — он влияет на то, как модель обрабатывает запрос, но сам по себе данных не возвращает. Когда применять: Tool: задача требует информации, которой у модели нет, требующих выполнения конкретных операций: вычислений, работы с API, запуска команд и т. д. Нужен поиск, запрос к API, получение актуальных данных. Skill: задача требует определённой обработки текста или изменения тона, формата, стиля ответа, нужно обучить модель определённому подходу к решению задач, задать правила работы или предоставить алгоритмы действий в текстовой форме. Например, для внедрения стандартов проверки кода, формирования текстов в определённом стиле или следования диагностическим шагам при устранении неполадок.  Итого: Tool — для получения данных извне, Skill — для изменения поведения модели.
Промпты	Workspace → Промпты	Пользователь вводит "/" и название промпта в чате.	1. Перейти в Workspace → Promts → Нажать Create. 2. Написать промт 3. Сохранить.	Чем Промпты отличаются от Skills Промпты (подсказки) — это многоразовые слэш-команды, которые превращают сложные инструкции в команды, выполняемые в один клик. Они позволяют сохранять часто используемые инструкции в виде слэш-команд. Например, можно ввести /summarize в любом чате, и полная подсказка сработает мгновенно. Промпты — это сохранённые слэш-команды. Например, /summarize или /translate. Пользователь вводит их вручную, и в чат подставляется заранее заготовленная инструкция. Skills — это активные обработчики, которые автоматически срабатывают без ручного вызова. Они перехватывают или модифицируют работу модели без участия пользователя. Основное отличие: промпт требует ручного вызова пользователем через слэш-команду. Skill срабатывает автоматически, без явного указания.
Valves	Внутри любого Pipe / Tool (класс Valves)	Никак — Valves не вызываются. Они настраиваются.  Valves — это не команды, а настройки Pipe. Пользователь один раз заполняет поля и забывает.	1. Открыть уже созданный Pipe или Tool. 2. В разделе Valves и/или UserValves указать нужные параметры. 3. Сохранить.	Valves и UserValves используются, чтобы пользователи могли предоставлять динамические данные, например, ключ API или опцию конфигурации. Они создают заполняемое поле или переключатель в меню GUI для заданной функции.  Valves позволяют пользователю настраивать параметры без редактирования кода следующим образом: 1. Создают в меню GUI удобные элементы для ввода данных:    - заполняемые поля;    - переключатели (bool switch). 2. Позволяют выбирать разные типы ввода в зависимости от задачи:    - ввод пароля (значения маскируются, отображаются точки вместо символов);    - выбор из списка (статический или динамический);    - множественный выбор (отображается список с чекбоксами). 3. Дают возможность настраивать параметры через интерфейс без изменения кода:    - UserValves настраиваются пользователями прямо из сеанса чата;    - параметры отображаются и изменяются в графическом интерфейсе;    - для чувствительных данных (пароли, API-ключи) предусмотрена маскировка.

OWUI - Open WebUI - это веб-интерфейс для работы с моделями искусственного интеллекта.

Routing в Open WebUI

Routing — это механизм определения того, как и куда направлять запросы пользователей в системе. В контексте Open WebUI это:

• Механизм распределения запросов между различными моделями ИИ
• Система правил для определения оптимального маршрута обработки запроса
• Процесс выбора подходящей модели для обработки конкретного запроса

Как работает routing в Open WebUI

1. Базовые принципы маршрутизации:
   • Определение доступных моделей
   • Установление приоритетов обработки
   • Настройка правил распределения запросов
2. Факторы маршрутизации:
   • Предпочтения пользователя
   • Настройки конкретного чата
   • Глобальные параметры системы
   • Модель по умолчанию
   • Права доступа
   • Контекст диалога

Управление routing

1. Администраторы могут настраивать:
   • Приоритеты моделей
   • Правила маршрутизации
   • Ограничения доступа
   • Параметры обработки запросов
2. Пользователи могут:
   • Выбирать модели для конкретных чатов
   • Настраивать предпочтения
   • Управлять параметрами работы

---

Модельная инфраструктура и абстракция провайдеров

OWUI не привязан к конкретному поставщику моделей. Вместо этого реализован слой абстракции, который унифицирует работу с разными бэкендами:

• Ollama: для локальных моделей на CPU/GPU.
• OpenAI‑compatible API: для облачных провайдеров и self‑hosted решений (vLLM, TGI, llama.cpp и др.).
• Специализированные провайдеры: Anthropic, Google Vertex AI и т. д.

Это позволяет администратору подключать новые источники моделей и управлять ими централизованно, а пользователям — переключаться между моделями в рамках одного интерфейса.

---

RAG‑архитектура: Embedding, поиск и Rerank

RAG в OWUI реализован как встроенный конвейер:

• Embedding‑модели преобразуют текст в векторы, которые индексируются в векторной базе данных. Поддерживаются разные хранилища: ChromaDB (локально), Qdrant, Milvus, PGVector и другие.
• Поиск выполняется по векторному сходству (cosine similarity) и может дополняться лексическим поиском (BM25) для гибридного подхода.
• Rerank‑модели улучшают выдачу: они берут топ‑N найденных фрагментов и пересортировывают их по релевантности, что заметно повышает качество контекста для LLM.

Такой подход позволяет системе эффективно работать с корпоративными базами знаний, документами и FAQ, не перегружая контекстное окно модели.

---

Основные типы моделей в Open WebUI

LLM (Large Language Model) — основная модель для обработки текстовых запросов:

• Отвечает за генерацию текста
• Выполняет основную обработку запросов
• Поддерживает различные типы задач (чат, генерация, анализ)

Embedding Model — модель для создания векторных представлений текста:

• Преобразует текст в числовые векторы
• Используется для:
  • Поиска по базе знаний
  • Сравнения текстов
  • Классификации
• Работает с семантическим сходством

Rerank Model — модель для переранжирования результатов:

• Пересортировывает полученные результаты
• Улучшает качество выдачи
• Применяет дополнительные критерии оценки

Как они работают вместе

1. Процесс обработки запроса:

• LLM получает запрос от пользователя
• Embedding Model создает вектор запроса
• Система ищет релевантные данные
• Rerank Model сортирует результаты
• LLM формирует финальный ответ

1. Взаимодействие моделей:

• Могут работать как единый конвейер
• Поддерживают параллельную обработку
• Интегрируются через API системы

Особенности настройки

LLM:

• Настраивается через параметры модели
• Требует настройки контекста
• Имеет различные режимы работы

Embedding:

• Определяет способ векторизации
• Влияет на качество поиска
• Может использовать разные алгоритмы

Rerank:

• Настраивается под конкретные задачи
• Определяет критерии ранжирования
• Может использовать дополнительные данные

Важные моменты

• Модели могут работать независимо или в связке
• Настройка происходит через административную панель
• Можно выбирать разные комбинации моделей для разных задач
• Система автоматически управляет распределением нагрузки между моделями

---

Безопасность и управление доступом

Безопасность в OWUI реализована на нескольких уровнях:

• Аутентификация: поддержка OAuth/OIDC, API‑ключей, SSO, LDAP/Active Directory.
• Ролевая модель (RBAC): разграничение прав на уровне пользователей, групп и рабочих областей.
• Контроль доступа к моделям и знаниям: администратор может ограничивать видимость моделей, источников знаний и инструментов для отдельных пользователей.
• Шифрование и приватность: данные хранятся локально, а при использовании внешних сервисов администратор контролирует, куда и какие данные отправляются.

Для корпоративных сценариев предусмотрены дополнительные механизмы: интеграция с SCIM для автоматического управления пользователями, журналирование действий и экспорт логов для аудита.

---

Масштабируемость и отказоустойчивость

Архитектура OWUI спроектирована с учётом масштабирования:

• Stateless‑бэкенд: экземпляры могут запускаться в нескольких копиях за балансировщиком нагрузки.
• Централизованное хранилище сессий: Redis используется для координации WebSocket‑сессий и синхронизации конфигурации между узлами.
• Внешние базы данных: для продакшена рекомендуется использовать PostgreSQL вместо SQLite.
• Векторные базы в клиент‑серверном режиме: локальный режим ChromaDB не подходит для кластера, поэтому в масштабируемых сценариях используют Qdrant, Milvus или PGVector.
• Мониторинг и наблюдаемость: поддержка OpenTelemetry для сбора метрик, трейсов и логов.

Такая конфигурация позволяет разворачивать OWUI в Kubernetes, Docker Swarm или на виртуальных машинах, обеспечивая высокую доступность и предсказуемую производительность.

---

Сценарии использования и гибкость архитектуры

Благодаря модульной структуре OWUI подходит для разных задач:

• Персональный AI‑ассистент: локальная установка с Ollama и простой RAG для личных заметок.
• Командная платформа: многопользовательский режим с разграничением доступа, общими источниками знаний и инструментами.
• Корпоративный шлюз к LLM: централизованное управление моделями, политиками безопасности и интеграциями.
• Платформа для экспериментов: быстрый запуск пайплайнов, тестирование разных моделей и стратегий RAG.

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

---

Заключение

Архитектура Open WebUI объединяет в себе удобство веб‑интерфейса, гибкость расширений и надёжность enterprise‑решений. Система спроектирована так, чтобы администратор мог управлять всеми аспектами работы с LLM — от маршрутизации запросов до интеграции с внешними сервисами и настройки RAG, — через понятный интерфейс, без необходимости программировать. При этом сохраняется возможность глубокой кастомизации через плагины и API. Такой подход делает OWUI универсальным решением как для индивидуальных пользователей, так и для крупных организаций, которым важны контроль, безопасность и масштабируемость.