MarkItDown

[!IMPORTANT] MarkItDown, mevcut işlemin ayrıcalıklarıyla I/O gerçekleştirir. open() veya requests.get() gibi, işlemin kendisinin erişebileceği kaynaklara erişecektir. Güvenilmeyen ortamlarda girişlerinizi temizleyin ve kullanım durumunuz için gerekli olan en dar convert_* fonksiyonunu çağırın (örn. convert_stream() veya convert_local()). Daha fazla bilgi için belgelendirmenin Güvenlik Hususları bölümüne bakın.

MarkItDown, LLM'ler ve ilgili metin analizi işlem hatları ile kullanılmak üzere çeşitli dosyaları Markdown'a dönüştürmek için hafif bir Python yardımcı programıdır. Bu amaçla, textract ile en karşılaştırılabilir olanıdır, ancak önemli belge yapısı ve içeriğinin Markdown olarak korunmasına odaklanır (başlıklar, listeler, tablolar, linkler vb. dahil). Çıktı genellikle makul ölçüde sunulabilir ve insan dostu olsa da, metin analiz araçları tarafından tüketilmek için tasarlanmıştır -- ve insan tüketimi için yüksek sadakatli belge dönüştürmeleri için en iyi seçenek olmayabilir.

MarkItDown şu anda aşağıdakilerden dönüştürmeyi desteklemektedir:

• PDF
• PowerPoint
• Word
• Excel
• Görüntüler (EXIF meta verileri ve OCR)
• Ses (EXIF meta verileri ve konuşma transkripsiyonu)
• HTML
• Metin tabanlı formatlar (CSV, JSON, XML)
• ZIP dosyaları (içeriği üzerinde yineler)
• Youtube URL'leri
• ePub'lar
• ... ve daha fazlası!

Neden Markdown?

Markdown, düz metne son derece yakındır; minimal işaretleme veya biçimlendirme ile, ancak yine de önemli belge yapısını temsil etmenin bir yolunu sağlar. OpenAI'ın GPT-4o gibi ana akım LLM'ler, Markdown'ı doğal olarak "konuşurlar" ve çoğu zaman Markdown'ı tepkilerine istenmeden dahil ederler. Bu, geniş miktarda Markdown biçimlendirilmiş metinle eğitilmiş olduklarını ve bunu iyi anladıklarını gösterir. Ek bir avantaj olarak, Markdown kuralları son derece token verimli olur.

Ön Koşullar

MarkItDown, Python 3.10 veya üstünü gerektirir. Bağımlılık çatışmalarından kaçınmak için sanal ortam kullanılması önerilir.

Standart Python kurulumu ile, aşağıdaki komutları kullanarak sanal ortam oluşturabilir ve etkinleştirebilirsiniz:

python -m venv .venv
source .venv/bin/activate

uv kullanıyorsanız, aşağıdakilerle sanal ortam oluşturabilirsiniz:

uv venv --python=3.12 .venv
source .venv/bin/activate
# NOT: Bu sanal ortama paket yüklemek için 'pip install' yerine 'uv pip install' kullandığınızdan emin olun

Anaconda kullanıyorsanız, aşağıdakilerle sanal ortam oluşturabilirsiniz:

conda create -n markitdown python=3.12
conda activate markitdown

Kurulum

MarkItDown'ı kurmak için pip kullanın: pip install 'markitdown[all]'. Alternatif olarak, kaynaktan yükleyebilirsiniz:

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

Kullanım

Komut Satırı

markitdown path-to-file.pdf > document.md

Veya çıktı dosyasını belirtmek için -o kullanın:

markitdown path-to-file.pdf -o document.md

Ayrıca içeriği pipe edebilirsiniz:

cat path-to-file.pdf | markitdown

İsteğe Bağlı Bağımlılıklar

MarkItDown, çeşitli dosya formatlarını etkinleştirmek için isteğe bağlı bağımlılıklara sahiptir. Bu belgenin daha öncesinde, [all] seçeneği ile tüm isteğe bağlı bağımlılıkları yükledik. Ancak daha fazla kontrol için bunları ayrı ayrı yükleyebilirsiniz. Örneğin:

