Bir embedding modeli, metni bir vektöre dönüştürür; böylece benzer anlamlar birbirine yakın düşer. Contextator varsayılan olarak birini CPU’nuzda, local olarak çalıştırır — API key yok, hesap yok, makineden çıkan hiçbir şey yok — ve isterseniz onun yerine OpenAI kullanabilirsiniz.
Varsayılan
| Model | Xenova/multilingual-e5-small |
| Boyut | 384 |
| Diller | Türkçe dahil 100. Soruyu cevabın yazıldığı dilde sorun: diller arası eşleşme ölçülmüş bir model sınırıdır, açılıp kapanan bir ayar değil |
| İndirme | Bir kere ~470 MB (fp32), bir Docker volume’unda önbelleklenir |
| Çalıştığı yer | CPU. GPU kullanılmaz ve gerekmez |
Daha küçük ve daha hızlı seçenekler
EMBEDDING_DTYPE=q8 # aynı model, ~120 MB, quantized
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 # yalnızca İngilizce, ~90 MB, yine 384 boyut
EMBEDDING_DIMENSIONS=384
Herhangi bir transformers.js feature-extraction modeli çalışır. EMBEDDING_DIMENSIONS, modelin
ürettiğiyle eşleşmek zorundadır — eşleşmezse sunucu size doğru sayıyı söyler.
Bunun yerine OpenAI kullanmak
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-…
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536
RESET_VECTORS=1 # yalnızca değişiklikten sonraki ilk başlatma için — aşağıya bakın
Uzun parçalarda daha iyi getirme ve çok daha büyük bir girdi penceresi; bedeli, indekslenen her parça ve sorulan her sorgu için bir API çağrısıdır. Dokümantasyon metniniz OpenAI’a gönderilir; bu kabul edilemezse local kalın ya da aşağıdaki gibi kendi sunucunuzu kullanın.
Kendi sunucunuzu kullanmak
EMBEDDING_PROVIDER=openai, OpenAI uyumlu bir /embeddings endpoint’i sunan her sunucuyla konuşur.
EMBEDDING_BASE_URL’i path’iyle birlikte ona ayarlayın ve o sunucunun sunduğu modelin adını
OPENAI_EMBEDDING_MODEL’e yazın. Bir base URL ile OPENAI_API_KEY opsiyoneldir; ayarlıysa bearer token
olarak gönderilir. EMBEDDING_DIMENSIONS modelin vektör boyutuyla eşleşmelidir.
# Ollama
EMBEDDING_PROVIDER=openai
EMBEDDING_BASE_URL=http://localhost:11434/v1
OPENAI_EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_DIMENSIONS=768
# LM Studio: yerel sunucusu
EMBEDDING_BASE_URL=http://localhost:1234/v1
# Text Embeddings Inference, -p 8080:80 ile başlatılmış
EMBEDDING_BASE_URL=http://localhost:8080/v1
# vLLM: `vllm serve`'i başlattığınız host ve port
EMBEDDING_BASE_URL=http://gpu-box:<port>/v1
EMBEDDING_REQUEST_DIMENSIONS=always # yalnızca istek üzerine vektörlerini kısaltan bir model için
Her durumda model adını ve EMBEDDING_DIMENSIONS’ı yüklediğiniz modele göre ayarlayın; yukarıdaki satırlar
yalnızca farklı olanı gösterir. RESET_VECTORS=1 yalnızca veritabanı bir vektör boyutu kaydetmişse ve yeni
boyut ondan farklıysa gerekir — 384 boyutlu bir kurulumu 768 boyutlu bir modele taşımak gibi; ilk kurulum
buna ihtiyaç duymaz. Yalnızca bir başlatma için ayarlayın — bkz. Modeli değiştirmek.
EMBEDDING_REQUEST_DIMENSIONS varsayılan olarak auto’dur ve dimensions’ı yalnızca text-embedding-3-*
için gönderir; bunu kabul eden bir model için always, reddeden bir sunucu için never kullanın.
Token’ları modelin kendi tokenizer’ıyla saymak. Chunk’lar, EMBEDDING_TOKENIZER sunulan modelin
tokenizer.json’ıyla eşleşen bir Hugging Face modelini adlandırmadıkça bir tahminle (karakter ÷ 4) boyutlandırılır.
Yalnızca tokenizer, MODEL_CACHE_DIR’e indirilir ve yüklenemezse başlangıç durur. Onunla bir endpoint, yerel
provider’ın aynı modelden kestiği chunk’ları keser. Model id’sinin parçasıdır; bu yüzden ayarlamak ya da değiştirmek
her projeyi bir kez yeniden indeksler.
# TEI ya da vLLM arkasında multilingual-e5-small
EMBEDDING_PROVIDER=openai
EMBEDDING_BASE_URL=http://localhost:8080/v1 # TEI; vLLM: http://gpu-box:<port>/v1
OPENAI_EMBEDDING_MODEL=intfloat/multilingual-e5-small # gerçek ad, böylece e5 prefix'leri uygulanır
EMBEDDING_DIMENSIONS=384
EMBEDDING_TOKENIZER=Xenova/multilingual-e5-small
Prefix’lere modelin adı karar verir. multilingual-e5-* ailesinin query: ve passage: prefix’leri
OPENAI_EMBEDDING_MODEL’deki addan seçilir; bu yüzden orada modelin gerçek adı olmalıdır. Sunucunuz modeli başka bir adla sunuyorsa (yerel bir takma ad, bir yol), ad hiçbir aileyle eşleşmez: model prefix’siz çalışır ve recall sessizce düşer. Prefix değişkenlerinden birini ayarlamadıysanız sunucu bunu başlangıçta bir kez, info düzeyinde söyler. Ya modelin gerçek adını OPENAI_EMBEDDING_MODEL’e yazın ya da kendi adınızı tutup EMBEDDING_QUERY_PREFIX="query: " ve EMBEDDING_PASSAGE_PREFIX="passage: " değerlerini kendiniz ayarlayın; hangisini yaparsanız her projeyi bir kez yeniden indeksler.
Contextator konteynerinin içinde localhost sizin makineniz değil, konteynerin kendisidir: sunucuya
konteynerin ulaşabileceği adresi kullanın. Endpoint’in host’u ve portu, her projenin damgalandığı model
id’sinin parçası olur; bu yüzden başka bir sunucuya yönlendirmek her projeyi yeniden indeksler — bkz.
Modeli değiştirmek. Böyle bir sunucuya gönderilen metin, o sunucunun çalıştığı
yerde kalır.
Modeli değiştirmek
Aynı boyut (örn. 384 boyutlu local modeller arasında)
EMBEDDING_MODEL’i değiştirin.- Yeniden başlatın.
- Her projeyi yeniden indeksleyin.
Contextator, her projeyi hangi modelin indekslediğini kaydeder. Sunucunun modeli farklıysa, sonraki
çalışma otomatik olarak tam bir yeniden indeksleme olur ve search_docs, bu gerçekleşene kadar o
projede aramayı reddeder — kendinden emin ama yanlış sonuçlar döndürmek yerine, tam olarak bunu söyleyen
bir mesajla.
Farklı boyut (örn. OpenAI’ın 1536’sına geçiş)
Vektör kolonunun genişliği veritabanı oluşturulduğunda sabitlenir, bu yüzden bu tek seferlik yıkıcı bir adımdır:
- Provider’ı, key’i ve
EMBEDDING_DIMENSIONS’ı ayarlayın. - Bir kere
RESET_VECTORS=1ile başlatın. Her parça ve belge düşürülür, kolon yeniden tipenir (re-typed). RESET_VECTORS’ı kaldırın (ya da0’a geri ayarlayın).- Her projeyi yeniden indeksleyin.
Bayrak olmadan sunucu başlamayı reddeder ve şu talimatı yazdırır:
The database was created with EMBEDDING_DIMENSIONS=384 but the current config says 1536.
Either set EMBEDDING_DIMENSIONS=384, or start once with RESET_VECTORS=1
(drops every indexed chunk; all projects must be re-indexed), or wipe the pgdata volume.
Arama gerçekte nasıl çalışır
Arama hibrittir: anlam ve birebir sözcük aynı anda aranır ve sıralarıyla birleştirilir.
- Sorunuz, belgeleri indeksleyen aynı modelle gömülür.
- PostgreSQL, o projeyle sınırlı olarak iki sıralama üretir — bir HNSW index üzerinde cosine
similarity ile en yakın parçalar ve bir GIN index üzerinde
tsvectoranahtar sözcük eşleşmesi — ve bunları reciprocal rank fusion ile birleştirir; böylece bir ortam değişkeni de en az bir soru kadar kolay bulur sayfasını. - En iyi eşleşmeler; dosya yolu, başlık kırıntısı ve skorlarıyla döndürülür.
Skorlar cosine similarity’dir: yüksek olan daha iyidir ve varsayılan modelde yüksek ve birbirine yakın
dururlar. Sevk edilen yapılandırmada ortalama skor 0.881’dir ve yanlış bir hit, doğru olandan yalnızca
0.02 kadar aşağıdadır. Yani skor bir doğruluk sinyali değildir ve üründe hiçbir
şey sıralama ya da doğruluk kararı için skor okumaz; yalnızca aşağıdaki alan dışı taban ona bakar.
İlgi eşiği — varsayılanı SEARCH_SCORE_FLOOR=0.82 — bambaşka bir şeye karşı ölçüldü:
dokümantasyonunuzla hiç ilgisi olmayan sorulara. Commit edilmiş on iki
böyle soruluk kümede on tanesini reddediyor, altmış dört altın sorunun hiçbirini reddetmiyor. Eşiğin
iddiasının tamamı budur: alan dışı soruların çoğunu yakalar ve cevaplanabilir bir soruya hiçbir şeye mal olmaz.
İkisini ayırmaz — alan dışı en yüksek en iyi sonuç (0.839), gerçek bir sorunun en düşük en iyi
sonucunun (0.833) üstünde durur, bu yüzden hiçbir eşik ayıramaz. Ürününüz gibi görünen ama cevabı hiçbir
yerde yazılı olmayan soruyu da yakalamaz — onlar tam olarak gerçek soruların aldığı skorları alır. Eşiğin altında
search_docs, bir ajanın alıntılayacağı bir sonucu uzatmak yerine iyi eşleşme yok der.
Skorlar bir proje ve bir model içinde karşılaştırılabilirdir, farklı modeller arasında anlamsızdır —
EMBEDDING_MODEL’i değiştirirseniz eşik npm run eval ile yeniden ölçülmelidir.
SEARCH_SCORE_FLOOR (varsayılanı 0.82) sunucunun eşiğidir. Bir proje, kendi korpusu farklı ölçtüğünde
— düzyazı ağırlıklı korpuslar genelde daha düşük bir eşik ister — sorgu panelinden kendi eşiğini
ayarlayabilir, ya da eşiği kendisi için tamamen kapatabilir. Panel, bir eşiğin, uygulanmadan önce zaten
kaydedilmiş aramalara ne yapacağını gösterir, ve sunucunun SEARCH_SCORE_FLOOR=0’ı yine de her projenin
eşiğini kapatır. Bkz. Yapılandırma.
Birleştirilen sıralamalardır, skorlar değil. Cosine similarity ve PostgreSQL’in ts_rank’i
karşılaştırılabilir nicelikler değildir, bu yüzden füzyon her parçanın her iki tarafta tuttuğu
sıralamayı birleştirir — göründüğü listeler üzerinden Σ 1/(60 + sıra) (reciprocal rank fusion) —
embedding modeli her değiştiğinde yeniden öğrenilmesi gereken ağırlıklı bir toplam yerine. Sonuç:
bir sonucun skoru artık konumunu açıklamaz — 0.86 skorlu biri 0.88 skorlu birinin üstünde
oturabilir. GET /api/projects/:id/search ve pano, her sonucun her iki tarafta tuttuğu sıralamayı
D3 L1 olarak gösterir; bir L’si olup bir D’si olmayan bir sonuç, salt vektör aramanın tek başına
göremeyeceği bir tanımlayıcıdır. Altın kümede, sıralama füzyonu tanımlayıcı biçimli otuz soruyu
recall@5 %76,7’den %83,3’e taşıdı. Doğal dilde sorulan otuz dört soruyu ise hiç kıpırdatmadı;
recall@1 %78,1’den %75,0’a düştü — bu, füzyonun yaptığı takas: yalnızca bir yarı tarafından bulunan
bir parça, ikisi tarafından da makul biçimde bulunan birinin önüne geçemez.
Varsayılan model asimetriktir: bir arama sorgusunun önüne query: , indekslenen bir pasajın önüne
ise passage: konularak eğitilmiştir, bu yüzden sunucu onları otomatik olarak ekler — indekslediğiniz
ya da aradığınız hiçbir şey onlardan hiç bahsetmez, ve önekleri olmayan bir model bir sorguyu ve bir
pasajı hiçbir bedel ödemeden özdeş biçimde kodlar. Retrieval korpusunda önekler bir soruyu sıra 1’de
kazandırdı ve recall@5’te hiçbir şey değiştirmedi; EMBEDDING_PASSAGE_PREFIX=none ile birlikte
EMBEDDING_QUERY_PREFIX=none onları kapatır ve önceki model kimliğini tam olarak geri getirir.
Anahtar sözcük yarısı varsayılan olarak her kaynağı PostgreSQL’in simple yapılandırmasında
indeksler — yazıldığı gibi sözcükler, hiçbir stemming olmadan — ki bu referans materyali için doğru
seçimdir: HALYARD_DISPATCH_TIMEOUT ve HLY-4015, oldukları dizeler olarak indekste hayatta kalır.
Bir kaynak bunun yerine kendi dilini adlandırabilir (kaynak formundaki Language alanı), ki bu onu
stemmed bir yapılandırmaya geçirir — anahtarı hakkında Türkçe sorulan bir soru o zaman
anahtarın diyen bir sayfayı bulur, simple’ın ilişkisiz saydığı iki dize. İkisi bir projede
birbirine karışmadan birlikte yaşar: her kaynak kendi yapılandırmasında aranır ve tek bir sorgu
hepsine ulaşır, her biri füzyona kendi sıralı listesiyle katkıda bulunur. Bir kaynağın dilini
değiştirmek onu yeniden indeksler.
Diller arası arama bilinen bir sınırdır ve düzeltilmeyecek
Soruyu, onu cevaplaması gereken dokümantasyonla aynı dilde yazın. Türkçe sayfalar Türkçe biçimli
ifadeler için yüzeye çıkar. İngilizce sayfalar İngilizce biçimli ifadeler için yüzeye çıkar. O sınırı
geçmek çoğunlukla hiçbir şey döndürmez, ve bu açılabilecek bir ayar değil, embedding modelinin bir
özelliğidir. Her MCP client’ı bir dil modelidir, ve list_topics bir kaynağın dilini adlandırırken
instructions çağıran agent’a search_docs sorgusunu ona uyacak şekilde yazmasını yönlendirir — arama
mekanizmasının kendisinde bir değişiklik değil, çağırana verilen bir yönergedir.
Ölçüm eval/BASELINE.md’dedir
ve fark kıl payı değil: otuz soru korpustan, her biri sorunun ifade edilmediği dildeki bir
sayfa hakkında yazıldı — her yön için on beş. Dördü ilk beşte cevaplanıyor. Otuzdan yirmi yedisi bunun
yerine sıra 1’de ifadenin kendi dilindeki bir sayfayı döndürüyor: model neyin sorulduğunu anlamakta
başarısız olmuyor, ifadenin dilini cevabının üstünde sıralıyor. İki yön de eşit biçimde başarısız
oluyor.
Tanımlayıcılar istisnadır. HALYARD_DISPATCH_TIMEOUT, HLY-4015, X-Halyard-Signature her iki
dilde de aynı dizedir, bu yüzden aramanın anahtar sözcük yarısı onları ne olursa olsun bulur. Kümedeki
bir tanımlayıcı adlandıran dokuz diller-arası sorudan dördü cevaplanıyor; sıradan sorular olarak
ifade edilen yirmi birinden ise hiçbiri cevaplanmıyor.
Bir düzeltme beklemek yerine ne yapılır. Her dili kendi kaynağında tutun ve bir agent’ın aramasını
source, path_prefix ya da version ile kapsamlandırmasına izin verin — her ikisi de iyi cevap veren
iki kaynak, her iki dili de kötü cevaplayan tek bir koleksiyondan iyidir. Bilinen iki çözüm de zaten
ölçülmüştür: hibrit arama (yukarıda) diller-arası tanımlayıcı getirimini kurtardı ve hiçbir doğal dil
sorusunu kurtarmadı; SEARCH_RERANK arkasındaki çok dilli bir cross-encoder rerank’i diller-arası
recall@5’i %13,3’ten %33,3’e taşıdı — yine de bundan önceki gömme modelinin ulaştığı %42,9’un altında —
ve on üç sıradan sorunun sıra-1 cevabına ve bir aramanın gecikmesinin 12 ms’den 1,2 sn’ye çıkmasına mal oldu.
Varsayılan olarak kapalıdır ve kapalı kalmalıdır. Ek bir index olarak ikinci, çeviri üzerine eğitilmiş
bir encoder bunu gerçekten düzeltirdi — kabaca dört katı bir indirme, ikinci bir vektör kolonu, her
kurulumda tam bir yeniden indeksleme — ve bu bedel bir dokümantasyon sunucusu için ödemeye değmez.
Diller arası arama korpusunuz için gerekliyse, bu, bu ürünü beklemek için değil, farklı bir araç seçmek
için bir nedendir.
Air-gapped kurulumlar
Varsayılan bir kurulumun yaptığı tek dışa giden istek, tek seferlik model indirmesidir. Onu da kaldırmak için:
- Models volume’unu (
/app/.cache/models) model dosyalarıyla önceden doldurun — örneğin bağlı bir host’ta bir kere çalıştırıp volume’u kopyalayarak. Bunu, air-gapped host’un kullanacağı aynıEMBEDDING_MODELveEMBEDDING_DTYPEile yapın. EMBEDDING_OFFLINE=1ayarlayın.
Sunucu bundan sonra hiçbir zaman indirme denemez ve model eksikse gürültülü biçimde başarısız olur.
Reranker
Opsiyonel reranker (SEARCH_RERANK=on, varsayılan olarak kapalı) ikinci bir modeldir,
SEARCH_RERANK_MODEL (varsayılan Xenova/bge-reranker-base); aynı cache dizinine yüklenir ve aynı
EMBEDDING_OFFLINE tarafından yönetilir. Reranker açıkken ve bayrak ayarlıyken onun dosyalarının da
volume’da önceden bulunması gerekir: cache’i kopyalamadan önce bağlı host’ta SEARCH_RERANK=on ile ve
aynı SEARCH_RERANK_MODEL ve SEARCH_RERANK_DTYPE ile ısıtın.
İmajı ve modelleri taşımak
Bağlı bir host’ta imajı çekin ve bir dosyaya yazın, dosyayı karşıya taşıyın ve yükleyin:
docker pull contextator/contextator:<tag>
docker save --output contextator.tar contextator/contextator:<tag>
# air-gapped host'ta
docker load --input contextator.tar
latest değil, çalıştırdığınız tag’i kullanın; böylece iki host sürümde anlaşır. Models volume’u imajın
parçası değildir: onu ayrıca kopyalayın (varsayılan volume contextator-models’tır) ya da
CONTEXTATOR_MODELS_PATH ile bir dizin bağlayın.
Host’tan hâlâ dışarı çıkanlar
| Kaynak türü ya da özellik | Dışa giden istek |
|---|---|
Gömme, varsayılan local model |
Cache doldurulduktan sonra hiçbiri; aksi hâlde Hugging Face Hub’dan tek seferlik model indirmesi |
EMBEDDING_TOKENIZER ile adlandırılan tokenizer (EMBEDDING_PROVIDER=openai ile) |
Cache’te yoksa Hugging Face Hub’dan indirilir; EMBEDDING_OFFLINE’a tabidir ve bulunamazsa açılış durur |
| Reranker | Cache doldurulduktan sonra hiçbiri; aksi hâlde Hugging Face Hub’dan kendi tek seferlik model indirmesi |
EMBEDDING_PROVIDER=openai ile gömme |
Doküman metni ve sorgular, EMBEDDING_BASE_URL’e (siz değiştirmediyseniz OpenAI) |
| Yerel dizin, upload | Hiçbiri |
| Git deposu | Git host’unuz, HTTP(S) üzerinden, her senkronizasyonda ve webhook ile tetiklenen birinde |
| Notion | Notion’ın API’si, her senkronizasyonda |
| Confluence | Confluence örneğiniz, her senkronizasyonda |
| Doküman sitesi | İşaret ettiğiniz site ve onun robots.txt’i |
Uzak kaynaklar, onları kuran tarayıcıdan değil bu sunucudan çekilir; dolayısıyla bunlardan birine ihtiyaç duyan air-gapped bir host, o uzak host’a bir yola ihtiyaç duyar, başkasına değil.
Performans notları
- Gömme CPU’ya bağlıdır ve indekslemenin yavaş kısmıdır; aynı anda tek bir projenin indekslenmesinin nedeni budur.
EMBEDDING_BATCH_SIZE(varsayılan 16), her çağrıda kaç parçanın gömüleceğini denetler.- Bir sorgu tam olarak tek bir kısa metni gömer, bu yüzden arama gecikmesine model değil veritabanı hakimdir.
- Model, başlangıçta arka planda yüklenir — pano yüklenirken de çalışır, ama indeksleme ve arama onu bekler.