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_ATTEMPTSbaşarısızlığı herkese429yanıtı verir. - MCP connector’ları yetkilendirme yapamaz hale gelir.
PUBLIC_BASE_URLayarlanmamışken, OAuth korunan kaynak metadata’sı veWWW-Authenticateişaretçisireq.protocol’den oluşturulur — ki buhttpokur — bu yüzden belgehttp://…reklamını yaparken istemcihttps://…gönderir, ve/oauth/authorizeher seferindeinvalid_targetyanı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
Securebayrağını kaybeder, çünküAUTH_COOKIE_SECURE=autoaynı yönlendirilmiş şemayı izler.AUTH_COOKIE_SECURE=1bu 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 denone’a ayarlamak dahil, birini ayarlamak her projeyi bir sonraki çalışmasında yeniden indeksler.EMBEDDING_DIMENSIONS— bir kezRESET_VECTORS=1gerektirir; 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.