pip install 'markitdown[pdf, docx, pptx]'

yalnızca PDF, DOCX ve PPTX dosyaları için bağımlılıkları yükleyecektir.

Şu anda aşağıdaki isteğe bağlı bağımlılıklar mevcuttur:

• [all] Tüm isteğe bağlı bağımlılıkları yükler
• [pptx] PowerPoint dosyaları için bağımlılıkları yükler
• [docx] Word dosyaları için bağımlılıkları yükler
• [xlsx] Excel dosyaları için bağımlılıkları yükler
• [xls] Eski Excel dosyaları için bağımlılıkları yükler
• [pdf] PDF dosyaları için bağımlılıkları yükler
• [outlook] Outlook mesajları için bağımlılıkları yükler
• [az-doc-intel] Azure Document Intelligence için bağımlılıkları yükler
• [az-content-understanding] Azure Content Understanding için bağımlılıkları yükler
• [audio-transcription] wav ve mp3 dosyalarının ses transkripsiyonu için bağımlılıkları yükler
• [youtube-transcription] YouTube video transkripsiyonu getirmek için bağımlılıkları yükler

Eklentiler

MarkItDown, 3. taraf eklentileri de destekler. Eklentiler varsayılan olarak devre dışıdır. Yüklü eklentileri listelemek için:

markitdown --list-plugins

Eklentileri etkinleştirmek için kullanın:

markitdown --use-plugins path-to-file.pdf

Kullanılabilir eklentileri bulmak için GitHub'da #markitdown-plugin hashtag'ini arayın. Bir eklenti geliştirmek için bkz. packages/markitdown-sample-plugin.

markitdown-ocr Eklentisi

markitdown-ocr eklentisi, PDF, DOCX, PPTX ve XLSX dönüştürücülerine OCR desteği ekler ve LLM Vision kullanarak gömülü görüntülerden metin ayıklar — MarkItDown'ın zaten görüntü açıklamaları için kullandığı llm_client / llm_model deseniyle aynı. Yeni ML kitaplıkları veya ikili bağımlılıklar gerekli değildir.

Kurulum:

pip install markitdown-ocr
pip install openai  # veya herhangi bir OpenAI uyumlu istemci

Kullanım:

Görüntü açıklamaları için kullanacağınız llm_client ve llm_model ile aynı olanları geçirin:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)

Hiçbir llm_client sağlanmazsa, eklenti yine de yüklenir, ancak OCR sessizce atlanır ve standart yerleşik dönüştürücü kullanılır.

Ayrıntılı belgelendirme için packages/markitdown-ocr/README.md bölümüne bakın.

Azure Content Understanding

Azure Content Understanding, yapılandırılmış alan ayıklama (YAML ön kapı), çok modaliteli destek (belgeler, görüntüler, ses, video) ve yapılandırılabilir analizörlerle daha yüksek kaliteli dönüştürme sağlar.

Kurulum: pip install 'markitdown[az-content-understanding]'

Content Understanding Ne Zaman Kullanılır

Content Understanding, yerleşik veya Document Intelligence dönüştürücülerinin sağladığından daha fazla özelliğe ihtiyacınız olduğunda idealdir:

• Ses ve video dosyaları — CU, video için tek seçenek ve ses için daha yüksek kaliteli bulut seçeneğidir. Yerleşik dönüştürücülerin video desteği yok ve sadece temel ses transkripsiyonu var.
• Yapılandırılmış alan ayıklama — Önceden oluşturulmuş veya özel olarak oluşturulan analizörler, alan özel alanları (fatura tutarları, makbuz tarihleri, sözleşme maddeleri) YAML ön kapısı olarak seri hale getirilmiş şekilde ayıklar. Ne yerleşik ne de Doc Intel entegrasyonu alanları açığa çıkarır.
• Daha yüksek kaliteli belge ayıklama — Taranmış PDF'ler, karmaşık tablolar ve çok sayfalı belgeler için bulut tabanlı düzen analizi ve OCR.
• Tüm modelliteler için tek API — Tek bir cu_endpoint, otomatik analizör yönlendirmesi ile belgeleri, görüntüleri, sesi ve videoyu işler.

