AG
EN

// work / mizan

Mizan

Kur'an için hibrit bir arama ve metin analizi motoru. Arapça üzerinde ISRI kök bulucuyla BM25 tarzı anahtar kelime araması, üç pgvector diller-arası gömme yolu, Reciprocal Rank Fusion ve Tanzil külliyatına karşı doğrulanan harf/Ebced hesapları.

Rol
Yazar ve sürdürücü
Tarih
Oca 2026

Yığın

  • Python 3.11
  • FastAPI
  • PostgreSQL
  • pgvector
  • Redis 7
  • Next.js 16
  • TypeScript
  • SQLAlchemy (async)
  • ISRI stemmer
  • intfloat/multilingual-e5-base

Problem

Kur'an'ı iyi aramak ve analiz etmek göründüğünden zordur. Arapça biçimbilimsel açıdan zengindir, bu yüzden naif anahtar kelime araması bariz eşleşmeleri kaçırır; kullanıcılar yalnızca Arapça değil, Türkçe ve İngilizce de sorgular; harf sayıları ve Ebced toplamları yaygın biçimde dolaşır ama nasıl hesaplandıkları gösterilmediği için çoğu zaman yanlıştır.

Kısıtlar

  • Her sayı ve Ebced toplamı, sadece iddia edilmek yerine yetkili bir külliyata karşı harf-harf doğrulanabilir olmalıdır.
  • Sorgular Arapça'nın yanı sıra Türkçe ve İngilizce de gelir; motor, harici bir arama motoru olmadan diller arasında köprü kurmalıdır.

Yaklaşım

Mizan, klasik bilgi erişimini modern diller-arası gömme vektörleriyle birleştirir. Erişici dört yolu paralel çalıştırır: intfloat/multilingual-e5-base (768 boyut) kullanan üç pgvector kosinüs-benzerliği yolu (Arapça, İngilizce, Türkçe) ve ISRI Arapça kök bulucu içeren bir PostgreSQL tsvector/GIN anahtar kelime yolu. Dört sıralı liste, Reciprocal Rank Fusion (RRF) ile kaynaştırılır; üstüne isteğe bağlı bir çapraz kodlayıcı yeniden sıralayıcı (ms-marco-MiniLM) eklenir. Harf sayımı ve Ebced hesabı, yüklenme sırasında SHA ile doğrulanan külliyat bütünlüğü eşliğinde Tanzil külliyatına karşı harf-harf doğrulanır.

Önemli kararlar

  • Salt sözlüksel ya da salt anlamsal arama yerine RRF'li dört yollu hibrit erişim

    pgvector yolları (Arapça, İngilizce, Türkçe), anahtar kelime aramasının kaçırabileceği anlamsal ve diller-arası eşleşmeleri yakalar. ISRI kök bulucuyla tsvector/GIN yolu, Arapça kaynak üzerinde biçimbilim duyarlı kesin geri çağırım sağlar. Hiçbiri tek başına hem bir âlimin tam-ifade aramasını hem de sıradan bir Türkçe soruyu kapsamaz. RRF, yollar arasında skor kalibrasyonu gerektirmeden sıralı listeleri kaynaştırır.

  • Her sonuca metodoloji meta-verisi ekle

    Her sonuç, onu üretmek için kullanılan sayım yöntemini ve modeli taşır; böylece sayılar yeniden üretilebilir. Külliyat, hesaplama başlamadan önce herhangi bir değişikliği tespit etmek için yüklenme sırasında SHA doğrulamasından geçer.

Mimari

Arapça, Türkçe veya İngilizce bir sorgu FastAPI servisine girer. Hibrit erişici üç pgvector kosinüs yolunu (Arapça, İngilizce, Türkçe) ve bir tsvector/GIN anahtar kelime yolunu (ISRI kök bulucuyla) paralel çalıştırır, sonuçları RRF ile kaynaştırır, isteğe bağlı çapraz kodlayıcı yeniden sıralayıcıyı uygular ve sıralama sonuçlarını analiz motorunun harf/Ebced sayımlarıyla birlikte döndürür. Her yanıt, kullanılan sayım yöntemini ve modeli içerir.

