Python ile PDF'yi Markdown'a Dönüştürme

Neden Markdown ve bu iş neden göründüğünden zor

LLM'ler Markdown'ı olağanüstü iyi işler: başlıklar bölüm sınırlarını belirtir, pipe tabloları tablo verilerini hizalı tutar ve listeler liste olarak kalır. Modele PDF'den çıkarılmış ham metni vermek bunların tümünü kaybettirir — PDF ikili dosyasını vermekse çoğu işlem hattı için zaten seçenek değildir. Bu yüzden neredeyse her ciddi RAG yığını, belgeleri parçalama ve gömme öncesinde Markdown'a dönüştürür.

İşin zor kısmı şu: PDF'ler yapı içermez — x/y koordinatlarına yerleştirilmiş karakterler içerir. Bir dönüştürücü hangi satırların başlık olduğunu (yazı tipi boyutundan), hangi kelimelerin tablo oluşturduğunu (hizalamadan) ve okuma sırasının ne olduğunu (düzen analizinden) tersine mühendislikle çıkarmak zorundadır. Kütüphaneler bunu ne kadar iyi yaptıkları konusunda büyük farklılık gösterir; seçim bu yüzden önemlidir.

İkinci bir zorluk: taranmış PDF'ler hiç metin içermez, yalnızca sayfa görüntüleri içerir. Aşağıdaki seçeneklerden yalnızca bazıları bunları OCR ile işleyebilir.

1. Seçenek: PyMuPDF4LLM — hızlı ve hafif

PyMuPDF4LLM, PyMuPDF (fitz) üzerine LLM işlem hatları için özel olarak yazılmış ince bir katmandır: pip install pymupdf4llm, ardından md = pymupdf4llm.to_markdown("doc.pdf") — tek satır ve çok hızlıdır; çoğu belgeyi bir saniyenin çok altında işler.

Başlıkları yazı tipi boyutlarından algılar, tabloları pipe tablosu olarak üretir ve LlamaIndex ya da LangChain'e doğrudan alım için meta verili sayfa parçaları çıkarabilir. Basit düzenlere sahip dijital doğumlu PDF'ler — raporlar, dokümantasyon, sıra dışı biçimlendirmesi olmayan makaleler — için mükemmel bir varsayılandır.

Sınırları: OCR yok, dolayısıyla taranmış sayfalar boş döner. Karmaşık çok sütunlu düzenler ve girift tablolar karışık çıkabilir; çünkü altta yatan sezgisel yöntemler derin düzen analizi yerine hızı önceler. Lisans notu: PyMuPDF AGPL lisanslıdır — iç araçlar için sorun değil, ancak ticari bir ürünün içinde dağıtmadan önce hukuk ekibinize danışın.

2. Seçenek: Marker — en yüksek kalite, GPU ister

Marker; düzen algılama, okuma sırası ve tablo yapısı için derin öğrenme modellerinden oluşan bir işlem hattı kullanır ve açık kaynak seçenekler arasında en sadık Markdown'ı üretir — çok sütunlu akademik makaleleri, karmaşık tabloları ve hatta denklemleri bile işler.

Bedeli altyapıdır: birkaç gigabaytlık model ağırlıkları, makul hız için bir GPU (CPU çalışır ama yavaştır — belge başına çoğu zaman onlarca saniye) ve üretim ya da sunucusuz ortamlara dağıtması gerçek emek isteyen ağır bir bağımlılık ağacı.

Zor belgelerde çıktı kalitesi en önemli öncelikse ve donanımınız varsa Marker'ı seçin — bir GPU makinesinde akademik bir külliyatı toplu dönüştürmek tam onun işi. Hafif bir servis veya sunucusuz bir fonksiyon içinse operasyonel ağırlığı genellikle onu devre dışı bırakır.

3. Seçenek: MarkItDown — Microsoft'un her formata açık dönüştürücüsü

MarkItDown, Microsoft'un açık kaynak "her şeyden Markdown'a" kütüphanesidir: pip install markitdown, ardından MarkItDown().convert("doc.pdf").text_content. Gücü kapsamındadır — aynı API; PDF, DOCX, PPTX, XLSX, HTML ve daha fazlasını dönüştürür; LLM veri hazırlığı için bu yüzden bu kadar hızla yayıldı.

Özellikle PDF'lerde çıkarımı, özel amaçlı seçeneklerden daha basittir: temel metin çıkarma üzerine kuruludur; bu yüzden başlık algılama ve tablo sadakati PyMuPDF4LLM ile Marker'ın gerisinde kalır ve taranmış PDF'ler ek OCR kurulumu ister.

Birçok dosya türünü orta kalitede tek bir bağımlılıkla kapsamanız gerekiyorsa — "insanlar ne yüklerse" kabul etmek zorunda olan bir iç alım betiği gibi — MarkItDown'ı seçin; mümkün olan en iyi PDF çıktısı için değil.

4. Seçenek: Barındırılan bir API — hiç bağımlılık yok

Dördüncü seçenek dönüştürmeyi yerelde hiç çalıştırmamaktır: PDF'yi bir ayrıştırma API'sine POST edin ve Markdown'ı geri alın. ParseJet ile: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — JSON yanıtının "text" alanı Markdown'dır.

Bu yolda taranmış sayfalar için OCR yerleşiktir, kurulacak model ağırlığı veya yerel kütüphane yoktur ve sunucusuz bir fonksiyonda, konteynerde veya not defterinde birebir aynı çalışır. AGPL sorusunu da tamamen devre dışı bırakır. Ödünleşim, bir ağ gidiş-dönüşü ve ücretsiz katmandan sonra belge başına maliyettir (ayda 300 kredi ücretsiz; bir PDF 3 kredi harcar).

İşlem hattının bugün çalışmasını istiyorsanız, PDF'lerinizin arasında taranmış olanlar varsa veya ağır bağımlılıkların sorun olduğu bir yere — Lambda, Cloud Run, Vercel — dağıtım yapıyorsanız API'yi seçin.

Hangisini kullanmalısınız?

Dijital doğumlu PDF'ler, basit-orta düzeyde düzenler ve hız önemliyse: PyMuPDF4LLM. Saf Python'daki en iyi emek/kalite oranı budur.

Zor belgeler (çok sütunlu makaleler, karmaşık tablolar) ve elinizde bir GPU varsa: Marker. Çıktı kalitesinde onu geçen açık kaynak yok.

Tek kütüphaneden geçen birçok farklı dosya türü ve orta düzey kalite yeterliyse: MarkItDown.

Karışımda taranmış PDF'ler, sunucusuz dağıtım veya bağımlılık yönetimine hiç niyet yoksa: barındırılan API. Tek HTTP çağrısı, OCR dahil, her belge için aynı çıktı şeması.

Tam örnek: PDF klasöründen Markdown dosyalarına

Hangi yolu seçerseniz seçin işlem hattının şekli aynıdır — yinele, dönüştür, yaz. İşte API ile hali (yerelde çalıştırmak için içteki çağrıyı pymupdf4llm.to_markdown() ile değiştirin):

import httpx; from pathlib import Path — ardından Path("pdfs/").glob("*.pdf") içindeki her pdf için: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": pdf.read_bytes()}); Path("md/", pdf.stem + ".md").write_text(resp.json()["text"], encoding="utf-8").

RAG alımı için Markdown'ı sabit karakter sayıları yerine başlıklara göre parçalayın — başlık farkındalıklı parçalar bölümleri bütün tutar ve belirgin biçimde daha isabetli geri getirilir. Dönüştürme adımını özenle yapmaya değmesinin nedeni tam da bu yapısal sadakattir.