# İndeksleme

> Bir indeksleme çalışmasında ne olur, değişmemiş bir projeyi yeniden indekslemek neden hiçbir şeyi gömmez, belgeler nasıl parçalanır ve indeksleme sürerken neler reddedilir.

- Güncelleme: 2026-09-21
- Kaynak: https://contextator.com/tr/docs/indexing/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
İndeksleme, dosyalarınızı bir ajanın arayabileceği bir şeye dönüştüren adımdır. Arka planda, aynı anda
tek bir proje üzerinde çalışır ve yalnızca gerçekten gereken işi yapar.

## Bir çalışma sırasında ne olur

1. **Sync.** Projenin her kaynağı sırayla senkronize edilir: git kaynakları branch ucunu çeker, Notion
   kaynakları değişen sayfaları çeker, local ve upload kaynaklarının çekecek bir şeyi yoktur. Başarısız
   olan bir kaynak kendi satırında raporlanır ve çalışma diğerleriyle devam eder.
2. **Scan.** Her kaynağın dizini, seçtiği dosya türleri için taranır. Dotfile'lar, `node_modules`,
   `dist`, `build`, `vendor`, `__pycache__`, dışarı kaçan symlink'ler ve `IGNORE_GLOBS` eşleşmeleri
   atlanır. Toplanan her yol, kaynağın adıyla önceklenir.
3. **Compare.** Her dosya okunur ve hash'lenir (sha256). Hash'i değişmemiş dosyalar **atlanır** —
   parçalama yok, gömme yok. Değişen ve yeni dosyalar devam eder.
4. **Transform and chunk.** Kaynağın içerik türü uygulanır, ardından dosya parçalara bölünür
   (aşağıya bakın).
5. **Embed.** Her parça toplu olarak gömülür ve veritabanına yazılır; bu, o belgenin önceki
   parçalarının yerini tek bir transaction içinde alır.
6. **Clean up.** Dosyası ortadan kalkan belgeler silinir — kaynağı hiç taranamadıysa bu istisnadır,
   o durumda belgeler bilerek tutulur.
7. **Finalise.** Sayaçlar yeniden hesaplanır, projenin durumu ayarlanır ve çalışma geçmişe kaydedilir.

## Varsayılan olarak artımlı (incremental)

Değişmemiş bir projeyi yeniden indekslemek **hiçbir şeyi** gömmez. Çalışma geçmişi bunu açıkça
gösterir:

```
12 unchanged · 0 updated
```

Bu, sık yeniden indekslemeyi ucuz kılan şeydir — bir webhook'tan, bir cron job'dan ya da yalnızca emin
olmadığınızda düğmeye basmaktan.

| Eylem | Etki |
|--------|--------|
| **Re-index** | Artımlı: yalnızca değişen dosyalar yeniden gömülür |
| **Force re-index** | Projenin her parçasını düşürür ve her şeyi yeniden kurar |

Gömme modeli değiştiğinde de otomatik olarak tam bir yeniden indeksleme yapılır — bkz.
[Gömme Modelleri](/tr/docs/embedding-models/).

### Ne zaman zorlanmalı

- `CHUNK_MAX_TOKENS` ya da `CHUNK_OVERLAP_TOKENS`'ı değiştirdikten sonra, bunları değişmemiş dosyalara
  da uygulamak için.
- İndeksin, hash'lemenin göremeyeceği bir biçimde tutarsız olduğundan şüphelendiğinizde.

Bir kaynağın **content type**'ını değiştirmek zorlama gerektirmez — Contextator o kaynağın hash'lerini
sizin için düşürür.

## Belgeler nasıl parçalanır

Getirme kalitesi büyük ölçüde parçalama kalitesidir, bu yüzden bu kısım özenle tasarlandı:

- **Frontmatter ayrıştırılır** ve içindeki bir `title:`, ilk `# heading`'e karşı kazanır; o da
  güzelleştirilmiş bir dosya adına karşı kazanır.
- **MDX temizlenir**: `import`/`export` ifadeleri, JSX yorumları ve tek başına duran component
  etiketleri `.mdx` dosyalarından kaldırılır — ama asla fenced code içinden değil.
- **Belge, başlıklarda bölünür** (`#`'den `####`'e kadar) ve her parça, üstündeki başlıkların bir
  **kırıntısını** (breadcrumb) taşır: `Guide > Install > Docker`.
- **Aşırı büyük bölümler**, paragraflardan ve fenced code bloklarından, ardışık parçalar arasında küçük
  bir overlap ile paketlenir. Kod blokları, tek bir blok zaten çok büyük olmadıkça asla blok ortasından
  bölünmez ve overlap kodu asla tekrarlamaz.
- **Küçük parçalar** komşusuyla birleştirilir, böylece tek başına bir başlık kendi başına bir parça
  olmaz.
