md2rag

Markdown to RAG-ready data
Complete pipeline: Split → Normalize → Embed → Vector DB

---

Nedir?

md2rag, Markdown dökümanlarınızı RAG (Retrieval Augmented Generation) sistemleri için hazır hale getiren modern bir CLI aracıdır. Tek bir komutla markdown'ınızı bölebilir, temizleyebilir, embedding'ler oluşturabilir ve doğrudan Qdrant vector database'e yükleyebilirsiniz.

---

Hızlı Başlangıç

Kurulum

# Projeyi klonlayın
git clone https://github.com/tunjayoff/md2rag.git
cd md2rag

# Bağımlılıkları yükleyin
pip install -e .

Kullanım

# Markdown'dan JSON'a
md2rag pipeline cilt1/DİB_İlmihal_Cilt1.md --depth 4 --rename-headers --format jsonl

# Embedding oluştur
md2rag embed output/DİB_İlmihal_Cilt1_depth4_normalized_renamed.jsonl

# Qdrant'a yükle
md2rag qdrant-upload output/*_embeddings.json --collection my_kb

---

Mimari

md2rag/
├── cli.py              # Ana CLI giriş noktası
├── __main__.py         # Paket çalıştırılabilirliği
├── config/             # Konfigürasyon yönetimi
├── core/               # Temel işlevler
│   ├── text_processor.py     # Text normalizasyon
│   └── markdown_processor.py # Markdown parsing
├── services/           # Harici servisler
│   ├── embedding_service.py  # DeepInfra entegrasyonu
│   └── qdrant_service.py     # Qdrant entegrasyonu
├── commands/           # CLI komutları
│   ├── normalize.py
│   ├── split.py
│   ├── update_pages.py
│   ├── pipeline.py
│   ├── embed.py
│   ├── qdrant_upload.py
│   └── audit_pages.py
└── utils/              # Yardımcı fonksiyonlar

Tasarım İlkeleri

• Single Responsibility - Her modül tek sorumluluk
• Error Handling - Kapsamlı hata yönetimi
• Logging - Detaylı loglama
• Configuration - Merkezi konfigürasyon

---

📂 Output Klasör Yapısı

output/
├── split/           # Bölünmüş markdown dosyaları
│   ├── DİB_Fetvalar_depth2_raw_renamed.json
│   ├── DİB_İlmihal_Cilt1_depth4_raw_renamed.json
│   └── DİB_İlmihal_Cilt2_depth4_raw_renamed.json
├── updated/         # Sayfa numaraları güncellenmiş dosyalar
│   ├── DİB_Fetvalar_depth2_raw_renamed_updated_pages.json
│   ├── DİB_İlmihal_Cilt1_depth4_raw_renamed_updated_pages.json
│   └── DİB_İlmihal_Cilt2_depth4_raw_renamed_updated_pages.json
└── embeddings/      # Embedding'ler eklenmiş dosyalar
    ├── DİB_Fetvalar_depth2_raw_renamed_updated_pages_embeddings.json
    ├── DİB_İlmihal_Cilt1_depth4_raw_renamed_updated_pages_embeddings.json
    └── DİB_İlmihal_Cilt2_depth4_raw_renamed_updated_pages_embeddings.json

---

pipeline - Tam İşlem Hattı

md2rag pipeline <markdown_file> [options]

Örnekler:

# Temel kullanım
md2rag pipeline document.md

# Tam özelliklerle
md2rag pipeline document.md \
  --depth 4 \
  --normalize \
  --rename-headers \
  --format jsonl \
  --book-title "My Book"

update-pages - Sayfa Numaralarını Güncelleme

md2rag update-pages <json_file> [options]

Örnekler:

# Temel (TOC otomatik bulunur)
md2rag update-pages data.json

# Özel TOC dosyası
md2rag update-pages data.json --toc toc.json

# Özel çıktı
md2rag update-pages data.json --output updated_data.json

embed - Embedding Oluşturma

md2rag embed <json_file> [options]

Örnekler:

# Temel
md2rag embed data.json

# Özel model ve batch
md2rag embed data.json \
  --model Qwen/Qwen3-Embedding-8B \
  --batch-size 50 \
  --keep-original

qdrant-upload - Vector DB Yükleme

md2rag qdrant-upload <embeddings_file> --collection <name> [options]

Örnekler:

# Temel
md2rag qdrant-upload embeddings.json --collection my_kb

# Tüm seçeneklerle
md2rag qdrant-upload embeddings.json \
  --collection knowledge_base \
  --distance Cosine \
  --batch-size 100 \
  --use-original

normalize - Metin Normalizasyonu

md2rag normalize <json_file> [options]

Örnekler:

# Temel normalizasyon
md2rag normalize data.json

# Özel ayarlar
md2rag normalize data.json \
  --lowercase \
  --remove-accents \
  --remove-markdown

interactive - İnteraktif Mod

md2rag interactive

İnteraktif menü ile tüm işlemleri adım adım gerçekleştirin. Otomatik config algılama ve Qdrant HNSW ayarları desteği ile.

Özellikler:

• Otomatik qdrant_config.yaml algılama
• HNSW konfigürasyonu desteği
• Batch işleme ayarları
• Tüm pipeline adımlarını tek yerden yönetme

audit-pages - Sayfa Anomali Denetimi

md2rag audit-pages [input_path] [options]

JSON dosyalarındaki sayfa numaralandırma anomalilerini denetler.

Örnekler:

# Varsayılan `output/updated` klasörünü denetle
md2rag audit-pages

# Belirli bir dosyayı denetle
md2rag audit-pages output/updated/my_data.json

# Ayrıntılı çıktı ile denetle
md2rag audit-pages --verbose

Anomaliler:

• Eksik Sayfa Numarası: page_number alanı olmayan kayıtlar.
• Sayfa Numarası Gerilemesi: Önceki kayıttan daha düşük sayfa numarasına sahip kayıtlar.
• Bölüm Duraklaması: Yeni bir bölümün önceki bölümle aynı sayfada başlaması.
• Hayalet Tekrarlar: Farklı bölümlerde aynı sayfada görünen başlıklar.
• Aşırı Tekrar: Aynı sayfa numarasının art arda 3'ten fazla tekrar etmesi.

---

Konfigürasyon

config.yaml

output:
  format: jsonl
  indent: 2

metadata:
  book_title: "DİB İlmihal"
  fields:
    BookTitle: {source: book_title, required: true}
    Topic: {source: h1, strip_markdown: true}
    SubTopic: {source: h2, strip_markdown: true}

processing:
  normalize:
    lowercase: true
    remove_accents: true
    remove_markdown: true
  split:
    default_depth: 6
    filter_empty: true

.env

DEEPINFRA_API_KEY=your_key
QDRANT_URL=https://cluster.qdrant.io
QDRANT_API_KEY=your_key

qdrant_config.yaml

qdrant:
  url: https://your-cluster.qdrant.io:6333
  api_key: your_api_key
  collection:
    name: my_collection
    vector_size: 4096
    distance: Cosine
    on_disk: false
  hnsw_config:
    m: 32
    ef_construct: 400
    full_scan_threshold: 20000
    max_indexing_threads: 0
    on_disk: false

---

Lisans

MIT License

---

Made with ❤️ by Tuncay EŞSİZ
📧 tuncayessiz9@gmail.com