كيف تحوّل PDF إلى Markdown في Python

لماذا Markdown؟ ولماذا الأمر أصعب مما يبدو؟

تتعامل نماذج LLM مع Markdown بامتياز: العناوين تحدّد حدود الأقسام، وجداول الأنابيب تُبقي البيانات الجدولية متراصفة، والقوائم تبقى قوائم. أما تغذية النموذج بنص خام مستخرج من PDF فتفقد كل ذلك — وتغذيته بملف PDF الثنائي ليست خيارًا لمعظم الخطوط. لهذا يحوّل كل نظام RAG جاد تقريبًا المستندات إلى Markdown قبل التقطيع والتضمين.

الجزء الصعب أن ملفات PDF لا تحتوي على بنية — بل على حروف موضوعة عند إحداثيات x/y. على المحوِّل أن يستنتج عكسيًا أي الأسطر عناوين (من حجم الخط)، وأي الكلمات تشكّل جدولًا (من المحاذاة)، وما هو ترتيب القراءة (من تحليل التخطيط). تتفاوت المكتبات كثيرًا في إتقان ذلك، ولهذا يهم الاختيار.

تعقيد ثانٍ: ملفات PDF الممسوحة ضوئيًا لا تحوي نصًا أصلًا، بل صورًا للصفحات فقط. بعض الخيارات أدناه فقط يتعامل معها، عبر OCR.

الخيار 1: PyMuPDF4LLM — سريع وخفيف

PyMuPDF4LLM طبقة رقيقة فوق PyMuPDF (fitz) مصمّمة خصيصًا لخطوط LLM: نفّذ pip install pymupdf4llm ثم md = pymupdf4llm.to_markdown("doc.pdf") — سطر واحد، وهي سريعة جدًا وتعالج معظم المستندات في أقل من ثانية بكثير.

تكتشف العناوين من أحجام الخطوط، وتعرض الجداول كجداول أنابيب، وتستطيع إخراج مقاطع صفحات مع بيانات وصفية للإدخال المباشر في LlamaIndex أو LangChain. لملفات PDF الرقمية المنشأ ذات التخطيطات المباشرة — تقارير وتوثيق وأوراق بحثية بلا تنسيق غريب — تُعد خيارًا افتراضيًا ممتازًا.

الحدود: لا OCR، فالصفحات الممسوحة ضوئيًا تعود فارغة. التخطيطات متعددة الأعمدة المعقدة والجداول المتشابكة قد تخرج مبعثرة، لأن الاستدلالات الأساسية تفضّل السرعة على التحليل العميق للتخطيط. ملاحظة ترخيص: PyMuPDF مرخّصة بـ AGPL — مناسبة للأدوات الداخلية، لكن راجع فريقك القانوني قبل شحنها داخل منتج تجاري.

الخيار 2: Marker — أعلى جودة، ويحتاج GPU

يستخدم Marker خط أنابيب من نماذج التعلّم العميق لاكتشاف التخطيط وترتيب القراءة وبنية الجداول، وينتج أدق Markdown بين جميع الخيارات مفتوحة المصدر — يتعامل مع الأوراق الأكاديمية متعددة الأعمدة والجداول المعقدة وحتى المعادلات.

الثمن هو البنية التحتية: أوزان نماذج بعدة جيجابايتات، وGPU لسرعة معقولة (يعمل على CPU لكنه بطيء — غالبًا عشرات الثواني لكل مستند)، وشجرة تبعيات ثقيلة يتطلب نشرها في بيئات الإنتاج أو البيئات بلا خادم جهدًا حقيقيًا.

اختر Marker حين تكون جودة المخرجات على المستندات الصعبة أولويتك القصوى ولديك العتاد — تحويل أرشيف أكاديمي بالجملة على جهاز بـ GPU هو موطن قوته. أما لخدمة خفيفة أو دالة بلا خادم، فالثقل التشغيلي يستبعده عادة.

الخيار 3: MarkItDown — محوّل مايكروسوفت لكل الصيغ

