Open WebUI

1. Bevezetés¶

Az Open WebUI (korábban Ollama WebUI) mára egy komplex, kiterjeszthető és biztonságos AI interfész platformmá fejlődött, amely a vállalati szintű igények kiszolgálására is alkalmas. Ez nem csupán egy grafikus felület az Ollama számára, hanem egy teljes körű AI operációs rendszer, amely támogatja a több-felhasználós kezelést, a RAG (Retrieval Augmented Generation) munkafolyamatokat és az egyedi ügynöki logikákat.

Az Open WebUI evolúciója jól tükrözi a helyi AI technológiák fejlődését:

• Múlt: Kezdetben egy egyszerű SvelteKit-alapú frontend volt az Ollama API-hoz, amelynek célja a terminál alapú interakciók kiváltása volt egy ChatGPT-szerű felülettel.
• Jelen: Jelenleg egy multi-backend rendszer, amely nemcsak az Ollamát, hanem bármilyen OpenAI-kompatibilis API-t (pl. vLLM, LM Studio, GroqCloud) képes kezelni. Beépített funkciói közé tartozik a natív dokumentum-feldolgozás, a Python alapú "Pipelines" keretrendszer és az integrált képalkotás (DALL-E, ComfyUI).
• Jövő (2025-2026): A roadmap fókuszában a horizontális skálázhatóság, az enterprise-szintű biztonság (OAuth2.1, finomhangolt RBAC) és a fejlett kutatási képességek (Deep Research) állnak. Várható a proaktív memóriakezelés és az ügynöki (agentic) funkciók további mélyítése, ahol a modellek képesek lesznek komplex, több-lépéses feladatok önálló elvégzésére.

2. Az Open WebUI rendeltetése és alapvető funkciói¶

A platform elsődleges célja az AI demokratizálása vállalati környezetben, miközben az adatok az infrastruktúrán belül maradnak.

3. Telepítési modellek és DevOps munkafolyamatok¶

Az Open WebUI leggyakrabban Docker konténerként kerül telepítésre. A DevOps szakembereknek több képváltozat (image tag) közül kell választaniuk a hardver és a stabilitási igények függvényében.

3.1. Docker telepítési parancsok¶

Ha az Ollama a gazdagépen fut, az Open WebUI konténert a következőképpen kell indítani a hálózati kommunikáció biztosítása érdekében:

docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -e WEBUI_SECRET_KEY=generealt_titkos_kulcs \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

GPU támogatással rendelkező, egybecsomagolt (bundled) kép használata esetén (ahol az Ollama a konténeren belül van):

docker run -d -p 3000:8080 \
  --gpus all \
  -v ollama:/root/.ollama \
  -v open-webui:/app/backend/data \
  --name open-webui \
  ghcr.io/open-webui/open-webui:ollama

3.2. Docker Compose: A standard megközelítés¶

Termelési környezetben a Docker Compose fájl használata az ajánlott, mivel ez dokumentálja az infrastruktúrát és egyszerűsíti a frissítéseket.

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama_storage:/root/.ollama
    ports:
      - "11434:11434"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    depends_on:
      - ollama
    ports:
      - "3000:8080"
    volumes:
      - webui_storage:/app/backend/data
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}
      - DATABASE_URL=sqlite:////app/backend/data/webui.db
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

volumes:
  ollama_storage:
  webui_storage:

3.3. Ubuntu 24.04-re telepítés¶

Az Ubuntu 24.04 alapértelmezetten a Python 3.12-es verzióját használja. Bár az Open WebUI futhat ezen is, a fejlesztők a Python 3.11-et javasolják a stabilitás érdekében.

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev -y
python3.11 --version
mkdir -p /opt/open-webui
cd /opt/open-webui
python3.11 -m venv venv
source venv/bin/activate
python3.11 -m pip install open-webui
open-webui serve

