Yapılandırma

Her şey bir ortam değişkenidir. Compose ile bunları docker-compose.yml’in yanındaki .env’e koyarsınız; birlikte gelen .env.example açıklamalı tam listedir.

Yapılandırma başlangıçta doğrulanır. Bir şey yanlışsa sunucu her sorunu yazdırır ve yarı çalışır bir durumda başlamak yerine çıkar.

---

Sunucu

Hesaplar ve oturumlar

İnsanlar panoya kendi hesaplarıyla oturum açar; bu ayarlar bunun nasıl işlediğini şekillendirir. Bkz. Hesaplar ve İzinler.

Federe oturum açma (OIDC_ISSUER_URL ve geri kalan OIDC_* değişkenleri) kendi sayfasıdır — bkz. Tek Oturum Açma.

Veritabanı

Depolama (yalnızca Compose)

Örnekler:

CONTEXTATOR_PGDATA_PATH=/srv/contextator/pgdata     # Linux: veritabanını seçtiğiniz bir diskte tutun
CONTEXTATOR_MODELS_PATH=D:/contextator/models       # Windows host dizini (ileri eğik çizgiler)
CONTEXTATOR_PGDATA_VOLUME=contextator-pgdata-v2     # ya da yalnızca başka adlı bir volume

Belgeler

Yüklemeler

Gömme

Arama ve sıralama

Vektör indeksi için ince ayar ve bir yanıtın kendi isabetlerinden nasıl bir araya getirildiği. Varsayılanlar, altın kümenin en iyi ölçtükleridir; bunların geldiği kıyaslama için bkz. İndeksleme Nasıl Çalışır.

Senkronizasyon

Gözlemlenebilirlik

Parçalama

Bilinmesi iyi olan: 96, modelin penceresinin bir kesri değildir — varsayılan model 512 token okur — altın kümede en iyi ölçülen değerdir ve pencereyi doldurmak daha kötü ölçer. OpenAI’da ikisini de yükseltin; onun penceresi 8191’dir. Birini değiştirmek yalnızca sonradan indekslenen dosyaları etkiler — her yere uygulamak için zorla yeniden indeksleyin. Bkz. İndeksleme.

---

Bir reverse proxy arkasında çalışmak

Varsayılan olarak önünde hiçbir şey yoktur — Compose, 3444’ü loopback arayüzünde yayınlar (CONTEXTATOR_BIND=127.0.0.1), onunla port arasında hiçbir şey olmadan, ve yukarıdaki varsayılanlar bunun için yazılmıştır. Onu başka bir yerde yayınlamak (CONTEXTATOR_BIND=0.0.0.0), önüne bir şey koymanın tam zamanıdır. nginx, Caddy, Traefik ya da bir bulut yük dengeleyicisini öne koyun ve iki ayar birlikte hareket etmelidir:

TRUST_PROXY=172.18.0.0/16        # proxy'nin kendi adresi ya da CIDR'ı, ya da host üzerinde çalışıyorsa `loopback`
PUBLIC_BASE_URL=https://docs.example.com
AUTH_COOKIE_SECURE=1

TRUST_PROXY, bu sunucunun o proxy’den X-Forwarded-For ve X-Forwarded-Proto’yu okumasını sağlayan şeydir. Arkasında 0’da bırakılırsa üç şey bozulur, ve hiçbiri bunu kendiliğinden söylemez:

• IP başına oturum açma sınırı örnek geneline yayılır. Her istek proxy’nin adresini taşır, bu yüzden bir kişiden gelen AUTH_LOGIN_MAX_ATTEMPTS başarısızlığı herkese 429 yanıtı verir.
• MCP connector’ları yetkilendirme yapamaz hale gelir. PUBLIC_BASE_URL ayarlanmamışken, OAuth korunan kaynak metadata’sı ve WWW-Authenticate işaretçisi req.protocol’den oluşturulur — ki bu http okur — bu yüzden belge http://… reklamını yaparken istemci https://… gönderir, ve /oauth/authorize her seferinde invalid_target yanıtı verir. PUBLIC_BASE_URL’i ayarlamak bu yarısını tek başına düzeltir, yukarıdaki blokta olmasının nedeni budur.
• Session çerezi Secure bayrağını kaybeder, çünkü AUTH_COOKIE_SECURE=auto aynı yönlendirilmiş şemayı izler. AUTH_COOKIE_SECURE=1 bu yarısını tek başına düzeltir.

Sunucu hatayı tahmin etmek yerine gözlemler: bu örneğin güvenmediği bir X-Forwarded-* header’ı taşıyan ilk istek, üçünü de adlandıran tek bir uyarı loglar.

