Docling 2.119.0 ile PDF’yi Yerelde Markdown’a Çevirme: Gerçek Test

Kısa sonuç: Docling 2.119.0, PDF, DOCX, PPTX ve başka belge türlerini yapay zekâ aramalarında kullanılabilecek Markdown, JSON veya parçalara dönüştüren açık kaynak bir belge işleme aracı. Dört sayfalık, etiketlenmemiş bir PDF’yi geçici dizinde CPU ile gerçekten dönüştürdüm: işlem başarılı oldu ve 854 kelimelik Markdown üretti. Ancak 121,32 saniye sürdü, yaklaşık 4,0 GB tepe bellek kullandı, ilk başlığı bozdu ve varsayılan gömülü görseller Markdown dosyasını 1,2 MB’a çıkardı. Yani Docling güçlü bir başlangıç noktası; erişilebilir PDF düzeltme aracı ya da hatasız veri çıkarma sistemi değil.

Docling ne işe yarar, kimler için?

Bir PDF’yi doğrudan bir sohbet botuna yüklemek kolay görünür. Fakat çok sütunlu sayfalar, tablolar, taranmış metinler ve görseller okuma sırasını bozabilir. Docling belgenin sayfa düzenini, metnini, tablolarını ve resimlerini ortak bir belge modeline çevirir. Bu modelden Markdown, JSON, HTML, düz metin, DocTags veya bölüm parçası üretilebilir. Sonuç daha sonra bir yerel arama sistemine, RAG akışına ya da insan denetimli içerik işlemeye girdi olur.

Araç; hassas belgeleri buluta göndermeden dönüştürmek isteyen ekipler, belge tabanlı asistan hazırlayan geliştiriciler ve toplu arşiv aktarımı yapan araştırmacılar için anlamlı. Yalnız bir PDF’den hızlıca metin kopyalamak isteyen kişi için pdftotext daha hafiftir. Taranmış ve karmaşık belgelerde ise Docling’in yerleşim ve tablo modelleri daha fazla yapı koruyabilir.

Mimari: ayrıştırıcı, yerleşim modeli ve çıktı katmanı

Standart PDF hattı önce sayfayı çözümler; gerekirse OCR uygular, yerleşim öğelerini saptar, tablo yapısını tahmin eder ve okuma sırasını kurar. Sonuç, metin parçalarıyla birlikte sayfa ve koordinat kökenini taşıyabilen bir DoclingDocument nesnesidir. Dışa aktarıcı bu nesneyi Markdown veya JSON’a çevirir. Bir sonraki aşamada hiyerarşik ya da hibrit parçalayıcı, metni model bağlamına uygun bölümlere ayırabilir.

Bu tasarımda dil modeli zorunlu değil. Testte bulut API anahtarı ve sohbet modeli kullanmadım. PDF ana makinede işlendi; fakat ilk çalıştırma tamamen çevrimdışı değildi. RapidOCR ağırlıkları ModelScope’tan, yerleşim ve tablo modelleri Hugging Face’ten indirildi. Dosyanın kendisinin bu servislere gönderildiğini gösteren bir istek yoktu. Gerçek hava boşluklu kullanım için modelleri önceden indirmek ve --artifacts-path ile yerel konumu göstermek gerekir.

Depo, sürüm, bakım ve lisans kontrolü

Test, 10 Ağustos 2026’da yayımlanan v2.119.0 etiketi ve 632f00c1a81c ile başlayan sabit commit üzerinden yapıldı. Bu sürüm Outlook .msg desteği, yeni VLM OCR çıktısı ve çeşitli doğruluk düzeltmeleri getiriyor. Ana dal 12 Ağustos’ta da güncellenmişti. GitHub aramasında pull requestleri hariç 885 açık issue, 1–12 Ağustos arasında kapanmış 19 issue vardı. Bunlar kalite puanı değil; geniş özellik alanının ve bakım yükünün göstergesi.

Güncel açık bildirimler arasında özel yazı tiplerinde geçersiz glif yüzünden PDF dönüşümünün durması, Windows’ta PyTorch derleme bağımlılığı, bazı Word başlıklarının kaybolması ve başlığın bölüm başlığına indirgenmesi bulunuyor. Öte yandan son sürümden sonraki hata düzeltmeleri ve özel güvenlik bildirim kanalı, projenin etkin yönetildiğini gösteriyor. Güvenlik politikası yalnız son sürümleri destekliyor.