MarkItDown مكتبة مايكروسوفت مفتوحة المصدر لتحويل كل شيء إلى Markdown: نفّذ pip install markitdown ثم MarkItDown().convert("doc.pdf").text_content. قوتها في الاتساع — الواجهة نفسها تحوّل PDF وDOCX وPPTX وXLSX وHTML وغيرها، ولهذا انتشرت بسرعة في تجهيز بيانات LLM.

لملفات PDF تحديدًا، استخراجها أبسط من الخيارات المتخصصة: تعتمد على استخراج نصي أساسي، فيتخلّف اكتشاف العناوين ودقة الجداول عن PyMuPDF4LLM وMarker، وتحتاج ملفات PDF الممسوحة ضوئيًا إعداد OCR إضافيًا.

اختر MarkItDown حين تحتاج تبعية واحدة تغطي أنواع ملفات كثيرة بجودة متوسطة — سكربت استيعاب داخلي يجب أن يقبل "أيًا كان ما يرفعه الناس" — لا حين تريد أفضل مخرجات PDF ممكنة.

الخيار 4: API مستضاف — بلا تبعيات إطلاقًا

الخيار الرابع ألا تشغّل التحويل محليًا: أرسل ملف PDF بطلب POST إلى API تحليل واستلم Markdown. مع ParseJet: resp = httpx.post("https://api.parsejet.com/v1/parse/auto/file", headers={"Authorization": "Bearer KEY"}, files={"file": open("doc.pdf", "rb")}) — حقل "text" في استجابة JSON هو Markdown.

هذا المسار يتضمن OCR للصفحات الممسوحة ضوئيًا جاهزًا، بلا أوزان نماذج أو مكتبات أصلية تثبّتها، ويعمل بالطريقة نفسها في دالة بلا خادم أو حاوية أو دفتر ملاحظات. كما يتجاوز مسألة AGPL كليًا. المقايضة هي رحلة شبكة ذهابًا وإيابًا وتكلفة لكل مستند بعد الطبقة المجانية (300 رصيد شهريًا مجانًا؛ ملف PDF يكلّف 3 أرصدة).

اختر API حين تريد الخط يعمل اليوم، أو حين تتضمن ملفاتك مسحًا ضوئيًا، أو حين تنشر في بيئة تؤذيها التبعيات الثقيلة — Lambda أو Cloud Run أو Vercel.

أيها تستخدم إذًا؟

ملفات PDF رقمية المنشأ بتخطيطات بسيطة إلى متوسطة والسرعة مهمة: PyMuPDF4LLM. أفضل نسبة جهد إلى جودة في Python الخالص.

مستندات صعبة (أوراق متعددة الأعمدة، جداول معقدة) ولديك GPU: Marker. لا شيء مفتوح المصدر يتفوق على جودة مخرجاته.

أنواع ملفات كثيرة عبر مكتبة واحدة والجودة المتوسطة كافية: MarkItDown.

ملفات ممسوحة ضوئيًا ضمن المزيج، أو نشر بلا خادم، أو صفر رغبة في إدارة التبعيات: API المستضاف. استدعاء HTTP واحد، مع OCR مضمّن، ومخطط مخرجات واحد لكل مستند.

مثال كامل: من مجلد PDF إلى ملفات Markdown

أيًا كان المسار الذي تختاره، شكل الخط واحد — كرّر، حوّل، اكتب. إليك المثال مع API (استبدل الاستدعاء الداخلي بـ pymupdf4llm.to_markdown() لتشغيله محليًا):

import httpx; from pathlib import Path — ثم لكل pdf في Path("pdfs/").glob("*.pdf"): نفّذ 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، قطّع Markdown حسب العناوين لا حسب عدد أحرف ثابت — المقاطع الواعية بالعناوين تُبقي الأقسام سليمة وتُسترجع بشكل أفضل بكثير. هذه الدقة البنيوية هي بالضبط سبب أهمية إتقان خطوة التحويل.