README.md

---
license: apache-2.0
language:
- tr
library_name: PyLate
pipeline_tag: sentence-similarity
base_model: moganai/MoganBERT-Embed
tags:
- ColBERT
- arxiv:2608.26344
- PyLate
- sentence-transformers
- late-interaction
- retrieval
- turkish
- loss:Distillation
---

<p align="center">
  <img src="banner.png" alt="Mogan-ColBERT-TR" width="600"/>
</p>

<p align="center">
  <a href="https://huggingface.co/papers/2608.26344"><img src="https://img.shields.io/badge/📄_Paper-arXiv-B31B1B?style=flat-square" alt="Paper"/></a>
  <a href="https://moganai.github.io/"><img src="https://img.shields.io/badge/🌐_Blog-MoganAI-2E7D5B?style=flat-square" alt="Blog"/></a>
  <a href="https://huggingface.co/collections/moganai/moganbert"><img src="https://img.shields.io/badge/🤗_Model_Collection-2C3E50?style=flat-square" alt="Model Collection"/></a>
</p>

# Mogan-ColBERT-TR

Mogan-ColBERT-TR is a 148.9M-parameter Turkish multi-vector retriever with late interaction. Instead of one vector per text, it keeps the representation at the token level through a 768→128 projection and scores with MaxSim. Queries are padded to 32 tokens with `[MASK]`; documents are encoded up to 512.