Ebben a környezetben elengedhetetlen, hogy a szolgáltatás automatikusan elinduljon a rendszerrel együtt. Docker helyett itt a systemd-re támaszkodunk.

Hozd létre a /etc/systemd/system/open-webui.service fájlt:

[Unit]
[Unit]
Description=Open WebUI Native Service
After=network.target ollama.service


Type=simple
# Cseréld ki a 'felhasznalonev'-et arra, akivel a mappát létrehoztad (pl. assistant vagy root)
User=root
Group=root
WorkingDirectory=/opt/open-webui
# Adatkönyvtár fixálása a /opt alá a hordozhatóságért
Environment="DATA_DIR=/opt/open-webui/data"
Environment="OLLAMA_BASE_URL=http://localhost:11434"
Environment="WEBUI_SECRET_KEY=$(openssl rand -hex 32)"
Environment="WEBUI_AUTH=True"
# Közvetlen hivatkozás a venv-ben lévő futtatható állományra
ExecStart=/opt/open-webui/venv/bin/open-webui serve
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Alkalmazása:

sudo systemctl daemon-reload
sudo systemctl enable open-webui
sudo systemctl start open-webui

Mivel kézzel telepítetted, a frissítés folyamata a következő lesz:

cd /opt/open-webui
source venv/bin/activate
pip install --upgrade open-webui
sudo systemctl restart open-webui

4. Az Open WebUI konfigurációja: Környezeti változók és perzisztencia¶

Az Open WebUI konfigurációs rendszere rétegzett. Vannak fix környezeti változók és vannak úgynevezett PersistentConfig változók, amelyek értéke az adatbázisban tárolódik és a felületen keresztül módosítható.

Kritikus környezeti változók táblázata

5. Mappa struktúra és adatbázis perzisztencia¶

Az Open WebUI az összes perzisztens adatot egyetlen volumon belül tárolja, ami egyszerűsíti a mentési és migrálási folyamatokat.

A volume belső struktúrája (/app/backend/data) a következő docker esetén:

• webui.db: SQLite adatbázis fájl. Ez tartalmazza a felhasználói profilokat, a chat előzményeket, a tageket és a konfigurációs beállításokat.
• uploads/: Itt tárolódnak a felhasználók által feltöltött dokumentumok, amelyeket a RAG rendszer használ.
• cache/: Az embedding modellek (amelyek a szöveget számokká alakítják) és a Whisper (audio-to-text) modellek gyorsítótárazott fájljai. Ez a könyvtár jelentős méretűre nőhet.
• docs/: Vektorizált dokumentum-indexek és metaadatok.
• audit.log: A rendszer minden műveletet ide naplóz, ha az AUDIT_LOGS_FILE_PATH változó be van állítva.

A volume belső struktúrája a következő native telepítés esetén:

A cache/ könyvtár nagyon nagyra nőhet (több GB). DevOps szempontból érdemes ezt a könyvtárat egy külön, gyorsabb lemezre mountolni vagy szimbolikus linkkel kivezetni a backupból, hogy a mentés csak a webui,db-t és az uploads/-t tartalmazza.

Natív Ubuntu környezetben az integráció egyszerűbb, de figyelni kell a jogosultságokra:

• CORS beállítások: Ha az Open WebUI nem ugyanazon a gépen fut, mint az Ollama, az Ollama systemd konfigurációjában az OLLAMA_ORIGINS változót *-ra vagy a WebUI IP-jére kell állítani.
• Közvetlen API elérés: A WebUI a backendjén keresztül kommunikál az Ollamával. Natív módban ellenőrizd, hogy a systemd service-ben az OLLAMA_BASE_URL helyesen van-e megadva.
• Adatátvitel: Mivel nincs konténerizált hálózati réteg, a válaszidők (latency) minimálisak lesznek a két folyamat között.