Kök depodaki tam MIT lisans metni sabit etikette doğrulandı. MIT kodu kullanmaya, değiştirmeye ve dağıtmaya genel olarak izin verir; telif ve lisans bildirimi korunmalıdır. Model koşulları ayrıdır: testte kullanılan Docling modelleri CDLA-Permissive-2.0 ve Apache-2.0, Heron yerleşim modeli Apache-2.0 olarak etiketleniyor. RapidOCR kod deposunda Apache-2.0 metni var; kullandığınız belirli OCR ağırlığının kartını ayrıca saklamak iyi bir dağıtım pratiğidir. MIT etiketi tek başına model, belge veya çıktı lisansını belirlemez.

Kurulum ve güvenli başlangıç

Docling 2.119.0, Python 3.10–3.13 istiyor. Bağımlılıkları ana Python ortamına karıştırmamak için ayrı sanal ortam ve sabit sürüm kullanın:

mkdir docling-deneme && cd docling-deneme
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python "docling==2.119.0"
.venv/bin/docling convert --version

Testte 103 paket kuruldu; sanal ortam yaklaşık 1,1 GB yer kapladı. Kurulu bağımlılıklar pip-audit ile tarandığında bilinen güvenlik açığı bulunmadı. Bu sonuç 12 Ağustos 2026’daki danışma veritabanı görüntüsüdür; kod denetimi veya gelecekteki güvenlik garantisi değildir.

Adım adım gerçek kullanım: PDF’yi Markdown’a dönüştürme

Girdi olarak Docling deposundaki dört sayfalık chart_document.pdf örneğini kullandım. Dosya 5,8 MB, şifresiz ve PDF erişilebilirlik etiketleri taşımıyor. Dönüşümü özellikle CPU’ya sabitledim ve hem insanın okuyacağı Markdown’ı hem denetim için ayrıntılı JSON’u istedim:

.venv/bin/docling convert chart_document.pdf \
  --to md --to json \
  --output cikti \
  --device cpu \
  --document-timeout 180 \
  --profiling

1. Komut belge biçimini PDF olarak algıladı ve standart hattı başlattı.
2. İlk koşuda RapidOCR için yaklaşık 30,7 MB’lık üç ağırlık ile yerleşim ve tablo modelleri indirildi.
3. Dört sayfanın OCR, yerleşim ve tablo aşamaları tamamlandı; hiçbir sayfa başarısız olmadı.
4. chart_document.md ve kaynak koordinatlarını da içeren JSON oluşturuldu.
5. Markdown’ı kaynak PDF ile karşılaştırdım: ana gövde ve altı bölüm başlığı korundu, fakat kapaktaki ilk başlık kontrol karakterlerine dönüştü.

Toplam duvar süresi 121,32 saniye, Docling’in raporladığı dönüşüm süresi 118,28 saniyeydi. Tepe bellek ayak izi yaklaşık 4,0 GB oldu. Markdown 854 kelime içeriyordu; görseller varsayılan olarak base64 gömüldüğü için dosya 1,2 MB’a, Markdown ve JSON’un bulunduğu çıktı klasörü 11 MB’a ulaştı. Arama dizinine yalnız metin verecekseniz şu seçenek daha kontrollü olur:

.venv/bin/docling convert rapor.pdf \
  --to md \
  --image-export-mode placeholder \
  --output cikti

Ardından bozuk karakterleri, başlık sırasını ve tabloları insan gözüyle denetleyin. Üretim akışında “komut başarıyla bitti” sonucu içerik doğruluğu kanıtı sayılmamalı.

Arayüz ve erişilebilirlik notları

Docling’in temel yüzeyi terminaldir: giriş bir dosya yolu veya URL, denetimler convert alt komutu ve seçenekleri, çıktı ise seçilen klasördeki dosyalarla ilerleme kayıtlarıdır. Fare gerektirmez; komutlar klavyeyle çalışır ve düz metin çıktılar ekran okuyucuya uygundur. Buna karşılık renkli ilerleme tabloları, uzun model indirme kayıtları ve ANSI denetim karakterleri konuşma çıktısını gürültülü hâle getirebilir. Betiklerde --quiet kullanmak, hataları ayrı kaydetmek ve üretilen dosyayı düzenleyicide açmak daha erişilebilir bir akıştır.

