Open WebUI Kurulumu ve Ollama Entegrasyonu

Open WebUI, yerel model sunucularının komut satırı deneyiminin üzerine ChatGPT benzeri, zengin bir web arayüzü ekleyen açık kaynak bir platformdur. Ollama ile birlikte kullanıldığında, tarayıcı üzerinden model seçimi, sohbet geçmişi, belge tabanlı soru yanıtlama ve çok kullanıcılı yönetim gibi kurumsal seviyede özellikler sunar. Bu rehber, Docker tabanlı kurulumu, Ollama entegrasyonunu, kullanıcı yönetimini ve RAG ile belge yüklemeyi ayrıntılarıyla ele alır.

Open WebUI Nedir

Proje, önce Ollama WebUI adıyla yalnızca Ollama’nın arayüzü olarak doğmuş; sonrasında OpenAI uyumlu tüm sağlayıcıları destekleyen bağımsız bir platforma dönüşmüştür. Sıradan bir sohbet arayüzünün ötesinde çoklu model karşılaştırma, sistem istemi şablonları, model parametre ayarları, konuşma dallandırma ve rol tabanlı kullanıcı yönetimi gibi işlevler içerir. Kurumsal ortaklıkları olmayan, topluluk tarafından geliştirilen bir yazılımdır ve kendi altyapısında barındırıldığı için veriler dışarıya çıkmaz.

Tipik kullanım senaryoları arasında küçük ekiplerin iç yapay zekâ portalini kurması, bireysel kullanıcıların belgeleriyle yerel sohbet kurması ve geliştiricilerin modelleri üretim öncesi test etmesi sayılabilir.

Ön Koşullar

Kurulumun resmî önerisi Docker üzerine kuruludur; belgeler, özellikle üretim kullanımında Docker yöntemini önerir. Gerekli bileşenler şunlardır: güncel bir Docker sürümü (Linux’ta Docker Engine, Windows ve macOS’ta Docker Desktop), çalışan bir Ollama kurulumu ve model için yeterli RAM ya da VRAM. Open WebUI’in kendisi hafif olduğu için ana makine üzerindeki bellek büyük ölçüde dil modeli tarafından tüketilir.

Windows’ta Docker Desktop kullanılıyorsa WSL 2 arka ucunun etkin olması önerilir. Ollama aynı makinede kurulu değilse önce Ollama kurulup en az bir model indirilmelidir; aksi hâlde arayüz açılsa bile sohbet edilecek model bulunmaz.

Kurulum Adımları

Ollama ile Aynı Makinede Tek Konteyner

1. Aşağıdaki komutla Open WebUI konteyneri başlatılır; komut, konteynerin ana makinedeki Ollama’ya erişmesini sağlayan host geçidi ayarını ve kalıcı veri depolama birimini içerir.

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

2. Konteynerin durumu kontrol edilir.

docker ps

3. Tarayıcıdan http://localhost:3000 adresi açılır.
4. Açılan ekranda ilk hesap oluşturulur; ilk kayıt olan kullanıcı otomatik olarak yönetici olur.

Volume parametresi kritik önemdedir: veritabanı ve belge deposu bu birimde saklandığı için parametrenin atlanması, konteyner her güncellendiğinde tüm kullanıcı ve sohbet verisinin kaybına yol açar.

Ollama’nın Docker Konteynerinde Olduğu Düzen

Ollama da konteyner içinde çalışacaksa iki servisin aynı ağda olması gerekir. En pratik yöntem, Ollama ve Open WebUI’yi tek dosyada tanımlayan bir Docker Compose düzeni kurmaktır:

services:
  ollama:
    image: ollama/ollama
    volumes:
      - ollama:/root/.ollama
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama
    volumes:
      - open-webui:/app/backend/data
volumes:
  ollama:
  open-webui:

Dosya kaydedildikten sonra docker compose up -d komutuyla her iki servis başlatılır. Open WebUI, OLLAMA_BASE_URL değişkeni sayesinde Ollama’yı doğrudan servis adından bulur.