- Gömme modeline verilen metin **kırıntı + içerik**tir, böylece en tanımlayıcı kelimeler her zaman
  modelin penceresinin içinde kalır.

Arama sonuçlarında gördüğünüz kırıntı budur ve bir alıntının bir parça değil bir bütün gibi
okunmasının nedeni de budur.

### Parça boyutu

| Ayar | Varsayılan | Notlar |
|---------|---------|-------|
| `CHUNK_MAX_TOKENS` | `96` | Yaklaşıklanmaz; embedding modelinin kendi tokenizer'ıyla sayılır |
| `CHUNK_OVERLAP_TOKENS` | `24` | `CHUNK_MAX_TOKENS`'tan küçük olmalıdır |

Varsayılan model 512 token okur, yani `96` onun penceresinin yanından bile geçmez — ve bu bilinçlidir.
**Altın kümede en iyi ölçülen değer `96`'dır**; pencereyi doldurmak *daha kötü* ölçer, çünkü uzun bir
parça tek bir vektörde ortalanır ve hiçbir şeye tam olarak işaret etmez. Bütçe, altın kümede 496'dan
64'e kadar taranmıştır, ve 88 ile 108 arası hepsi aynı ölçüldü — 96, o platonun kenarı değil ortasıdır.
Karakter sayısından yaklaşıklanmak yerine embedding modelinin kendi tokenizer'ıyla sayılır, çünkü yerini
aldığı yaklaşıklama metnin kendisinden etkileniyordu: retrieval korpusunda İngilizceyi %17, Türkçeyi ise
%11 eksik sayıyordu. Başlık kırıntısı ve, varsayılan modelde, her indekslenen parçanın önüne eklenen `passage: ` öneki
de bütçeden düşülür (bkz. [Arama gerçekte nasıl
çalışır](/tr/docs/embedding-models/#arama-gerçekte-nasıl-çalışır)) — ikisi de modelin okuduğunun bir
parçasıdır, bu yüzden ikisi de sayılır. OpenAI'da iki ayarı da yükseltin; onun penceresi 8191'dir. Birini
değiştirin, yeniden başlatın, sonra **Force re-index** yapın; mevcut bir proje o zamana kadar eski
parçalarını korur.

[`eval/`](https://github.com/Contextator/Contextator/tree/main/eval) içindeki altın kümede, tokenizer ve
bütçe çalışması `recall@5`'i %70,8'den %79,2'ye taşıdı, ve 96/24 ile `multilingual-e5-small`'a geçiş onu
`recall@1` %77,1 iken %85,4'e çıkardı.

## Bir çalışmayı izlemek

Proje satırı; faz, tamamlanan/toplam dosya sayısı ve gömülen parça sayısıyla bir ilerleme çubuğu
gösterir. Fazlar:

| Faz | Anlamı |
|-------|---------|
| `queued` | İndeksleyiciyi bekliyor (aynı anda tek bir projeyle ilgilenir) |
| `syncing` | Git / Notion'dan getiriliyor, kaynak kökleri doğrulanıyor |
| `scanning` | Dizinler taranıyor ve mevcut belge listesi okunuyor |
| `embedding` | Hash'leniyor, parçalanıyor ve gömülüyor |
| `finalizing` | Yeniden sayılıyor ve sonuç yazılıyor |

## Çalışma geçmişi

**Index runs** paneli son 20 çalışmayı tutar: ne zaman, artımlı mı zorlama mı, ne değişti
(`12 unchanged · 3 updated · 1 removed`), ne kadar sürdü ve varsa hangi hata. Canlı ilerleme
görünümünün aksine bu, yeniden başlatmalara dayanır — *"dün geceki webhook gerçekten çalıştı mı?"*
sorusunu yanıtlayacağınız yer burasıdır.

`GET /api/projects/:id/runs` üzerinden de erişilebilir — bkz. [Admin API](/tr/docs/admin-api/).

## Kuyruk

Gömme CPU'ya bağlı olduğu ve ikisini birden çalıştırmak ikisini de yavaşlatacağı için, aynı anda tek
bir proje indekslenir. Kuyruktaki bir proje hangi projeyi beklediğini gösterir. Aynı projeyi iki kez
kuyruğa almak, ikinci bir çalışma başlatmak yerine zaten sürmekte olan çalışmayı döndürür.

## Bir çalışma sırasında reddedilenler

İndeksi tutarlı tutmak için, bir proje indekslenirken şunlar çakışma hatasıyla reddedilir:

- projeyi silmek;
- kaynaklarından birini silmek;
- ona bir upload commit etmek.

Çalışmanın bitmesini bekleyin — ya da bitmesine izin verip yeniden deneyin; panodaki düğmeler
kendilerini devre dışı bırakır.