flowchart LR
  q["Query\nArabic / Turkish / English"]
  svc["FastAPI service"]
  vec_ar["pgvector cosine\n(Arabic embeddings)"]
  vec_en["pgvector cosine\n(English embeddings)"]
  vec_tr["pgvector cosine\n(Turkish embeddings)"]
  kw["tsvector/GIN\n+ ISRI stemmer"]
  rrf["Reciprocal Rank Fusion"]
  rerank["Cross-encoder reranker\n(optional, ms-marco-MiniLM)"]
  analysis["Analysis engine\nletter + Abjad counts\n(SHA-checked corpus)"]
  out["Result\n(method + model metadata)"]

  q --> svc
  svc --> vec_ar --> rrf
  svc --> vec_en --> rrf
  svc --> vec_tr --> rrf
  svc --> kw --> rrf
  rrf --> rerank --> out
  svc --> analysis --> out
Üç pgvector kosinüs yolu ve bir tsvector/GIN anahtar kelime yolu, RRF ve isteğe bağlı yeniden sıralayıcı ile kaynaştırılarak SHA doğrulamalı harf ve Ebced sayımlarıyla birleştirilir.

Sonuç

Mizan, kapsamlı bir test paketiyle bir FastAPI servisi ve Next.js ön yüzü olarak gelir. Harf sayıları ve Ebced toplamları Tanzil külliyatına karşı doğrulanır, külliyat yüklenme sırasında SHA doğrulamasından geçer ve her sonuç kullanılan sayım yöntemini ve modeli bildirir. Servis, bir Hetzner sunucusunda mizan.rollingcatsoftware.com ve mizan-api.rollingcatsoftware.com adreslerinde canlıdır.

Rakamlarla

  • 4 Erişim yolu
  • 3 Köprülenen sorgu dili
  • Tanzil corpus Sayım doğrulaması
  • method + model Sonuç başına metodoloji etiketi

Aşağıdaki yapılandırılmış bölümler Türkçe mevcuttur; ayrıntılı anlatım İngilizce yazılmıştır. Tam Türkçe çeviri henüz mevcut değildir.

Derinlemesine

Mizan (“the scale” / “the balance”) combines classical information retrieval with modern cross-language embeddings to make Quranic text searchable and its letter-level statistics verifiable.

Why hybrid retrieval

Arabic is morphologically rich: the same root surfaces in many inflected forms. A plain keyword index misses obvious matches, so Mizan runs a PostgreSQL tsvector/GIN path with an ISRI Arabic stemmer to get morphology-aware lexical recall on the Arabic source. But a scholar’s exact-phrase lookup and a casual Turkish question are different problems. The second needs to bridge languages, which is what the three pgvector cosine paths do: one each for Arabic, English, and Turkish, all using intfloat/multilingual-e5-base (768-dim). Reciprocal Rank Fusion combines the four ranked lists without requiring score calibration between paths. An optional cross-encoder reranker (ms-marco-MiniLM) sits on top when precision matters more than latency.

Verifiable, not just asserted

The part that matters most for trust is the numbers. Letter counts and Abjad (numerological) totals circulate widely and are frequently wrong because nobody shows the work. Mizan computes them and verifies them letter-by-letter against the Tanzil corpus. The corpus is SHA-checked at load time so any file-level modification is caught before computation begins. Every search and analysis result carries the counting method and the model version used to produce it, so the numbers are reproducible.

Where it runs

Mizan is a FastAPI service (Python 3.11, SQLAlchemy async, PostgreSQL + pgvector HNSW, Redis 7) with a Next.js 16 / React 19 / Tailwind front end, deployed on a Hetzner server. The front end is live at mizan.rollingcatsoftware.com and the API at mizan-api.rollingcatsoftware.com. The source is public on GitHub.

Tüm vaka çalışmaları