Üretilen Markdown’daki başlıklar başlıkla gezinmeyi kolaylaştırabilir; fakat Docling erişilebilir PDF onarım aracı değildir. Test PDF’si etiketsizdi, ilk başlık bozuldu ve görseller yalnız “Image” adlı genel alternatif metin aldı. Okuma sırası, tablo başlık ilişkileri, dil, anlamlı görsel açıklaması ve kaynakla eşdeğer erişim ayrıca doğrulanmalıdır. Bu vardiyada VoiceOver veya NVDA ile uçtan uca test yapılmadı.

Alternatiflerle karşılaştırma

• pdftotext veya PyMuPDF: Metin katmanı düzgün PDF’lerde daha hızlı ve hafif; karmaşık yerleşim ile tablo yapısını daha az koruyabilir.
• MarkItDown: Ofis belgelerini Markdown’a dönüştürmek için yalın bir araç; ağır PDF yerleşim modeli istemeyen akışlarda daha kolaydır.
• Unstructured: Bağlayıcı ve bölme ekosistemi geniştir; kurulum, hizmet ve lisans bileşimini kullanım biçimine göre ayrıca incelemek gerekir.
• Bulut belge servisleri: Ölçek ve yönetilen OCR sunar; sayfa başına ücret, hesap, bölgesel erişim ve belgenin üçüncü tarafa aktarılması söz konusudur.

Güvenlik, gizlilik ve maliyet

Yerel CLI ücretsizdir ve hesap istemez. Asıl maliyet CPU/GPU zamanı, yaklaşık gigabayt ölçeğindeki bağımlılıklar, model önbelleği ve çıktı depolamasıdır. Varsayılan yerel hatta uzaktaki model hizmetlerine belge gönderimi kapalıdır; buna rağmen ilk model indirmeleri ağ ve tedarik zinciri bağımlılığı yaratır. Üretimde sürümü, model revizyonunu ve dosya özetini sabitleyin; modeli denetimli ağda önceden indirin; --enable-remote-services seçeneğini gerekmedikçe açmayın.

Güvenilmeyen belgeleri ayrı kullanıcı, konteyner veya VM içinde işleyin. İşlemci ve bellek sınırı, dosya boyutu/sayfa sayısı sınırı, zaman aşımı ve salt okunur girdi dizini uygulayın. PDF’nin telif hakkı ve kişisel veri sınıfı, aracın açık kaynak olmasıyla değişmez. Çıktıya gömülen görseller ile JSON’daki kaynak metinler de aynı hassasiyette korunmalıdır.

Sınırlamalar ve sorun giderme

• İlk çalışma yavaş: Modeller indiriliyor ve belleğe alınıyor. Çevrimdışı kullanım için modelleri önceden getirip --artifacts-path verin.
• Bellek yetmiyor: CPU kullanın, tablo/OCR gibi gerekmeyen aşamaları kapatın, belgeyi sayfa gruplarına bölün ve eşzamanlı işi azaltın.
• Başlık veya glif bozuk: Kaynak PDF’nin gömülü yazı tipini ve metin katmanını kontrol edin; OCR kipini karşılaştırın ve sonucu insan denetimine gönderin.
• Çıktı aşırı büyük: --image-export-mode placeholder veya referenced kullanın; base64 gömme seçeneğini arama dizinine taşımayın.
• Komut başarısız ama toplu işlem sürüyor: CI’da --abort-on-error, belge başına zaman aşımı ve çıkış kodu denetimi ekleyin.

Karar: Docling 2.119.0, karmaşık belgeleri yerelde ve denetlenebilir biçimde AI iş akışına hazırlamak için ciddi bir araç. Fakat testteki süre, bellek kullanımı, bozuk ilk başlık ve genel görsel alternatif metni, onu “tek komutla doğru ve erişilebilir belge” çözümü olmaktan çıkarıyor. En güvenli kullanım; sabit sürüm, önceden indirilmiş modeller, sınırlandırılmış çalışma ortamı ve örneklem tabanlı insan kalite kontrolüdür.

Kaynaklar

• Docling 2.119.0 sabit kaynak ağacı — README, kurulum, kod ve test girdisi; 12 Ağustos 2026’da incelendi.
• Docling 2.119.0 sürüm notları — 10 Ağustos 2026.
• Docling MIT lisans metni ve güvenlik politikası.
• Model ön indirme, çevrimdışı kullanım ve uzak hizmet izinleri.
• Docling Layout Heron model kartı ve Docling model paketi kartı — model lisansları ve revizyonlar.
• Özel yazı tipi/glif hatası #3965, Windows PyTorch hatası #3956 ve başlık sınıflandırma sorunu #3957.