Yetenek	Yerleşik dönüştürücüler	Azure Document Intelligence	Azure Content Understanding
Belge dönüştürme	Çevrimdışı, biçime özel ayıklama	Bulut düzeni ayıklama	Bulut çok modaliteli ayıklama
Yapılandırılmış alanlar	Mevcut değil	Bu entegrasyon tarafından açığa çıkarılmaz	Analizör alanlarından YAML ön kapısı
Özel analizörler	Mevcut değil	Bu entegrasyonda yapılandırılamaz	cu_analyzer_id ile desteklenir
Ses ve video	Temel ses, video yok	Desteklenmez	Ses ve video analizörleri
Maliyet	Yalnızca yerel işlem	Faturalandırılabilir Azure API çağrıları	Faturalandırılabilir Azure API çağrıları

CLI:

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

Python API:

from markitdown import MarkItDown

# Sıfır yapılandırma — dosya türü başına analizörü otomatik seçer
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # belgeler → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # video → prebuilt-videoSearch
result = md.convert("call.wav")     # ses → prebuilt-audioSearch
print(result.markdown)

Özel analizör ile (alan özel alan ayıklama için):

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Çıktı, ayıklanan alanlarla YAML ön kapısını içerir:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...

cu_analyzer_id ayarlandığında, dönüştürücü otomatik olarak analizörün modalitesine göre uyumlu dosya türlerine kapsamını belirler. Uyumsuz türler (örn. bir belge analizörüne sahip ses dosyaları) varsayılan önceden oluşturulmuş analizörlere otomatik yönlendirilir.

Maliyet notu: CU yönlendirilmiş bir biçim için her convert() çağrısı, faturalandırılabilir bir Azure API çağrısıdır. CU'nun hangi biçimlere yönleneceğini kısıtlamak için cu_file_types kullanın:

from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # sadece PDF'ler CU kullanır
)

Azure Content Understanding hakkında daha fazla bilgi burada bulunabilir.

Azure Document Intelligence

Microsoft Document Intelligence'ı dönüştürme için kullanmak için:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

Azure Document Intelligence Kaynağının nasıl ayarlanacağı hakkında daha fazla bilgi burada bulunabilir

Python API

Python'da temel kullanım:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Eklentileri etkinleştirmek için True olarak ayarlayın
result = md.convert("test.xlsx")
print(result.text_content)

Python'da Document Intelligence dönüştürme:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

Görüntü açıklamaları için Büyük Dil Modellerini kullanmak için (şu anda sadece pptx ve görüntü dosyaları için), llm_client ve llm_model sağlayın:

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="isteğe bağlı özel istem")
result = md.convert("example.jpg")
print(result.text_content)

Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

Katkıda Bulunma

Bu proje katkıları ve önerileri memnuniyetle karşılar. Çoğu katkı, katkınızı kullanma haklarına sahip olduğunuzu ve gerçekten sahip olduğunuzu beyan eden bir Katkıçı Lisans Sözleşmesi'ne (CLA) kabul etmenizi gerektirir. Ayrıntılar için https://cla.opensource.microsoft.com adresini ziyaret edin.

Bir pull request gönderdiğinizde, bir CLA botu otomatik olarak CLA sağlamanız gerekip gerekmediğini belirleyecek ve PR'yi uygun şekilde dekore edecektir (örn. durum kontrolü, yorum). Bot tarafından sağlanan talimatları basitçe izleyin. Bunu yalnızca bir kez yapmanız gerekecektir; CLA kullanan tüm depolar arasında.

