Contextator
ENTR

Başlangıç

Yapılandırma

Contextator'ın okuduğu her ortam değişkeni — sunucu, hesaplar, veritabanı, depolama, belgeler, yüklemeler, gömme, arama, senkronizasyon, gözlemlenebilirlik, reverse proxy.

Güncelleme:

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

Değişken Varsayılan Ne yapar
PORT 3444 Uygulamanın dinlediği port. docker compose altında yalnızca host’ta yayınlanan portu değiştirir — konteynerin içinde uygulama 3444’te kalır
HOST 0.0.0.0 Konteynerin içindeki bağlanma adresi. Bunu olduğu gibi bırakın — dışarıdan neyin erişilebilir olduğunu kontrol eden ayar bu değildir; o, aşağıdaki CONTEXTATOR_BIND’dır. Docker, yayınlanan bir portu yalnızca konteynerin kendi loopback’ine bağlı bir sürece iletemez
CONTEXTATOR_BIND 127.0.0.1 docker compose’un portu hangi host arayüzünde yayınladığı (yalnızca Compose — uygulamanın kendisi bunu hiç okumaz). Varsayılan, yalnızca bu makinede ve başka hiçbir yerde yanıt verir. 0.0.0.0 her arayüzde yayınlar — bunu yalnızca önünde bir reverse proxy ya da bir VPN varken yapın, ve TRUST_PROXY ile PUBLIC_BASE_URL’i buna uydurun; aşağıda Bir reverse proxy arkasında çalışmak’a bakın
CONTEXTATOR_TAG latest docker compose’un hangi imaj etiketini çalıştıracağı (yalnızca Compose — uygulamanın kendisi bunu hiç okumaz). Bilinçli güncellemek için 1.0.0 gibi bir sürüm sabitleyin; bkz. Kurulum
LOG_LEVEL info fatal…trace, ya da silent. İstek başına loglama debug’da açılır
PUBLIC_BASE_URL – Örn. https://docs.example.com. Panoda gösterilen URL’ler için, ve — bir proxy arkasındayken — MCP connector’larının okuduğu OAuth metadata’sı için kullanılır. Bkz. Bir reverse proxy arkasında çalışmak
TRUST_PROXY 0 Hangi eşlerin bu sunucuya bir isteğin nereden geldiğini söyleyebileceği. req.ip’i (IP başına oturum açma sınırı, /oauth/register’ın host başına bütçesi, bir audit olayının yanındaki adres) ve req.protocol’ü belirler. 0, X-Forwarded-*’ı tamamen göz ardı eder, ki bu, önünde hiçbir şey olmayan gönderilen Compose şekli için doğrudur. Gerçek bir proxy arkasında bu ayarlanmalıdır — aşağıda Bir reverse proxy arkasında çalışmak’a bakın
ALLOWED_ORIGINS – /mcp/*’i çağırmasına izin verilen, virgülle ayrılmış tarayıcı origin’leri. Tarayıcı olmayan istemcilere her zaman izin verilir
SESSION_IDLE_TTL_MS 1800000 Boşta kalan Streamable HTTP transport oturumları 30 dakika sonra kapatılır. Pano oturum açmaları ayrıdır — o AUTH_SESSION_IDLE_MS’tir
MCP_STRUCTURED_OUTPUT 0 1, MCP araçlarının değişmeyen metnin yanında bir outputSchema yayınlamasını ve structuredContent döndürmesini sağlar; bu MCP 2025-11-25 istemcileri içindir, 2026-07-28 istemcisi bunları her zaman alır ve etkilenmez. Varsayılan olarak kapalıdır, çünkü bir sonuç bunu taşıdığı anda Claude Code metin yerine yapılandırılmış içeriği okur — bkz. MCP Araçları

Hesaplar ve oturumlar

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

Değişken Varsayılan Ne yapar
SETUP_CODE – İlk hesap var olmadan önce /setup’ın istediği tek seferlik kod. Ayarlarsanız onu asla logdan okumak zorunda kalmazsınız; boş bırakırsanız sunucu bir tane üretir ve o hesap oluşturulana kadar her başlatmada yazdırır. O andan sonra göz ardı edilir. Kontrol edilirken büyük/küçük harf, tire ve noktalama göz ardı edilir, bu yüzden noktalamaya güvenmek yerine yeterince harf ve rakam verin
ADMIN_TOKEN – Authorization: Bearer … üzerinden /api/*’e, root izinleriyle davranan makine erişimi — betikler ve CI için. Tarayıcılar bunun yerine bir hesapla oturum açar; bunu bir root parolası gibi görün ve asla birinin içine yapıştırmayın. /mcp/*’i korumaz
AUTH_SESSION_IDLE_MS 43200000 (12 sa) Bu kadar süre kullanılmayan bir pano oturumu yeniden oturum açmalıdır. Pano kullanımdayken yenilenir
AUTH_SESSION_TTL_DAYS 30 Ne kadar aktif kullanılırsa kullanılsın bir oturumun ömrünün sert tavanı. AUTH_SESSION_IDLE_MS’ten kısa olmamalıdır
AUTH_COOKIE_SECURE auto auto, istek HTTPS üzerinden geldiğinde Secure bayrağını ayarlar. TLS’i sonlandıran bir proxy arkasında 1 ile zorlayın; düz-HTTP bir LAN kurulumu için 0 kullanın, yoksa tarayıcı çerezi düşürür ve oturum açma /login’e geri döner
AUTH_LOGIN_MAX_ATTEMPTS 10 Bir kilitlenme ya da 429 öncesi, hesap başına ve IP adresi başına başarısız oturum açma sayısı
AUTH_LOGIN_WINDOW_MIN 15 Dakika cinsinden IP penceresi ve hesap kilitlenmesinin ilk adımı — buradan itibaren ikiye katlanır, bir saatte tavanlanır
PASSWORD_MIN_LENGTH 12 Geçici olanlar dahil her parolaya uygulanır. Hiçbir kompozisyon kuralı dayatılmaz
MCP_OAUTH 1 Bir istemcinin /mcp/* üzerinde bir hesap adına davranmasını sağlayan OAuth 2.1 akışı. 0 onu kaldırır; o zaman kapalı bir projeyi yalnızca statik tokenlar açar ve tarayıcı tabanlı connector’lar hiç bağlanamaz
MCP_OAUTH_ACCESS_TTL_MIN 60 Bir connector’a verilen tek bir access token’ın ömrü
MCP_OAUTH_REFRESH_TTL_DAYS 30 Bu süre boyunca kullanılmayan bir connector’ın yeniden yetkilendirilmesi gerekir
MCP_OAUTH_MAX_CLIENTS 200 Dinamik olarak kaydedilen connector client’larının tavanı (1 ile 100000 arası); kimliği doğrulanmamış bir /oauth/register’ın yazabileceği şeyi sınırlar

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

Veritabanı

Değişken Varsayılan Ne yapar
POSTGRES_PASSWORD contextator Gömülü PostgreSQL’in parolası. Küme ilk oluşturulduğunda uygulanır; sonradan değiştirmek ALTER USER gerektirir — bkz. Yedekleme ve Veri
DATABASE_URL – Boş olması (varsayılan) imajın kendi gömülü PostgreSQL’ini başlattığı anlamına gelir. Ayarlandığında Contextator’ı vector eklentisi olan harici bir PostgreSQL 16 ya da daha yenisine yöneltir ve gömülü sunucu başlatılmaz — veritabanını yedeklemek o zaman size kalır, POSTGRES_PASSWORD ile pgdata volume’ü de kullanılmaz. İçinde hiç PostgreSQL bulunmayan -slim imaj için zorunludur; bir kaynak checkout’unun okuduğu da budur (orada onun yerine libpq değişkenleri PGHOST, PGUSER, PGPASSWORD ve PGDATABASE çalışır). Bkz. Kurulum ve Kubernetes Üzerinde Çalıştırma
RESET_VECTORS 0 Gömme boyutlarını değiştirirken tek seferlik yıkıcı sıfırlama — bkz. Gömme Modelleri

Depolama (yalnızca Compose)

Değişken Varsayılan Ne yapar
CONTEXTATOR_PGDATA_VOLUME contextator-pgdata Veritabanı için volume adı
CONTEXTATOR_MODELS_VOLUME contextator-models İndirilen modeller için volume adı
CONTEXTATOR_DATA_VOLUME contextator-data Somutlaştırılmış kaynaklar için volume adı
CONTEXTATOR_PGDATA_PATH – Yukarıdaki volume yerine kullanılan mutlak host dizini
CONTEXTATOR_MODELS_PATH – Modeller için aynısı
CONTEXTATOR_DATA_PATH – Somutlaştırılmış kaynaklar için aynısı
DOCS_HOST_PATH ./docs /docs’a salt okunur bağlanan host klasörü

Ö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

Değişken Varsayılan Ne yapar
ALLOWED_DOC_ROOTS /docs Virgülle ayrılmış. Bir yerel klasör kaynağı bunlardan birinin içinde yaşamak zorundadır. Bu gerçek bir güvenlik sınırıdır — bkz. Güvenlik
IGNORE_GLOBS – İndeksleme sırasında atlanan, virgülle ayrılmış glob’lar, ör. **/CHANGELOG.md,drafts/**. Her kaynağa uygulanır
DATA_DIR .data (konteynerde /data) Git checkout’larını, yüklemeleri ve Notion çekimlerini tutan yazılabilir dizin
SECRET_KEY – En az 32 karakter (openssl rand -hex 32). Git, Notion, Confluence ve GitHub token’larını, S3 anahtar çiftlerini, Google Drive anahtarlarını ve webhook secret’larını beklemede şifreler (AES-256-GCM). Yalnızca böyle bir kaynak var olduğunda gerekir. Onu tek başına değiştirmek saklanan her token’ı okunamaz bırakır — bunun yerine rotate edin: emekliye ayrılan anahtarı SECRET_KEY_PREVIOUS’a, yeni anahtarı SECRET_KEY’e ayarlayın, yeniden başlatın, npm run rotate-secret’i çalıştırın, sonra SECRET_KEY_PREVIOUS’ı kaldırıp yeniden başlatın. Güvenlik sayfasındaki rotate runbook’una bakın
SECRET_KEY_PREVIOUS – Yalnızca bir rotate işleminin (yukarıda) süresi boyunca ayarlanan, emekliye ayrılan anahtar. Hiçbir zaman şifrelemez — okumalar ona geri döner, her yazma SECRET_KEY’i kullanır
SOURCE_ALLOWED_HOSTS – 0.6.0 ile geldi. Bir Confluence kaynağının, bir S3 kaynağının endpoint’inin ve bir GitHub kaynağının GitHub Enterprise Server host’unun özel bir adreste (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 198.18.0.0/15, fc00::/7, fec0::/10) erişebileceği, virgülle ayrılmış host adları (ya da IP literalleri), ör. wiki.corp.example. İç ağdaki bir Confluence Data Center örneği için gereklidir; loopback, link-local (169.254.169.254 dahil), belirtilmemiş ve multicast adresler ile ayrılmış 240.0.0.0/4 ne listelenirse listelensin reddedilmeye devam eder. Bağlanılan adreste ve her yönlendirmede yeniden kontrol edilir. Bkz. Confluence. URL değil, ad; bir web ya da git kaynağı için host’a izin vermez. Helm: config.sourceAllowedHosts
CONFLUENCE_ALLOWED_HOSTS – 1.0.0’da kaldırıldı. Boş olmayan bir değer sunucunun başlamasını SOURCE_ALLOWED_HOSTS’u adıyla anan bir mesajla durdurur; yükseltmeden önce host’larını oraya taşıyın. Boş ya da ayarsız bir değer kabul edilir. Helm chart’ta ayar config.sourceAllowedHosts’tur; config.confluenceAllowedHosts chart 3.0.0’da kaldırıldı. Bkz. uyumluluk politikası
WEB_ALLOWED_HOSTS – Bir dokümantasyon sitesi (web) kaynağının özel bir adreste erişebileceği, virgülle ayrılmış host adları (ya da IP literalleri) — SOURCE_ALLOWED_HOSTS ile aynı aralıklar ve aynı her zaman reddedilen adresler. İç ağdaki bir site için gereklidir; 0.3.1’den itibaren iç bir host’taki web kaynağı listelenene kadar çalışmaz. URL değil, ad; diğer listelerden bağımsızdır. Helm: config.webAllowedHosts. Bkz. Dokümantasyon sitesi kaynağı
GIT_ALLOWED_HOSTS – Bir git kaynağının remote’unun özel bir adreste erişebileceği, virgülle ayrılmış host adları (ya da IP literalleri) — SOURCE_ALLOWED_HOSTS ile aynı aralıklar ve aynı her zaman reddedilen adresler. İç ağdaki bir git server’ı için gereklidir, ör. self-host Gitea; 0.3.1’den itibaren böyle bir kaynak listelenene kadar çalışmaz. URL değil, ad; diğer listelerden bağımsızdır. Helm: config.gitAllowedHosts. Bkz. Git deposu kaynağı
GIT_MAX_PACK_BYTES 268435456 (256 MiB) En az 1048576 (1 MiB). Bir git remote’undan gelen tek bir yanıtın (ref listesi ya da klon veya güncellemenin pack’i) taşıyabileceği en çok bayt; daha büyüğü sync’i bu ayarın adını anan bir hatayla düşürür. Bellek sınırı değildir: git kütüphanesi pack’i bellekte tutup iki kez kopyalar, bu yüzden bir fetch instance’ın kendi kullanımının üstüne bu değerin yaklaşık iki katını kullanabilir — konteynerin memory limitiyle birlikte yükseltin ve limiti değerin iki katının rahatça üstünde tutun. Helm: config.gitMaxPackBytes. 0.3.2 ile geldi. Bkz. Git deposu kaynağı
CONFLUENCE_MAX_PAGES 5000 Bir Confluence senkronizasyonunun çekebileceği sayfa sayısı (1 ile 100000 arası)
S3_MAX_OBJECTS 5000 1 ile 100 000 arası. Bir S3 kaynağının en fazla indeksleyeceği nesne sayısı: anahtar sırasındaki ilkler. Helm: config.s3MaxObjects
GDRIVE_MAX_FILES 5000 1 ile 100 000 arası. Bir Google Drive kaynağının en fazla indeksleyeceği dosya sayısı: gezinme sırasındaki ilkler. Helm: config.gdriveMaxFiles
GITHUB_MAX_ISSUES / GITHUB_MAX_DISCUSSIONS her biri 5000 1 ile 100 000 arası. Bir GitHub kaynağının en fazla indeksleyeceği issue ve Discussion sayısı, en son oluşturulanlar önce. Helm: config.githubMaxIssues, config.githubMaxDiscussions
NOTION_MAX_PAGES 5000 Bir Notion senkronizasyonunun çekebileceği sayfa sayısı (1 ile 100000 arası)
MAX_STORED_DOCUMENT_BYTES 1048576 (1 MB) Asgari 4096. read_document için her belgenin metninin ne kadarının veritabanında tutulduğu. Bunun ötesinde önek saklanır ve araç bunu söyler. PostgreSQL tarafından satır dışında sıkıştırılır, bu yüzden maliyet aynı belgenin vektörlerinin küçük bir kesridir
MAX_CONVERTED_FILE_BYTES 33554432 (32 MiB) Dosya okunmadan önce, taramanın kaydettiği boyuta karşı kontrol edilir, bu yüzden bir sınır asla belleğe zaten alınmış byte’lara uygulanmaz. .md, .mdx ve .txt ayrıştırılmak yerine çözülür ve sınırlanmaz
MAX_PDF_PAGES 2000 Her sayfa tek seferde belleğe okunmadan önce, bundan daha fazla sayfa bildiren bir PDF’i reddeder
MAX_DOCX_UNPACKED_BYTES 268435456 (256 MiB) Bir .docx, dizini yazarının yazdığı bir boyutu raporladığı bir zip’tir; her parça bir sayaç üzerinden şişirilir ve bu tavan aşıldığında atılır, ki bir zip bomb’unu gerçekten sınırlayan da budur
CONVERSION_TIMEOUT_MS 120000 (2 dk) Bunun ötesinde hâlâ dönüştürülmekte olan bir dosya, okunamayan bir PDF gibi adıyla reddedilir; worker thread değiştirilir ve çalışma devam eder
CONVERSION_IDLE_MS 60000 (1 dk) Dönüştürme worker thread’i dosyalar arasında sıcak tutulur ve bu kadar boşta kaldıktan sonra düşürülür, bu yüzden sessiz bir sunucu büyük bir belgenin büyüttüğü heap’i tutmaya devam etmez
MAX_SPEC_FILE_BYTES 8388608 (8 MiB) Spec olarak okunan en büyük OpenAPI/Swagger dosyası (en az 16384); daha büyük olan bütünüyle yüklenmek yerine reddedilir
CONVERSION_WORKER_MAX_HEAP_MB ayarsız (sınır yok) Dönüştürme thread’inin heap’i için MiB cinsinden isteğe bağlı üst sınır. Belleği sınırlı bir konteyner içindir: bunu aşan bir dosya adıyla reddedilir ve çalışma sürer; yoksa kernel’in OOM killer’ı tüm süreci alırdı
WEB_MAX_PAGES 1000 Bir web taramasının çekebileceği sayfa sayısı (1 ile 50000 arası)
WEB_MAX_DEPTH 10 Bir taramanın başlangıç sayfasından izlediği link derinliği (0 ile 25 arası)
WEB_REQUEST_DELAY_MS 500 Aynı siteye yapılan istekler arasındaki bekleme, milisaniye cinsinden (0 ile 60000 arası)
WEB_CRAWL_BUDGET_MS 900000 (15 dk) Bir tarama için duvar saati bütçesi (en az 1000)
WEB_RESPECT_ROBOTS 1 0, tarayıcının robots.txt’e uymasını durdurur

Yüklemeler

Değişken Varsayılan Ne yapar
UPLOAD_MAX_FILE_BYTES 52428800 (50 MB) Yüklenen dosya başına
UPLOAD_MAX_FILES_PER_REQUEST 500 Pano büyük klasörleri isteklere kendiliğinden böler
UPLOAD_MAX_ARCHIVE_BYTES 268435456 (256 MB) Yüklenen arşiv başına
ARCHIVE_MAX_ENTRIES 20000 Ayıklama sırasında uygulanan koruma
ARCHIVE_MAX_TOTAL_BYTES 1073741824 (1 GB) Ayıklama sırasında uygulanan koruma
DATA_DIR_MIN_FREE_BYTES 536870912 (512 MiB) DATA_DIR’in boş tutması gereken alan. Bunun altında bir yükleme ve gömülü veritabanında zorlanmış bir yeniden indeksleme 507 insufficient_disk ile reddedilir; bir proje içe aktarımı bunu artı arşiv boyutunun dört katını ister, yükleme okunmadan önce ve açılmadan önce yeniden denetlenir. Denetim danışma niteliğindedir ve 0 onu kapatır. Bkz. Yedekleme ve Veri

Gömme

Değişken Varsayılan Ne yapar
EMBEDDING_PROVIDER local local (CPU, API anahtarı yok) ya da openai
EMBEDDING_MODEL Xenova/multilingual-e5-small Herhangi bir transformers.js feature-extraction modeli. Önceki varsayılan, yalnızca 128 token okur: Xenova/paraphrase-multilingual-MiniLM-L12-v2. Yalnızca İngilizce ve daha hızlı: Xenova/all-MiniLM-L6-v2. Üçü de 384 boyutludur
EMBEDDING_DIMENSIONS 384 Modelle eşleşmelidir. text-embedding-3-small için 1536
EMBEDDING_DTYPE fp32 q8, ~4× daha küçük nicelenmiş bir model indirir
EMBEDDING_BATCH_SIZE 16 Batch başına gömülen parça sayısı
MODEL_CACHE_DIR .cache/models Konteynerin içinde /app/.cache/models
EMBEDDING_OFFLINE 0 1, gömme modelinin de reranker’ın da model indirmelerini yasaklar (önceden doldurulmuş önbelleğe sahip air-gapped makineler). Bkz. Air-gapped kurulumlar
EMBEDDING_BASE_URL – openai sağlayıcısının isteklerini gönderdiği yer, path’iyle birlikte (http://localhost:11434/v1). OPENAI_BASE_URL’e göre önceliklidir; o ad 1.0.0’dan beri kullanımdan kaldırılmıştır: EMBEDDING_BASE_URL boşken istekleri hâlâ yönlendirir, bunu yaparken sunucu başlangıçta bir uyarı loglar ve 2.0’dan önce kaldırılmaz. Eski addan bunun üzerine geçmek model id’sini bir kez değiştirir (URL api.openai.com değilse), yani her proje yeniden indekslenir. İkisi de ayarlı değilse istekler OpenAI’a gider. Host ve port model id’sinin parçasıdır, bu yüzden başka bir sunucuya yönlendirmek her projeyi yeniden indeksler. Bkz. Gömme Modelleri
EMBEDDING_REQUEST_DIMENSIONS auto auto, always ya da never. openai sağlayıcısının her istekle birlikte dimensions gönderip göndermeyeceği: auto bunu yalnızca text-embedding-3-* için yapar, always vektörlerini istek üzerine kısaltan bir model için, never bu alanı reddeden bir sunucu için
OPENAI_API_KEY – api.openai.com için gerekir; EMBEDDING_BASE_URL başka bir yeri gösteriyorsa opsiyoneldir, ayarlıysa orada bearer token olarak gönderilir
OPENAI_EMBEDDING_MODEL text-embedding-3-small Endpoint’in sunduğu modelin adı. Aşağıdaki sorgu ve passage prefix’leri bu addan çözülür; bu yüzden yerel bir takma adı değil, modelin gerçek adını (intfloat/multilingual-e5-small) yazın
EMBEDDING_MAX_INPUT_TOKENS – Modelin kullanışlı biçimde okuduğu — tokenizer’ının kestiği yer değil, eğitildiği pencere. Boş bırakılırsa sunucu bunu yüklü modelden keşfeder ve CHUNK_MAX_TOKENS sığmıyorsa başlatma sonrası uyarır; ayarlanırsa bu keşfin yerini alır, ve çelişen bir CHUNK_MAX_TOKENS başlamayı reddeder
EMBEDDING_TOKENIZER – Yalnızca EMBEDDING_PROVIDER=openai ile. Endpoint’in sunduğu modelin tokenizer.json’ıyla eşleşen bir Hugging Face model id’si (Xenova/multilingual-e5-small). Chunk’lar o zaman karakter ÷ 4 tahmini yerine modelin kendi tokenizer’ıyla boyutlandırılır; böylece bir endpoint, yerel provider’ın aynı modelden kestiği chunk’ları keser. Yalnızca tokenizer dosyaları (tokenizer.json ve tokenizer_config.json) ve hiçbir zaman ağırlıklar değil, başlangıçta MODEL_CACHE_DIR’e indirilir ve yüklenemezse başlangıç durur. Model id’sinin parçasıdır: ayarlamak ya da değiştirmek her projeyi bir kez yeniden indeksler. Bkz. Gömme Modelleri
EMBEDDING_QUERY_PREFIX / EMBEDDING_PASSAGE_PREFIX – Modelin eğitildiği talimat önekleri, sunucu tarafından eklenir, asla sizin tarafınızdan değil. Boş bırakmak modelin karar vermesi anlamına gelir: multilingual-e5-* için query: / passage: , başka her şey için hiçbiri. Sondaki boşluk önemlidir ve .env tırnaksız bir tanesini siler, bu yüzden EMBEDDING_QUERY_PREFIX="query: " yazın. Boş bir değer önek yok değil ayarlanmamış olarak okunur — önekleri olan bir modelde önek yok demenin yolu none’dır. Her iki değer de model id’sinin parçasıdır: birini değiştirmek, tıpkı EMBEDDING_MODEL’i değiştirmek gibi, her projeyi yeniden indeksler. Bkz. Gömme Modelleri
SEARCH_SCORE_FLOOR 0.82 Altında search_docs’un en iyi sonucunu vermek yerine iyi eşleşme yok dediği cosine similarity. 0 kapatır. Varsayılan embedding modeline karşı ölçülmüştür ve başka bir modelde anlamsızdır

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.

Değişken Varsayılan Ne yapar
HNSW_EF_SEARCH 100 Üretim filtresi uygulanmadan önce vektör indeksinin ürettiği aday sayısı — pgvector’ın kendi varsayılanı 40’tır. Her projenin kendi kısmi indeksi vardır, bu yüzden adaylar o projenin satırlarıdır; bir proje yeniden indekslenirken, bir sonraki üretimi aynı indekste durur ve sonradan filtrelenir. Her aramada gecikmeye mal olur
HNSW_ITERATIVE_SCAN relaxed_order relaxed_order, strict_order ya da off. Filtre istenenden daha az isabet bıraktığında kısa yanıt vermek yerine taramaya devam eder (pgvector 0.8+; daha eski bir sürümde üç ayar da göz ardı edilir ve arama eskisi gibi davranır). relaxed_order, satırları sırasız döndürür ve sunucu onları kendisi sıralar
HNSW_MAX_SCAN_TUPLES 20000 Yinelemeli bir taramayı gerçekten bitiren tavan, projenin kendi indeksinin tuple’larıyla sayılır. Bir örnek büyüdükçe değil, bir proje büyüdükçe yükseltin
SEARCH_MAX_PER_DOCUMENT 2 Bir belgenin bir yanıta katkıda bulunabileceği alıntı sayısı, sıralamadan sonra uygulanır ve altındaki alıntılardan yeniden doldurulur, bu yüzden beş isteyen bir agent yine de beş alır. Altın kümede ölçüldüğünde bir soru kazandırır — düşürdüğü şey sayfada zaten olan bir şeyin neredeyse birebir kopyasıdır. 20 kapatır
SEARCH_NEIGHBOR_CONTEXT 1 Her isabetin iki yanındaki parçalar, daha fazla sonuç olarak değil, onun çevresinde bağlam olarak gösterilir. 0 kapatır. Bir parça CHUNK_MAX_TOKENS’tır, bu yüzden bir yanındaki, eskiden bir isabetin kullandığı bağlamın yaklaşık üç katıdır
SEARCH_RERANK off on, birleştirilmiş adayları bir cross-encoder ile yeniden puanlar. Varsayılan olarak kapalıdır — ikinci bir model yükler ve her aramaya bir gidiş-dönüş ekler, ölçüm de Gömme Modelleri sayfasındadır
SEARCH_RERANK_MODEL Xenova/bge-reranker-base SEARCH_RERANK=on iken kullanılan cross-encoder
SEARCH_RERANK_DTYPE q8 fp32, fp16 ya da q8
SEARCH_RERANK_MAX_TOKENS 128 Bir soru ve pasaj çiftinin kesildiği yer (32 ile 512 arası)
SEARCH_RERANK_BATCH 16 İleri geçiş başına çift sayısı (1 ile 100 arası)
SEARCH_QUERY_LOG 1 Sorgu logu için örnek geneli anahtar; 0, bir projenin kendi ayarı ne derse desin hiçbir yerde hiçbir şey kaydetmez
SEARCH_QUERY_LOG_RETENTION_DAYS 30 Kaydedilen bir sorgunun ne kadar süre tutulduğu (1 ile 3650 arası); report_gap raporlarını da süpürür
MCP_REPORT_GAP_PER_HOUR 20 Bir MCP kimlik bilgisinin saatte kabul edilmiş kaç report_gap raporu olabileceği; bir open projenin tüm anonim çağıranları aynı büyüklükte tek bir kovayı paylaşır. 0 sınırı kapatır. Sınırın üstündeki bir rapor başarı olarak yanıtlanır ve bırakılır. Bkz. MCP Araçları
SEARCH_MAX_RESULT_CHARS 12000 Tek bir render edilmiş search_docs yanıtının tavanı; bunun ötesinde bütün alıntılar düşürülür ve sonuç kaç tanesinin düştüğünü söyler. Varsayılan bir yanıt yaklaşık 3.300 karakterdir

Senkronizasyon

Değişken Varsayılan Ne yapar
SYNC_DEFAULT_INTERVAL_MINUTES 60 Yeni oluşturulan bir kaynağa dakika cinsinden verilen senkronizasyon aralığı; 0 onu zamansız oluşturur. Zaten var olan bir kaynağa asla ulaşmaz — ne yükseltmede, ne de bu değer değiştiğinde — bu yüzden bir yükseltme kimsenin istemediği hiçbir giden trafiği başlatmaz. Kaynak başına, pano ve API 5 ile 43200 (30 gün) arasını, ya da Never’ı kabul eder
WEBHOOK_MIN_INTERVAL_MINUTES 5 Bir kaynağın webhook tetiklemeli senkronizasyonları arasındaki asgari aralık; 0 her teslimatı hemen kuyruğa alır. Canlı okunur, bu yüzden bir değişiklik kendi aralığı olmayan kaynaklara uygulanır
SYNC_PROBES_PER_TICK 10 Bir tick’in — bir dakikanın — kontrol edebileceği vadesi gelmiş kaynak sayısı. Geri kalanı sırasını korur, en eskiden başlayarak, ve bir sonraki tick onları alır
SYNC_MAX_SKIP_HOURS 24 Zamanlanmış bir kaynağın, kontrolü “değişmedi” demeye devam ederken başarılı bir senkronizasyon olmadan geçirebileceği en uzun süre, saat olarak (0 ile 720 arası). Bu süre aşılınca kaynak yine de senkronize edilir; kontrolün göremediği, Notion’da paylaşımı kaldırılmış bir sayfayı ya da değişiklik zamanı geri yüklenmiş bir dosyayı indeksten düşüren de bu senkronizasyondur. Notion’da paylaşımı kaldırılan bir sayfa bu yüzden, bu süre artı kaynağın kendi senkronizasyon aralığı, en fazla bir dakika ve senkronizasyonun kendi süresi ya da süren bir çalışma kadar bir süre içinde indeksten çıkar. 0 sınırı kapatır. Bedeli, hiçbir şey değişmemiş olsa bile her kaynak için bu süre başına bir gerçek senkronizasyondur. Senkronizasyonu sürekli başarısız olan bir kaynak sınırın ötesinde kalır ve başarılı olana kadar vadesi geldiği her seferde çalışır. Bir kaynağın aralığından küçük bir değer, o kaynağı vadesi geldiği her seferde senkronize eder. Zamanlanmamış kaynaklar (Never) etkilenmez

Gözlemlenebilirlik

Değişken Varsayılan Ne yapar
AUDIT_LOG_RETENTION_DAYS 365 Bir audit olayının ne kadar tutulduğu. Logun kendisi için bir anahtar yoktur — başarılı olan her durum değiştiren admin isteği kaydedilir. Bkz. Admin API
METRICS_TOKEN – GET /metrics’e ve başka hiçbir şeye ulaşan bir bearer kimlik bilgisi, bu yüzden scrape etmek Prometheus’a bir ADMIN_TOKEN vermek anlamına gelmez. En az 16 karakter — uzunluk bir taban, entropi değildir, ve bu endpoint hız sınırlı değildir. Ayarlanmazsa, /metrics yine de oturum açmış bir hesaba ya da ADMIN_TOKEN’a yanıt verir, ama yalnızca veritabanı ayaktayken; bir kesinti sırasında okunabilir kalmak isteyen bir örnek bunu ayarlar. Bkz. Admin API
METRICS_PUBLIC 0 1, /metrics’i hiçbir kimlik bilgisi olmadan yanıtlar. Özel bir ağ için, ya da yolu zaten koruyan bir proxy için — portun erişilebilir olduğu her yerde kapalı bırakın; exposition örneği tanımlar

Parçalama

Değişken Varsayılan Ne yapar
CHUNK_MAX_TOKENS 96 Parça başına token; embedding modelinin kendi tokenizer’ıyla sayılır
CHUNK_OVERLAP_TOKENS 24 Bir bölümün ardışık parçaları arasındaki örtüşme. CHUNK_MAX_TOKENS’tan küçük olmalıdır

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.


Connect with Notion (OAuth)

Üç değişken, kaynak diyaloğunda bir dahili integration token’ı yapıştırmaya alternatif olarak Connect with Notion’ı açar. Her operatör Notion’da kendine ait bir public connection kaydeder; Contextator’a ait bir connection yoktur.

Değişken Notlar
NOTION_OAUTH_CLIENT_ID Public connection’ın client id’si. Secret ile birlikte ayarlanır
NOTION_OAUTH_CLIENT_SECRET Client secret’ı. OIDC_CLIENT_SECRET gibi bir süreç secret’ı: veritabanında saklanmaz, döndürülmez, loglanmaz
NOTION_OAUTH_REDIRECT_URI Connection’a kaydedilen yönlendirme URI’si. Varsayılan <PUBLIC_BASE_URL>/api/sources/notion/oauth/callback. Bir alan adı kullanın, yerel instance için localhost; IP adresi olmaz

Yalnızca kimlik ve secret’tan biri ayarlıysa, ikisi de ayarlı olup ne NOTION_OAUTH_REDIRECT_URI ne PUBLIC_BASE_URL ayarlıysa ya da ikisi de SECRET_KEY olmadan ayarlıysa başlangıç, değişkeni adlandıran bir mesajla reddedilir. Hiçbiri ayarlı değilse hiçbir şey değişmez ve dashboard düğme göstermez. Helm’de kimliği env’e, secret’ı envSecret’a koyun. Connection’ın nasıl çalıştığı: Notion.

Belgeleri secret’lar ve kişisel numaralar için taramak

PII_SCAN (varsayılan 1, 0 kapatır), her belgenin saklanan metnini altı tür değer için tarar: bir AWS access key id, bir GitHub token’ı, bir PEM özel anahtarının başlığı, bir JWT, bir T.C. kimlik numarası (yalnızca geçerli kontrol hanelerinde) ve bir IBAN (yalnızca geçerli mod-97’de). Yalnızca raporlar, başka bir şey yapmaz: bir belge yazıldığı gibi indekslenir, aranır ve okunur; asla maskelenmez, asla atlanmaz ve arama sonuçları tarama açıkken ve kapalıyken aynıdır.

Bir bulgu, değerin nerede olduğu (belge, satır, sütun) ve maskelenmiş bir önizlemedir. SECRET_KEY ayarlıysa bulgu ayrıca değerin, ondan türetilen bir anahtarla HMAC’ini taşır; bu yalnızca dashboard’un “aynı değer N belgede geçiyor” demesini sağlar; SECRET_KEY olmadan bulgular onsuz yazılır ve hiçbir şey gruplanmaz. Değerin kendisi hiçbir yerde saklanmaz. Tarama, bir indeks çalıştırması bir projeyi değiştirdikten sonra arka planda ve henüz taranmamış her şey için başlangıçta bir kez çalışır. Bulgular bir proje editor’ü ve üstü için GET /api/projects/:id/findings ile listelenir (viewer 403 alır) ve proje sayfasında Secrets and personal data altında gösterilir; MCP yüzeyinde hiçbir şey yoktur. PII_SCAN=0 yeni taramayı durdurur, var olan bulguları yerinde bırakır. Proje dışa aktarımı onları dışarıda bırakır ve excluded.documentFindings altında sayar.

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 (ve true), aynı tehlikenin açıkça söylenmiş haliydi: 0.4.1’de kullanımdan kaldırıldı ve 0.5.0’dan beri başlangıçta reddedilir — süreç, değeri adlandıran bir mesajla çıkar. Bir sıçrama sayısı da kabul edilmez — bu sunucunun kontrol edemeyeceği bir iddiadır, ve proxy’nin önünde bir CDN belirdiği gün sessizce yanlış gider.

TRUST_PROXY=1 ayarlı bir 0.4.x kurulumundan yükseltmek bu yüzden ortamda tek satırlık bir değişikliktir ve yeni sürüm başlamadan önce gereklidir: proxy’yi adlandırın (loopback, adresi ya da CIDR bloğu), ya da önünde hiçbir şey yoksa 0 kullanın.

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ı, veritabanı modu (gömülü ya da harici) ve yükleme sınırları. Yöneticiler için buna veritabanı hedefi, izin verilen belge kökleri, veri dizini ve SECRET_KEY’in ayarlanıp ayarlanmadığı eklenir. 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.

Gezinmek için ok tuşları, açmak için Enter.