It is initialized from [MoganBERT-Embed](https://huggingface.co/moganai/MoganBERT-Embed) — a ModernBERT trained from scratch on an entirely Turkish corpus, not a fine-tune of a foreign base.

## Usage

```bash
pip install -U pylate
```

```python
from pylate import indexes, models, retrieve

model = models.ColBERT(model_name_or_path="moganai/Mogan-ColBERT-TR")
index = indexes.PLAID(index_folder="pylate-index", index_name="index", override=True)

documents_ids = ["1", "2", "3"]
documents = ["birinci belge metni", "ikinci belge metni", "üçüncü belge metni"]

index.add_documents(
    documents_ids=documents_ids,
    documents_embeddings=model.encode(documents, batch_size=32, is_query=False),
)

retriever = retrieve.ColBERT(index=index)
queries_embeddings = model.encode(["örnek sorgu"], batch_size=32, is_query=True)
print(retriever.retrieve(queries_embeddings=queries_embeddings, k=10))
```

For reranking use `pylate.rank.rerank`. A multi-vector index is tens of times larger than a dense one, so in production the recommended setup is two-stage: candidate generation with [MoganBERT-Embed](https://huggingface.co/moganai/MoganBERT-Embed), reranking with this model.

## Training

Single-epoch KL distillation from the `bge-reranker-v2-m3` cross-encoder over 1 positive and 7 mined hard negatives, on 1×H100. The optimizer uses two parameter groups — encoder 1e-5, projection 1e-4 — since the projection starts random while the encoder does not.

Training data is title→passage pairs carved out of our pretraining corpus plus two Turkish question-based retrieval sets. Passages are split in the character domain at sentence boundaries rather than by decoding cut token lists. Negatives are mined in the MoganBERT-Embed embedding space and filtered by three rules together: skip the top 10, drop candidates sharing the query's group identifier, and drop anything above 0.95 cosine. The group mask matters — a second passage from the same document ranks high for the same title and is not a negative.

## Results

TurkColBERT, official pipeline (PLAID index, exact MaxSim, `document_length=300`, `k=100`). None of the five datasets appears in the training pool, so all results are clean zero-shot.

<img src="assets/turkcolbert_en.jpg" alt="TurkColBERT" width="850"/>

Averaged over the five datasets: 31.81 nDCG@10, 35.53 nDCG@100, 56.98 Recall@100, 25.13 mAP. The benchmark evaluates at `document_length=300` while the model was trained at 512, so these are a lower bound.

## Model Family

| Model | Params | Purpose |
|---|---:|---|
| [MoganBERT-TR](https://huggingface.co/moganai/MoganBERT-TR) | 149.4M | Base encoder |
| [MoganBERT-Embed](https://huggingface.co/moganai/MoganBERT-Embed) | 149M | Single-vector embeddings |
| [**Mogan-ColBERT-TR**](https://huggingface.co/moganai/Mogan-ColBERT-TR) | 148.9M | Multi-vector retrieval (this model) |

## Citation

```bibtex
@article{yilmaz2026mogancolbert,
  title   = {MoganColBERT-TR: A Late-Interaction Multi-Vector Retrieval Model for Turkish},
  author  = {Furkan Yilmaz and Habibe Aleyna Tasdemir and Muhammed Faruk Gozay},
  year    = {2026}
}
```

---
---

# Mogan-ColBERT-TR (Türkçe)

Mogan-ColBERT-TR, geç etkileşimli, 148.9M parametreli bir Türkçe çok vektörlü retriever'dır. Metin başına tek vektör yerine temsili 768→128 izdüşümü ile token seviyesinde tutar ve MaxSim ile skorlar. Sorgular `[MASK]` ile 32 tokena tamamlanır, belgeler 512'ye kadar kodlanır.

[MoganBERT-Embed](https://huggingface.co/moganai/MoganBERT-Embed)'den başlatılmıştır — tamamen Türkçe bir külliyat üzerinde sıfırdan eğitilmiş bir ModernBERT; yabancı bir modelin ince ayarı değil.

## Kullanım

```bash
pip install -U pylate
```

```python
from pylate import indexes, models, retrieve

model = models.ColBERT(model_name_or_path="moganai/Mogan-ColBERT-TR")
index = indexes.PLAID(index_folder="pylate-index", index_name="index", override=True)

belge_idleri = ["1", "2", "3"]
belgeler = ["birinci belge metni", "ikinci belge metni", "üçüncü belge metni"]

index.add_documents(
    documents_ids=belge_idleri,
    documents_embeddings=model.encode(belgeler, batch_size=32, is_query=False),
)

retriever = retrieve.ColBERT(index=index)
sorgu_gommeleri = model.encode(["örnek sorgu"], batch_size=32, is_query=True)
print(retriever.retrieve(queries_embeddings=sorgu_gommeleri, k=10))
```

Yeniden sıralama için `pylate.rank.rerank` kullanın. Çok vektörlü indeks yoğun bir indeksten onlarca kat büyüktür; üretimde önerilen kurulum iki aşamalıdır: aday üretimi [MoganBERT-Embed](https://huggingface.co/moganai/MoganBERT-Embed) ile, yeniden sıralama bu model ile.

## Eğitim

1×H100 üzerinde, `bge-reranker-v2-m3` çapraz kodlayıcısından 1 pozitif ve 7 zor negatif üzerinde tek epoch'luk KL damıtma. Optimizasyon iki parametre grubu kullanır — encoder 1e-5, izdüşüm 1e-4 — çünkü izdüşüm rastgele başlarken encoder başlamaz.

Eğitim verisi, ön-eğitim külliyatımızdan çıkarılan başlık→pasaj çiftleri ve iki Türkçe soru tabanlı retrieval kümesidir. Pasajlar, kesilmiş token listeleri decode edilerek değil, karakter alanında cümle sınırlarından bölünür. Negatifler MoganBERT-Embed gömme uzayında çıkarılır ve üç kural birlikte uygulanarak filtrelenir: ilk 10'u atla, sorgunun grup kimliğini paylaşan adayları düşür, 0.95 kosinüsün üstündekileri düşür. Grup maskesi önemlidir — aynı belgeden çıkan ikinci pasaj aynı başlık için üst sıralara çıkar ve negatif değildir.

## Sonuçlar

TurkColBERT, resmî hat (PLAID indeksi, tam MaxSim, `document_length=300`, `k=100`). Beş veri kümesinin hiçbiri eğitim havuzunda yer almaz, dolayısıyla tüm sonuçlar temiz sıfır-atıştır.

<img src="assets/turkcolbert.jpg" alt="TurkColBERT" width="850"/>

Beş veri kümesinin ortalaması: 31.81 nDCG@10, 35.53 nDCG@100, 56.98 Recall@100, 25.13 mAP. Kıyaslama `document_length=300` ile ölçüm yapar, model ise 512 ile eğitildi; bu sayılar bir alt sınırdır.

## Model Ailesi

| Model | Parametre | Amaç |
|---|---:|---|
| [MoganBERT-TR](https://huggingface.co/moganai/MoganBERT-TR) | 149.4M | Temel encoder |
| [MoganBERT-Embed](https://huggingface.co/moganai/MoganBERT-Embed) | 149M | Tek vektörlü gömme |
| [**Mogan-ColBERT-TR**](https://huggingface.co/moganai/Mogan-ColBERT-TR) | 148.9M | Çok vektörlü retrieval (bu model) |

## Atıf

```bibtex
@article{yilmaz2026mogancolbert,
  title   = {MoganColBERT-TR: A Late-Interaction Multi-Vector Retrieval Model for Turkish},
  author  = {Furkan Yilmaz and Habibe Aleyna Tasdemir and Muhammed Faruk Gozay},
  year    = {2026}
}
```