Tam olmOCR Yerel Deployment Kılavuzu 2025: Docker & vLLM ile Modern PDF İşleme

olmOCR Logosu

Son birkaç aydır olmOCR ile çalışıyorum ve söylemeliyim ki – bu araç PDF işleme şeklimi tamamen değiştirdi. Versiyon 0.3.4 henüz çıktı ve dürüst olmak gerekirse Allen AI ekibinin burada başardığı şey etkileyici.

🚀 Önce denemek ister misiniz? Yerel deployment kurmadan önce olmOCR'nin kendi PDF'lerinizle yeteneklerini test etmek için ana sayfamıza gidin.

📚 Not: Önceki deployment kılavuzumuz "olmOCR Yerel Deployment için Adım Adım Kılavuz" arıyorsanız, bunun artık güncelliğini yitirdiğini belirtmeliyiz. Bu kapsamlı 2025 kılavuzu en son kurulum yöntemlerini ve en iyi uygulamaları içeriyor.

Son sürümde dikkatimi çeken şeyler:

Otomatik rotasyon algılaması artık gerçekten çalışıyor (artık yan dönen dokümanlar yok!)
Docker kurulumu eskisinden çok daha sorunsuz
vLLM'ye geçtiler ve hız farkı fark edilir
RTX 4090 veya H100'ünüz varsa FlashInfer optimizasyonu buna değer
Maliyet tasarrufları gerçek: milyon sayfa başına ₺5.500 ile doküman işliyorum, ticari API'lere ödediğim ₺350.000+'lık tutarın yerine

🎯 Neden Yerel olmOCR Deployment'ına Geçtim

Rakamlar Yalan Söylemiyor (Ama Her Şey Değil)

Bakın, bunu tatlandırmayacağım – olmOCR'ye para yüzünden geçtim. Benchmark %78.5 doğruluk gösteriyor, Marker'ın %70.1'ine karşı, ve bu harika, ama beni ikna eden maliyet farkıydı. Ticari API'lerle para kaybediyordum.

Ama pratikte gerçekten önemli olan şu:

Verilerinizi gerçekten gizli tutar: Hassas sözleşmeleri üçüncü taraf hizmetlere yükleme yok
Çevrimdışı çalışır: İnternet çöktü? Kim umursar, hala doküman işliyorsun
Garip PDF'leri ele alır: 1995'ten tuhaf düzenli taranmış dokümanları biliyorsun değil mi? Evet, onları da hallediyor
İhtiyacın olduğunda ölçeklenir: Tekil dosyalarla başladım, şimdi binlerce dosyayı bankayı batırmadan işliyorum

🛠️ Gerçekten Neye İhtiyacınız Var

Donanım Hakkında Konuşalım (Gerçek Gereksinimler)

Dalışa geçmeden önce, ihtiyacın hakkında dürüst olalım. Dokümantasyon "minimum konfigürasyon" diyor ama size gerçekten neyin işe yaradığını söyleyeceğim:

Başlamak istiyorsan:

GPU: 24GB'lık RTX 4090 çoğu insan için sweet spot. 16GB'da çalıştığını gördüm ama dar – gerçeklik kontrolü: topluluk 3090'da gerçekte ~20GB VRAM kullandığını bildiriyor, bu yüzden 16GB kartlar zorlanıyor
RAM: 32GB iyi, büyük partiler işlemeyi planlıyorsan 64GB alırdım
Depolama: 30GB minimum, ama yapabilirsen NVMe SSD al. Bu konuda bana güven
CUDA: 12.8+ (önce nvidia-smi ile kontrol et)

⚠️ Topluluk Uyarısı - Multi-GPU Çalışmıyor: "İki RTX 3060 kullanarak toplam 24GB elde edeceğim" diye düşünüyorsan – yapma. Bu GitHub sorunlarında sürekli çıkıyor. olmOCR VRAM'i birden fazla GPU'da birleştiremez. Tek kartta 20GB+ lazım. Kendini baş ağrısından kurtar.

Bunu iş için yapıyorsan:

GPU: Şirketin cebi doluysa H100, değilse A100
RAM: 64GB+ çünkü başka şeyler de çalıştıracaksın
Depolama: Hızlı depolamada 100GB+. İşleme karışıyor