Proxy’yi adlandırın, istemcilerinizin bulunduğu ağı değil. Liste yalnızca eşe karşı değil, her sıçramaya karşı eşleştirilir — sunucu zinciri soketten dışarı doğru yürür, ve req.ip, listenin kapsamadığı ilk adrestir. Bu yüzden istemcilerin de 10.0.0.0/8 ya da 192.168.0.0/16 üzerinde olduğu bir LAN’da TRUST_PROXY=uniquelocal hiçbir şeyi korumaz: bir istemci tam olarak bir proxy gibi yürünür, ve X-Forwarded-For: 203.0.113.99, o değeri yeniden req.ip’e koyar. TRUST_PROXY=1, aynı tehlikenin açıkça söylenmiş halidir ve yalnızca porta proxy’den başka hiçbir şeyin ulaşamadığı durumda güvenlidir. Bir sıçrama sayısı kabul edilmez — bu sunucunun kontrol edemeyeceği bir iddiadır, ve proxy’nin önünde bir CDN belirdiği gün sessizce yanlış gider.

Proxy’nin, istemcinin gönderdiği her neyse onun üzerine eklemek yerine X-Forwarded-For’u değiştirdiğinden emin olun (nginx: proxy_set_header X-Forwarded-For $remote_addr;, önüne başka güvenilir bir proxy konulmadıkça $proxy_add_x_forwarded_for değil). Ekleyen bir proxy, çağırana en soldaki değeri verir, ve buradaki hiçbir ayar farkı söyleyemez. Panonun önüne Basic authentication koyan bir nginx örneği için bkz. Güvenlik.

Değişiklikleri uygulamak

docker compose up -d      # konteyneri yeni .env ile yeniden oluşturur

Ayarların çoğu hemen devreye girer. Birkaçı biraz daha fazlasını ister:

• EMBEDDING_MODEL — bir sonraki indeksleme çalışması otomatik olarak tam bir yeniden indekslemeye döner. Bu çalışmayı hiçbir şey kendiliğinden başlatmaz: proje sayfası uyuşmazlığı bir Re-index now düğmesiyle gösterir, ve düğmeye basılana kadar arama reddedilmeye devam eder. Çalışmayı günün herhangi bir saatinde başlatmak güvenlidir — eski indeksin yanına yazılır ve sonunda tek bir adımda yayınlanır, bu yüzden proje asla “indekslenmiş içerik yok” durumundan geçmez. Çalışırken proje, parçalarının ve vektör indeksindeki payının iki kopyasını tutar, bu yüzden disk için zirveyi planlayın. Bkz. Gömme Modelleri.
• EMBEDDING_QUERY_PREFIX / EMBEDDING_PASSAGE_PREFIX — modeli değiştirmek gibi sayılır: ikisini de none’a ayarlamak dahil, birini ayarlamak her projeyi bir sonraki çalışmasında yeniden indeksler.
• EMBEDDING_DIMENSIONS — bir kez RESET_VECTORS=1 gerektirir; bkz. Gömme Modelleri.
• CHUNK_MAX_TOKENS / CHUNK_OVERLAP_TOKENS — yeni indekslenen dosyalara uygulanır; her şeyi yeniden kurmak için Force re-index’i kullanın.

Bir varsayılan değişikliğini yükseltmek kendi başına bir durumdur: Xenova/multilingual-e5-small, Xenova/paraphrase-multilingual-MiniLM-L12-v2’den sonra varsayılan oldu. EMBEDDING_MODEL’i hiç ayarlamamış bir kurulum yükseltmede yeniyi alır, ve mevcut her proje yeniden indekslenene kadar bir uyuşmazlık olarak okunur. Bunu ertelemek için .env’de eski değeri sabitleyin — ve geri dönmenin yalnızca ayarı geri almak meselesi olmadığını unutmayın: yeni model altında zaten yeniden indekslenmiş bir proje geri dönmek için başka bir yeniden indekslemeye ihtiyaç duyar.

Neyin canlı olduğunu kontrol etmek

GET /api/health, çalışan yapılandırmayı raporlar: veritabanı durumu, gömme sağlayıcısı, model, boyutlar, dtype ve hazırlık ve giriş penceresi, CHUNK_MAX_TOKENS’ın o pencereye sığıp sığmadığı, açık MCP oturumları, izin verilen belge kökleri, veri dizini, SECRET_KEY’in ayarlanıp ayarlanmadığı ve yükleme sınırları. Panonun üst çubuğu önemli olanları gösterir.

Çağıranı ne kadar az tanıyorsa o kadar az ayrıntıyla yanıtlar: anonim bir istek — bir monitör, ya da konteynerin kendi sağlık kontrolü — ok, sürüm, veritabanı durumu ve setup’ın hâlâ beklemede olup olmadığını alır, makineyi tanımlayan hiçbir şeyi almaz. Gerisi için oturum açın ya da ADMIN_TOKEN kullanın.

GET /metrics, kendi kimlik bilgisi kurallarına sahip ayrı, Prometheus biçimli bir endpoint’tir — bkz. Admin API.