Bu proje, Microsoft Açık Kaynak Davranış Kuralları benimsemiştir. Daha fazla bilgi için bkz. Davranış Kuralları SSS veya herhangi bir ek soru veya yorum için opencode@microsoft.com ile iletişim kurun.

Nasıl Katkıda Bulunursunuz

Sorunlara bakarak veya PR'leri gözden geçirmeye yardımcı olarak katkıda bulunabilirsiniz. Herhangi bir sorun veya PR hoştur, ancak topluluk katkılarını kolaylaştırmaya yardımcı olmak için bazılarını 'katkıya açık' ve 'gözden geçirmeye açık' olarak işaretledik. Bunlar elbette sadece önerilerdir ve herhangi bir şekilde katkıda bulunmakta özgürsünüz.

Testleri ve Kontrolleri Çalıştırma

• MarkItDown paketine gidin:

  cd packages/markitdown
  

• Ortamınıza hatch yükleyin ve testleri çalıştırın:

  pip install hatch  # Hatch'i kurmanın diğer yolları: https://hatch.pypa.io/dev/install/
  hatch shell
  hatch test
  

  (Alternatif) Tüm bağımlılıkları yüklenmiş olan Devcontainer'ı kullanın:

  # Projeyi Devcontainer'da yeniden açın ve çalıştırın:
  hatch test
  

• PR göndermeden önce ön kayıt kontrollerini çalıştırın: pre-commit run --all-files

Güvenlik Hususları

MarkItDown, mevcut işlemin ayrıcalıklarıyla I/O gerçekleştirir. open() veya requests.get() gibi, işlemin kendisinin erişebileceği kaynaklara erişecektir.

Girişlerinizi temizleyin: Güvenilmeyen girişi doğrudan MarkItDown'a geçirmeyin. Girişin herhangi bir kısmı güvenilmeyen bir kullanıcı veya sistem tarafından kontrol edilebiliyorsa, örneğin barındırılan veya sunucu tarafı uygulamalarda, MarkItDown'ı çağırmadan önce doğrulanmalı ve kısıtlanmalıdır. Ortamınıza bağlı olarak, bu dosya yollarını kısıtlamayı, URI şemalarını ve ağ hedeflerini sınırlamayı ve özel, geri döngü, bağlantı-yerel veya meta veri-hizmet adreslerine erişimi engellemeyi içerebilir.

Sadece ihtiyacınız olan dönüştürme yöntemini çağırın: Kullanım durumunuza uygun en dar dönüştürme API'sini tercih edin. MarkItDown'ın convert() yöntemi kasıtlı olarak izin veren ve yerel dosyalar, uzak URI'ler ve bayt akışlarını işleyebilir. Uygulamanız sadece yerel dosyaları okumaya ihtiyacınız varsa, bunun yerine convert_local() öğesini çağırın. URI getirme üzerinde daha fazla kontrol gerekiyorsa, requests.get() öğesini kendiniz çağırın ve yanıt nesnesini convert_response() öğesine geçirin. Maksimum kontrol için, dönüştürmek istediğiniz girişe bir akış açın ve convert_stream() öğesini çağırın.

3. Taraf Eklentilerine Katkıda Bulunma

Ayrıca 3. taraf eklentileri oluşturarak ve paylaşarak katkıda bulunabilirsiniz. Daha fazla ayrıntı için bkz. packages/markitdown-sample-plugin.

Ticari Markalar

Bu proje, projeler, ürünler veya hizmetler için ticari markalar veya logolar içerebilir. Microsoft ticari markalarının veya logolarının yetkili kullanımı, Microsoft'un Ticari Marka ve Marka Yönergeleri başlığı altında belirtilmiş ve takip etmelidir. Bu projenin değiştirilmiş sürümlerinde Microsoft ticari markalarının veya logolarının kullanımı, kafa karışıklığına neden olmamalı veya Microsoft sponsorluğu anlamına gelmemelidir. Herhangi bir üçüncü taraf ticari markası veya logosu kullanımı, ilgili üçüncü tarafın politikalarına tabidir.