Sıkıcı Ama Temel Kurulum

Evet, biliyorum, dependency kurulumu eğlenceli değil. Ama bunu atlarsan sonra tuhaf PDF render sorunlarını debug edeceksin. Ubuntu/Debian'da:

# Olağan şüpheliler önce
sudo apt-get update

# PDF problemlerinin çoğunu düzelten sihirli satır
sudo apt-get install -y \
    poppler-utils \
    ttf-mscorefonts-installer \
    msttcorefonts \
    fonts-crosextra-caladea \
    fonts-crosextra-carlito \
    gsfonts \
    lcdf-typetools

Dikkat: Font kurulumunda lisans popup'ı alacaksın. Sadece TAB bas ve Yes seç. Microsoft fontları Microsoft'un.

🐍 Python'u Doğru Kurma

Sadece Conda Kullan (Ciddi)

Bunun için hem conda hem venv denedim. Conda her seferinde kazanıyor. Dependency cehennemi PyTorch ve CUDA ile gerçek, ve conda bunu daha iyi hallediyor:

# Temiz ortam yarat (Python 3.11 onların test ettiği)
conda create -n olmocr python=3.11
conda activate olmocr

# Bu satır ~3GB şey indirecek, sabırlı ol
pip install olmocr[gpu] --extra-index-url https://download.pytorch.org/whl/cu128

# RTX 4090 veya H100'ün varsa, bu fark yaratır
pip install https://download.pytorch.org/whl/cu128/flashinfer/flashinfer_python-0.2.5%2Bcu128torch2.7-cp38-abi3-linux_x86_64.whl

Gerçekten venv Kullanmak İstersen

Bak, anlıyorum. Bazıları venv tercih ediyor. Tamam, PyTorch versiyonlarını debug ederek iki saat geçirdiğinde beni suçlama:

# Standart venv kurulum
python3.11 -m venv olmocr-env
source olmocr-env/bin/activate  # Linux/Mac
# Windows kullanıcıları için: olmocr-env\Scripts\activate

# Parmaklarını çaprazla ve kur
pip install olmocr[gpu] --extra-index-url https://download.pytorch.org/whl/cu128

💬 Gerçek Kullanıcı Deneyimi: Bir GitHub kullanıcısı mükemmel özetledi: "venv ile CUDA/PyTorch versiyon çakışmalarıyla 3 saat uğraştım. Conda'ya geçtim ve 10 dakikada çalıştı." Conda'daki dependency çözümü gerçekten burada fark yaratıyor.

🚀 Bu Şeyi Gerçekten Kullanma Zamanı

İlk PDF'in (Gerçek Anı)

Basit başlayalım. Bu çalışmazsa kurulumunla bir sorun var:

# Onların test PDF'ini al (sadece 3 sayfa)
curl -o olmocr-sample.pdf https://olmocr.allenai.org/papers/olmocr_3pg_sample.pdf

# İlk çalıştırma modeli indirecek (~13GB), kahve al
python -m olmocr.pipeline ./workspace --markdown --pdfs olmocr-sample.pdf

İlk çalıştırma modeli indirdiği için sonsuza kadar sürüyor. Paniklememe.

Çoklu Dosyaların Batch İşlenmesi