NVIDIA GPU’lu sistemlerde Ollama konteynerine GPU geçirgenliği eklenir; Docker Compose dosyasında Ollama servisine deploy bölümü altında GPU rezervasyonu tanımlanır ve ana makinede NVIDIA Container Toolkit kurulu olur.

Ollama Bağlantısını Doğrulama

Arayüz açıldığında sol üstteki model seçici, bağlantı başarılıysa Ollama’da yüklü modelleri listeler. Liste boşsa Ayarlar bölümünden Yönetici Paneli üzerinden bağlantı ayarları kontrol edilir; varsayılan değer ana makine Ollaması için host.docker.internal:11434, konteyner ağı için servis adı ve 11434 numaralı bağlantı noktasıdır. Bağlantı kurulduktan sonra model henüz indirilmemişse arayüz üzerinden model çekme isteği de gönderilebilir; Open WebUI, Ollama’nın model yönetimini arayüze taşır.

Kullanıcı Yönetimi

İlk kayıt olan hesap yönetici rolünü alır ve Yönetici Paneli üzerinden diğer kullanıcıları yönetir. Kayıt politikası üç biçimde ayarlanabilir: açık kayıt, davetle kayıt veya onaylı kayıt. Kurumsal kullanımda onaylı kayıt tercih edilir; yeni kullanıcılar hesap açar ancak yönetici onaylamadan sohbet başlatamaz.

Rol hiyerarşisi üç kademeden oluşur: yönetici tüm ayarlara erişir, yetkili kullanıcı model ve bilgi bankası yönetebilir, sıradan kullanıcı yalnızca izin verilen modellerle sohbet eder. Model bazında erişim kısıtlaması sayesinde örneğin büyük bir model yalnızca belirli gruba açılabilir. Şirket içi ağda çalışırken arayüzün yalnızca yerel ağdan erişilebilir olması, ek bir güvenlik katmanı sağlar.

RAG ile Belge Yükleme

Open WebUI’nin en güçlü özelliği, yerleşik RAG altyapısıdır. Yüklenen belgeler parçalara bölünür, gömme (embedding) modeliyle vektörlere dönüştürülür ve iç veritabanında saklanır; sohbet sırasında model, soruya en ilgili parçaları bağlam olarak alır. Kullanım adımları şöyledir:

1. Sol menüden Çalışma Alanı bölümünde Bilgi (Knowledge) sekmesi açılır.
2. Yeni bilgi bankası oluşturulup PDF, Word, metin gibi dosyalar yüklenir.
3. Sohbet ekranında artı simgesiyle bilgi bankası konuşmaya eklenir.
4. Model soruları yalnızca belge içeriğine dayanarak yanıtlar.

Yönetici panelinden RAG ayarlarına inilebilir: parça boyutu, örtüşme oranı, üst k sonuç sayısı ve gömme modeli değiştirilebilir. Varsayılan gömme modeli yerel çalışır; Ollama üzerindeki bir gömme modeli de tanımlanabilir. Büyük belge kümelerinde parça boyutunun küçültülmesi, arama isabetini artırırken bağlam penceresini verimli kullanmayı sağlar.

Model Ayarları ve Sistem İstemi Şablonları

Open WebUI, her model için davranışı kalıcı biçimde tanımlama imkânı sunar. Çalışma alanındaki modeller bölümünde bir Ollama modeli seçildiğinde, ona özel sistem istemi yazılabilir; model artık her sohbette bu kimlikle açılır. Aynı temel modelden farklı görevlere hizmet eden türevler üretmek, bu özelliğin en yaygın kullanımıdır: biri özetleme uzmanı, biri kod yorumcusu, biri de yazım denetçisi olan üç profil, tek bir 8B modelden türetilir ve her kullanıcıye göre ayrı listelerde sunulur.