DevOps szempontból a legfontosabb fájl a webui.db. Ennek mentése kritikus. Az adatbázis migrációkat az Alembic nevű keretrendszer kezeli automatikusan az indításkor. Ha az adatbázis verziója nem egyezik a kóddal, az indítási folyamat megállhat vagy hibaüzenetet küldhet. Ilyenkor a DATABASE_URL helyes beállítása és az írási jogok ellenőrzése az első lépés.

6. Ollama integráció: Protokoll-orientált design¶

Az Open WebUI nem csupán egy proxy; mély integrációval rendelkezik az Ollama API-val. Ez lehetővé teszi a következőket:

• Modellek letöltése (Pulling): Közvetlenül az interfészről indítható egy új modell letöltése, ahol a WebUI valós időben mutatja a folyamatjelzőt az Ollama API válaszai alapján.
• Paramétervezérlés: A hőmérséklet (temperature), top-k, top-p és a kontextus ablak mérete minden egyes csevegésnél egyedileg állítható, amit a WebUI továbbít az Ollamának.
• Reasoning modellek kezelése: A legújabb modellek (pl. DeepSeek-R1) "gondolkodási" folyamatát (<think> tagek) az Open WebUI képes külön blokkban megjeleníteni, ha az Ollama a megfelelő parserrel fut.

7. Üzemeltetési és DevOps stratégiák¶

A rendszerek skálázása és karbantartása során több specifikus kihívással kell szembenézni. Frissítés és életciklus-menedzsment

A frissítési folyamat kritikus, mivel az Open WebUI és az Ollama is sűrűn (akár hetente) ad ki új verziókat.

1. Backup: Készítsünk másolatot a webui.db fájlról és a volumról.
2. Pull: Húzzuk le az új image-et: docker pull ghcr.io/open-webui/open-webui:main.
3. Migration Check: Ellenőrizzük a konténer logokat (docker logs open-webui) az indítás után, hogy az Alembic migrációk hiba nélkül lefutottak-e.
4. Cache törlés: Frissítés után a böngésző cache ürítése gyakran szükséges a UI elemek helyes megjelenítéséhez.

Automatizált frissítésekhez olyan eszközök használhatók, mint a Watchtower vagy a WUD (What's Up Docker), de termelési környezetben a manuális, ellenőrzött frissítés javasolt az esetleges adatbázis-sémaváltások miatt.

7.1. Monitorozás és hibakeresés¶

Az Ollama és az Open WebUI is bőséges naplózási lehetőséget kínál.

• Ollama naplók: Linuxon journalctl -u ollama. Keressük a "failed to create compute context" hibaüzenetet, ami általában GPU/VRAM problémára utal.
• Open WebUI naplók: docker logs open-webui. Itt láthatók a backend (FastAPI) hibái, például a hibás OLLAMA_BASE_URL miatti kapcsolódási hibák.
• Health Checks: Használható a GET /api/models végpont az Open WebUI-n. Ha 200-as kódot ad vissza és tartalmazza a modelleket, a teljes lánc (WebUI -> Ollama -> GPU) működőképes.

A teljesítmény méréséhez (benchmarking) az Open WebUI tartalmaz egy belső tesztcsomagot, amely képes szimulálni több párhuzamos felhasználót és mérni a válaszidőket (P95 latency), valamint a token/másodperc értékeket.

7.2. Skálázhatóság és Load Balancing¶

Nagyobb terhelés esetén az Open WebUI képes több Ollama példányt is kezelni.

• Random terheléselosztás: Ha több Ollama URL-t adunk meg, a WebUI véletlenszerűen osztja el a kéréseket közöttük.
• Modell azonosság: Fontos, hogy minden Ollama példányon ugyanazok a modellek legyenek letöltve azonos névvel a konzisztens válaszokhoz.
• Hálózati késleltetés: A AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST változóval finomhangolható, hogy mennyi ideig várjon a WebUI egy esetleg lassú vagy nem elérhető Ollama node-ra.