# Bir dizindeki tüm PDF'leri işle
python -m olmocr.pipeline ./workspace --markdown --pdfs /path/to/pdfs/*.pdf

# Özel ayarlarla işle
python -m olmocr.pipeline ./workspace \
    --markdown \
    --pdfs /path/to/pdfs/*.pdf \
    --workers 4 \
    --target_longest_image_dim 2048

Resim Dosyası İşleme

olmOCR birden fazla resim formatını destekliyor:

# PNG/JPEG resimlerini işle
python -m olmocr.pipeline ./workspace --markdown --pdfs document.png image.jpg

🐳 Docker Deployment Kılavuzu

Yöntem 1: Resmi Docker Image (Önerilen)

# En son olmOCR Docker image'ını çek
docker pull alleninstituteforai/olmocr:latest

# GPU desteği ve volume bağlamayla çalıştır
docker run -it --gpus all \
    -v /path/to/your/documents:/documents \
    -v /path/to/output:/output \
    --name olmocr_container \
    alleninstituteforai/olmocr:latest /bin/bash

Docker Container İçinde

# Container içinde dokümanları işle
python -m olmocr.pipeline /output/workspace \
    --markdown \
    --pdfs /documents/*.pdf

Yöntem 2: Harici vLLM Sunuculu Docker

Üretim ortamları için çıkarım sunucusunu ayır:

# vLLM sunucu container'ını başlat
docker run -d --gpus all \
    -p 8000:8000 \
    --name vllm-server \
    vllm/vllm-openai:latest \
    --served-model-name olmocr \
    --model allenai/olmOCR-7B-0825-FP8 \
    --max-model-len 16384

# vLLM sunucuya işaret eden olmOCR istemcisini çalıştır
docker run --rm --network host \
    -v /path/to/documents:/documents \
    -v /path/to/output:/output \
    alleninstituteforai/olmocr:latest \
    python -m olmocr.pipeline /output/workspace \
    --server http://localhost:8000 \
    --markdown \
    --pdfs /documents/*.pdf

⚡ Gelişmiş Konfigürasyon Seçenekleri

GPU Bellek Optimizasyonu

# GPU bellek kullanımını optimize et
python -m olmocr.pipeline ./workspace \
    --markdown \
    --pdfs documents/*.pdf \
    --gpu-memory-utilization 0.9 \
    --max_model_len 8192 \
    --tensor-parallel-size 2

Özel Model Konfigürasyonu

# Belirli model versiyonunu kullan
python -m olmocr.pipeline ./workspace \
    --model allenai/olmOCR-7B-0825-FP8 \
    --markdown \
    --pdfs documents/*.pdf

Kalite ve Performans Ayarı

# Özel ayarlarla yüksek kalite işleme
python -m olmocr.pipeline ./workspace \
    --markdown \
    --pdfs documents/*.pdf \
    --target_longest_image_dim 2048 \
    --max_page_retries 5 \
    --max_page_error_rate 0.02 \
    --workers 8 \
    --apply_filter

🏢 Kurumsal ve Üretim Deployment'ı

AWS S3 ile Çoklu-Node Küme Kurulumu

Birden fazla sunucuda milyonlarca doküman işlemek için:

# İlk node'da workspace'i başlat
python -m olmocr.pipeline s3://my-bucket/workspace \
    --pdfs s3://my-bucket/documents/*.pdf

# Aynı workspace'e ek node'ları ekle
python -m olmocr.pipeline s3://my-bucket/workspace

Harici vLLM Sunucu Konfigürasyonu

Yüksek throughput üretim ortamları için:

# vLLM sunucuyu başlat
vllm serve allenai/olmOCR-7B-0825-FP8 \
    --served-model-name olmocr \
    --max-model-len 16384 \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.95

# olmOCR'yi harici sunucuya bağla
python -m olmocr.pipeline ./workspace \
    --server http://your-vllm-server:8000 \
    --markdown \
    --pdfs documents/*.pdf

Performans İzleme ve Optimizasyon

# Detaylı istatistikleri etkinleştir
python -m olmocr.pipeline ./workspace \
    --stats \
    --markdown \
    --pdfs documents/*.pdf

📊 Sonuçları Görüntüleme ve Yönetme

Output Dizin Yapısı

workspace/
├── markdown/           # İnsan tarafından okunabilir markdown dosyaları
├── results/           # Dolma format çıktısı
└── logs/              # İşleme logları

Dönüştürülmüş İçeriği Görüntüleme

# Markdown çıktısını görüntüle
cat workspace/markdown/document.md

# Detaylı sonuçları incele
cat workspace/results/output_*.jsonl

Görsel Karşılaştırma Aracı

Orijinal PDF'leri dönüştürülmüş sonuçlarla karşılaştır:

# Yan yana karşılaştırma oluştur
python -m olmocr.viewer.dolmaviewer workspace/results/output_*.jsonl

# Oluşturulan HTML dosyasını tarayıcıda aç
open dolma_previews/comparison.html

🔧 İşler Yolunda Gitmediğinde (Ve Gitmeyecek)

CUDA Out of Memory (Klasik)

Bu herkese oluyor. GPU'nun VRAM'i bitiyor:

# Bellek kullanımını düşür ve tekrar dene
python -m olmocr.pipeline ./workspace \
    --gpu-memory-utilization 0.7 \
    --max_model_len 8192 \
    --pdfs documents/*.pdf

🤷‍♂️ Topluluk Ne Diyor: "20GB VRAM'den az bir şeyde OOM hataları alıyorsan, bu normal. Model sadece aç." - GitHub issue #142. Birden fazla kullanıcı optimizasyonlarla bile güvenilir işleme için gerçekten tam 20GB'ye ihtiyacın olduğunu doğruluyor.

Model İndirilmiyor

Bazen HuggingFace sunucuları yavaş veya bağlantın timeout oluyor:

# Önce ayrı indir
huggingface-cli download allenai/olmOCR-7B-0825-FP8

Garip Font/Rendering Sorunları

PDF'ler bozuk görünüyor? Genellikle font sorunu:

# Nükleer seçenek: tüm fontları yeniden kur
sudo apt-get install --reinstall ttf-mscorefonts-installer

Docker GPU'nu Görmüyor

Docker muhtemelen GPU erişimi için yapılandırılmamış:

# NVIDIA Docker runtime kur
sudo apt-get install nvidia-docker2
sudo systemctl restart docker

Evet, Docker'ı yeniden başlatman gerek. Bunu zor yoldan öğrendim.

📈 Performans Benchmark'ları ve Optimizasyon

Benchmark Sonuçları (olmOCR v0.3.0)

Model	ArXiv	Tablolar	Eski Taramalar	Genel Skor
olmOCR v0.3.0	78.6	72.9	43.9	78.5
Marker v1.7.5	76.0	57.6	27.8	70.1
MinerU v1.3.10	75.4	60.9	17.3	61.5

Maliyet Karşılaştırması

olmOCR: Milyon sayfa başına ₺5.500
GPT-4o API: Milyon sayfa başına ₺350.000
Maliyet Tasarrufları: İşleme maliyetlerinde %98.5 azalma

Performans Optimizasyon İpuçları

GPU Seçimi: H100 > A100 > RTX 4090 > L40S
Bellek Yönetimi: Maksimum throughput için %90 GPU kullanımı
Batch İşleme: Birden fazla dosyayı aynı anda işle
Resim Çözünürlüğü: Kalite (2048px) ve hız (1280px) arasında denge kur
Worker Thread'leri: Worker sayısını CPU çekirdekleriyle eşle

💡 Topluluk İpuçları ve Zor Öğrenilen Dersler

Yüzlerce GitHub sorunu ve topluluk tartışmasına dayanarak, size zaman kazandıracak gerçek dünya ipuçları:

🎯 Donanım Alışverişi Gerçeklik Kontrolü

İkinci El GPU Pazarının Sweet Spot'u:

RTX 3090 (24GB): olmOCR için topluluk favorisi. ~20GB kullanıyor, 4GB buffer bırakıyor. İkinci el pazarda sağlam erişilebilirlik
RTX 4080 (16GB): Teknik olarak çalışıyor ama dar. Birkaç kullanıcı karmaşık dokümanlarda OOM sorunları bildiriyor
Çift GPU Hayalleri: Dur orada. Birden fazla kullanıcı çift RTX 3060 kurulumlarını denedi – çalışmıyor, VRAM birleşmiyor

Reddit'ten Bütçe Stratejisi: Bir kullanıcı mükemmel özetledi: "Çift 3060 kurulumumu sattım, ikinci el 3090 aldım. ₺7.000 farkla 'çalışmıyor'dan 'mükemmel çalışıyor'a geçtim."

🛠️ Kurulum Savaş Hikayeleri

Ortam Yönetimi Gerçeği:

Python 3.11 + conda: Topluluk raporlarında %90 başarı oranı
Python 3.12 + venv: %30 başarı oranı, çok dependency cehennem
3.9/3.10'u Atla: Birden fazla uyumluluk sorunu bildiriliyor

Dependency Çakışması Hayatta Kalma Kılavuzu:

# Bu özel sıra önemli (topluluk zor yoldan öğrendi)
conda create -n olmocr python=3.11 -y
conda activate olmocr
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install olmocr[gpu]

🚀 Power User'lardan Performans Hack'leri

Gerçekten İşe Yarayan Bellek Optimizasyonu:

# RTX 3090 için topluluk test edilmiş sweet spot
python -m olmocr.pipeline ./workspace \
    --gpu-memory-utilization 0.85 \
    --max_model_len 12288 \
    --workers 2 \
    --pdfs documents/*.pdf

Batch İşleme Bilgeliği:

Küçük batch'ler (5-10 dosya): Genel olarak daha hızlı, hatalardan daha kolay kurtulma
Büyük batch'ler (50+ dosya): Topluluk tarafından bellek sızıntıları bildiriliyor, ara sıra yeniden başlat
Bir Reddit kullanıcısı: "20 dosya işle, script'i yeniden başlat. Sıkıcı ama güvenilir."

🐛 Yaygın Hata Kalıpları

"Demo'da Çalışıyor, Gerçek PDF'lerde Başarısız" Problemi: Birden fazla kullanıcı bunu bildiriyor. GitHub tartışmalarından gerçek çözüm:

# Problemli PDF'ler için bu flag'leri ekle
--target_longest_image_dim 1500 \
--max_page_retries 3 \
--apply_filter

Linux'ta Docker Bellek Sorunları: Docker bellek sınırları için topluluk çözümü:

# docker run komutuna ekle
--shm-size 8g --ulimit memlock=-1 --ulimit stack=67108864

🆕 2025 Güncellemelerinde Neler Yeni

Versiyon 0.3.4 İyileştirmeleri (Ağustos 2025)

Gelişmiş Otomatik Rotasyon: Daha iyi doküman yönlendirme algılaması
Boş Doküman İşleme: Boş sayfalarda halüsinasyonları ortadan kaldırır
Performans Optimizasyonları: Azaltılmış yeniden denemelerle daha hızlı işleme
vLLM Entegrasyonu: Daha iyi stabilite için sglang'den vLLM'ye geçiş
Docker İyileştirmeleri: En son GPU desteği için CUDA 12.8'e güncellendi

Model İyileştirmeleri

Yeni FP8 Modelleri: Daha hızlı çıkarım için allenai/olmOCR-7B-0825-FP8
Doğruluk Kazanımları: Önceki versiyonlara göre 3+ puan iyileşme
Bellek Verimliliği: Kalite korunurken azaltılmış VRAM gereksinimleri

🔐 Güvenlik ve Gizlilik Değerlendirmeleri

On-Premises Veri Koruma

Yerel İşleme: Dokümanlar hiçbir zaman altyapınızı terk etmez
GDPR Uyumluluğu: Veri işleme ve depolama üzerinde tam kontrol
Kurumsal Güvenlik: Güvenlik duvarları ve VPN'ler arkasında deploy edin
Denetim İzleri: Doküman işleme faaliyetlerinin tam loglanması

Erişim Kontrolü Önerileri

# Docker container ağ erişimini kısıtla
docker run --rm --network none \
    -v /secure/documents:/documents:ro \
    -v /secure/output:/output \
    alleninstituteforai/olmocr:latest

🚀 Deployment'ınızı Geleceğe Hazırlama

Güncel Kalma

# Güncellemeleri kontrol et
pip list --outdated | grep olmocr

# En son versiyona güncelle
pip install --upgrade olmocr[gpu]

# Docker image'ını güncelle
docker pull alleninstituteforai/olmocr:latest

İzleme ve Bakım

Düzenli Güncellemeler: Yeni sürümler için aylık kontroller
Performans İzleme: İşleme hızı ve doğruluğu takip edin
Kaynak Kullanımı: GPU bellek ve disk alanını izleyin
Yedekleme Stratejileri: İşlenmiş sonuçların düzenli yedeklemeleri

📚 Ek Kaynaklar

Resmi Dokümantasyon ve Destek

GitHub Repo: https://github.com/allenai/olmocr
Teknik Makale: olmOCR Araştırma Makalesi
Online Demo: https://olmocr.allenai.org/
Topluluk Discord: Discord Topluluğuna Katılın

Gelişmiş Kullanım Durumları

Akademik Araştırma: Araştırma makaleleri ve bilimsel dokümanların işlenmesi
Hukuki Dokümanlar: Sözleşme ve hukuki doküman dijitalleştirme
Tarihi Arşivler: Eski dokümanlar ve el yazmalarının dijitalleştirilmesi
Finansal Hizmetler: Form ve finansal dokümanların işlenmesi
Sağlık: Tıbbi kayıt dijitalleştirme ve işleme

🎉 Son Düşünceler

Dürüst olacağım – olmOCR kurmak trivial değil, ama buna değer. Yıllarca ticari OCR hizmetleri kullandıktan ve faturalarımın tırmanışını gördükten sonra, bu oyun değiştirici oldu. Doğruluk çoğu ücretli hizmetten gerçekten daha iyi, ve yerel çalıştırmak veri gizliliği veya API limitleri hakkında daha fazla endişe yok demek.

Bu kılavuzu takip ettikten sonra yapabilecekleriniz:

✅ Dokümanları hiçbir yere yüklemeden işleyin
✅ Basit PDF'lerden karmaşık taranmış dokümanlara kadar her şeyi ele alın
✅ Tekil dosyalardan devasa batch'lere bankayı batırmadan ölçeklendirin
✅ Bir daha asla API rate limitleri hakkında endişelenmeyin
✅ Hassas dokümanlarınızı ait oldukları yerde tutun – altyapınızda

Basit bir PDF ile başlayın, nasıl performans gösterdiğini görün, sonra ölçeklendirin. İlk kurulum biraz zaman alıyor, ama sonra kendinize teşekkür edeceksiniz.

Bir şeyde takıldınız mı? Discord topluluğu oldukça yardımcı: discord.gg/sZq3jTNVNG

❓ Sürekli Aldığım Sorular

S: Bu Çince/İspanyolca/her neyse dokümanları ele alabilir mi?
C: Evet, birden fazla dille çalışıyor. İngilizce olmayan şeyler için --apply_filter ekleyin, eğitim çoğunlukla İngilizce dokümanlarda olduğu için YMMV.

S: Bu RTX 3090'ımda çalışacak mı?
C: Aslında, evet! 3090 harika çalışıyor - kullanıcılar mevcut 24GB'nin yaklaşık 20GB'sini kullandığını bildiriyor. Özellikle ikinci el pazarda maliyet etkili bir seçenek olarak toplulukta popüler oldu.

S: Gerçekten ücretli hizmetlerden daha mı iyi?
C: Testlerimde, evet. Onların benchmark'ında %78.5 puan aldı, çoğu ticari seçeneğin %70'ine karşı. Ayrıca, biliyorsun, milyon sayfa başına ₺350.000 tutmuyor.

S: Docker kullanmak zorunda mıyım?
C: Hayır! Docker sadece deployment'ı kolaylaştırıyor. O rotayı tercih ediyorsan conda kurulumu iyi çalışıyor.

S: GUI için planlar var mı?
C: Bildiğim kadarıyla yok. Sadece komut satırı, ama hiçbir şey kurmadan dosyaları test etmek istiyorsan web demo var.

S: Bir bug buldum, ne yapmalıyım?
C: GitHub'da bir sorun oluşturun. Allen AI ekibi oldukça duyarlı.

S: Multi-GPU desteği için planlar var mı?
C: Bu GitHub sorunlarında en çok talep edilen #1 özellik. Şu anda resmi timeline yok, ama topluluk gerçekten istiyor. Şimdilik tek yüksek-VRAM karta ihtiyaç duymakla sınırlısın.

S: Apple Silicon/M-serisi Mac'ler ne durumda?
C: O da çok talep ediliyor ama şu anda desteklenmiyor. Şimdilik sadece CUDA. Bazı kullanıcılar MPS desteği hakkında soruyor ama henüz somut bir şey yok.

Tam olmOCR Yerel Deployment Kılavuzu 2025: Docker & vLLM ile Modern PDF İşleme

İçindekiler