Sıcaklık, üst p ve tekrar cezası gibi üretim parametreleri de model düzeyinde ayarlanabilir. Ayrı bir görev profile sahip olmak, kullanıcıların her sohbette parametre elle girmesini engeller. Gelişmiş ayarlar arasında bağlam uzunluğu sınırı, durdurma dizileri ve akış davranışı bulunur. Modelin Ollama tarafındaki varsayılan değerleri değişmeden kalır; arayüz tanımları yalnızca bu arayüzden yapılan isteklere uygulanır, böylece arayüz ayarlarıyla motor ayarları birbirine karışmaz.

Sistem istemi şablonu (prompt template) özelliği, sık kullanılan görev kalıplarını kayıt altına alır. Bir şablon, kullanıcıdan belirli değişkenleri isteyip yerleştirir; toplantı özeti, e-posta taslağı gibi tekrar eden işler tek tıkla başlatılır. Şablonlar kullanıcı bazında da tanımlanabilir; ekip düzeyinde standartlaştırılmış şablon seti, iş birliğini destekler.

Güncelleme, Yedekleme ve İşletme

Docker kurulumunda güncelleme, imajın yeniden çekilmesi ve konteynerin yeniden başlatılmasıyla yapılır; volume birimi korunduğu sürece veriler güncellemeden etkilenmez. Uygulama her yeni sürümde arayüz iyileştirmeleri ve yeni entegrasyonlar getirdiği için düzenli güncelleme önerilir; ancak üretim kullanımında güncelleme öncesi yedek almak sağlam bir kuraldır.

Yedeklemenin özü, volume biriminin içerikini kopyalamaktır. Open WebUI’in veritabanı bu birimde tek dosya hâlinde tutulur; yüklenen belgeler de aynı birimde saklanır. Birim klasörünün düzenli aralıklarla kopyalanması, kullanıcı hesapları, sohbet geçmişi, belgeler ve ayarların tamamını kurtarılabilir kılar. Taşıma işlemi de aynı mekanizmayla çalışır: eski sunucudan alınan birim içeriği, yeni sunucuda aynı ada sahip birime aktarıldığında sistem, tüm verisiyle birlikte kaldığı yerden devam eder.

İşletme tarafında üç pratik ölçüt izlenir. Birincisi disk kapasitesidir; yüklenen belgeler ve bilgi bankaları zamanla büyür. İkincisi model yükleme gecikmesidir; soğuk modelin ilk istekte yüklenmesi saniyeler sürebilir ve sık kullanılan modellerin bellekte tutulması Ollama tarafındaki tutma ayarıyla düzenlenir. Üçüncüsü eşzamanlı kullanıcı sayısıdır; arayüz hafiftir ancak model üretimi tek GPU’da sıralanır, yoğun ekiplerde model başına ayrı sunucu çalıştırmak makul bir büyüme yoludur.

Yaygın Hatalar ve Performans İpuçları

En sık karşılaşılan sorun, arayüzün Ollama’yı görmemesidir; bunun nedeni genellikle Docker ağından host geçidi parametresinin eksik olması veya yanlış temel URL tanımıdır. Windows’ta dosya yükleme hataları, konteynerin bellek sınırından kaynaklanabilir ve Docker Desktop ayarlarından bellek tahsisi artırılarak çözülür. Konteyner güncellemesi yapılırken volume biriminin korunması şarttır.

Performans tarafında üç nokta öne çıkar: modelin Ollama tarafında tamamen GPU’da tutulması, uzun belgelerde parça boyutunun makul tutulması ve eşzamanlı kullanıcı sayısı arttıkça Ollama’nın paralellik ayarlarının gözden geçirilmesi. Açılışta konteynerin yeniden başlatılması için restart politikasının tanımlanmış olması, sunucu yeniden başladığında arayüzün otomatik dönüşünü garantiler. Güncellemeler için konteyner imajının düzenli aralıklarla çekilip yeniden başlatılması, arayüzün yeni özelliklerinden yararlanmayı sağlar.