ملفات PDF في Claude Code: التحويل والرموز والحفاظ على البنية

ماذا يحدث لملف PDF في Claude، ولماذا تكلّف كل صفحة 1,500–3,000 رمز؟#

تصف وثائق Anthropic الرسمية العملية في ثلاث خطوات واضحة:

يبدو الأمر منطقيًا، لكن تكاليف المعالجة تزداد خطيًا مع عدد الصفحات. وهذا هو الرقم الذي يفسّر نفاد حد اشتراكك بسبب ملف PDF واحد:

لمعرفة حجم ذلك، قاست Anthropic ملف PDF نفسه المؤلف من 3 صفحات على Bedrock باستخدام وضعين. استهلك وضع النص (Converse Document Chat) نحو 1,000 رمز. أما التحليل البصري (Claude PDF Chat) فاستهلك نحو 7,000 رمز. إدراج الصور يجعل المعالجة أعلى تكلفة بـ7 مرات.

لقطات صفحات المستند أسوأ من ذلك. تكلّف لقطة شاشة بقياس 1000×1000 بكسل نحو 1,300 رمز.

الآلية بسيطة: ملفات PDF مكلفة لأن Claude لا يثق بتقنية OCR الخاصة به. فهو يستخدم النص والصورة معًا ليقارن بينهما، وتدفع تكلفة الطبقتين في الوقت نفسه. ويمكنك التعامل مع المستندات الكبيرة بطريقة مختلفة: احفظ الملف بصيغة Markdown في مجلد مشروعك، وقل لـClaude: «إليك مستندًا يحتوي على معلومات—وزّعها». سيقسّم المحتوى على ملفاته ويتابع العمل على النص المنظّم بدلًا من استهلاك كل شيء دفعة واحدة.

كم يستهلك ملف PDF في مهمة اعتيادية؟#

الأرقام المحددة (نموذج Sonnet 4.x، الإدخال بسعر $3 لكل مليون رمز):

وهذه الحسابات تخص دورة واحدة من 4 طلبات فقط. بعد ذلك يأتي دور التخزين المؤقت للموجّهات (مدة صلاحية افتراضية تبلغ 5 دقائق، وتصل إلى ساعة واحدة في المستوى الموسّع، مع خصم يصل إلى 90% على الطلبات المتكررة ضمن النافذة)، فتتضاعف الوفورات.

في كل مرة تحمّل فيها ملف PDF نفسه في محادثة جديدة، يقرؤه Claude من جديد؛ فالتخزين المؤقت لا ينتقل بين المحادثات.

إذا حوّلت ملف PDF نفسه ذي 15 صفحة إلى Markdown مرة واحدة، ثم أضفته إلى كل من أربع محادثات جديدة كملف .md، يستخدم المثال 15 × 300 × 4 = 18,000 رمز إدخال بدل 135,000. يمثل 300 رمز للصفحة المحولة و2,250 للصفحة بصيغة PDF افتراضين للحساب، وليس ثابتين مقاسين لكل PDF. عُدّ رموز وثيقتك وتحقق من جودة التحويل قبل تقدير التوفير.

تزداد أهمية هذه الحسابات مع اشتراك Claude Pro. فقد يستهلك تقرير واحد من 100 صفحة حد الساعات الخمس بأكمله. وبعد تحويله إلى Markdown، تتّسع الميزانية نفسها لأكثر من 10 مستندات من هذا النوع.

ما حدود Anthropic API لملفات PDF في 2026؟#

تسرد وثائق Anthropic الحدود في أعلاها (محدّثة حتى 31 مايو 2026):

تختلف حدود Claude.ai (تطبيق الويب المخصص للمستهلكين): حد أقصى يبلغ 500 MB لكل ملف، وما يصل إلى 20 ملفًا في المحادثة. لكن التحليل البصري يعمل فقط مع ملفات PDF التي لا تتجاوز 100 صفحة؛ أما ما يزيد على ذلك، فلا يرى Claude سوى النص، من دون المخططات والرسوم البيانية.

ثلاث طرق لإرسال ملف PDF عبر API:

1. عبر URL - "source": {"type": "url", "url": "..."} - أبسط طريقة عندما يكون المستند متاحًا على الإنترنت.
2. بترميز Base64 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - للملفات المحلية.
3. عبر Files API - "source": {"type": "file", "file_id": "file_abc123"} - للطلبات المتكررة؛ ويتطلب ترويسة الإصدار التجريبي anthropic-beta: files-api-2025-04-14.

تُعد Files API الوسيلة الأساسية للتوفير عند العمل على ملف PDF نفسه عبر محادثات مختلفة. حمّله مرة واحدة، واحصل على file_id، ثم استخدمه في جميع التفاعلات. مع cache_control: ephemeral، تكلّف الطلبات المتكررة 10% من السعر المعتاد.

تقدّم Anthropic أيضًا نصائح رسمية لتقليل الاستهلاك:

الطريقة 1: كيف تُعدّ MarkItDown في 5 دقائق؟#

MarkItDown مشروع رسمي من Microsoft، ويتولى فريق AutoGen صيانته. لديها 134 ألف نجمة و9.2 ألف نسخة متفرعة على GitHub (حتى نهاية مايو 2026). ويشرح ملف README غرضها مباشرةً:

التنسيقات المدعومة:

• المستندات: PDF وDOCX وPPTX وXLSX
• الويب: HTML وJSON وXML وCSV
• الوسائط: صوت مع تفريغ نصي، وصور مع EXIF وOCR، ومقاطع YouTube (عبر التسميات التوضيحية)
• الأرشيفات: ZIP وEPub
• أخرى: جميع المرفقات داخل ملفات Outlook MSG

التثبيت

المتطلب: Python 3.10+ (يكون مثبتًا عادةً على macOS؛ أما على Windows فيجب تثبيته على نحو منفصل).

pip install 'markitdown[all]'

إذا لم تكن بحاجة إلى كل التنسيقات، يمكنك تثبيت التنسيقات التي تحتاج إليها فقط:

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

تحويل ملف واحد

أبسط حالة:

markitdown document.pdf > document.md

بعد ذلك، سيظهر document.md في المجلد الحالي. أضفه إلى Claude Code باستخدام @document.md أو ضعه بجوار مشروعك.

Python API

إذا أردت دمجه في نصك البرمجي:

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("research-paper.pdf")
print(result.text_content)

# يمكنك حفظه مباشرةً:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

ما الذي لا يستطيع MarkItDown فعله

• OCR لملفات PDF الممسوحة ضوئيًا - لا يعيد أي نتيجة. تحتاج الملفات الممسوحة ضوئيًا إلى PyMuPDF4LLM أو Docling.
• التخطيطات المعقدة متعددة الأعمدة - قد يخلط ترتيب القراءة.
• عناوين URL المضمّنة في ملفات PDF - لا يحافظ عليها.

بالنسبة إلى ملفات PDF البسيطة (التقارير والمقالات والوثائق)، يُعد MarkItDown الخيار الأفضل: أداة متعددة الاستخدامات تُثبّت في دقيقة ولا تتطلب معرفة بـPython. ويعرض تحليل كيفية تحويل PDF إلى نص لاستخدامه مع AI نتائج قياس أدائه على المستندات التي تتضمن نصوصًا سيريليّة وملفات PDF ممسوحة ضوئيًا.

الطريقة 2: ماذا يقدّم PyMuPDF4LLM، ومتى يكون الخيار الأفضل؟#

يتميّز MarkItDown باتساع التنسيقات التي يدعمها، فيما يتعمق PyMuPDF4LLM في معالجة ملفات PDF.

الإصدار الحالي حتى 31 مايو 2026 هو 1.27.2.3 (صدر في 24 أبريل 2026).

ما الذي يتضمنه

• صفحات متعددة الأعمدة بترتيب القراءة الصحيح
• تحويل الجداول إلى Markdown متوافق مع GitHub
• إزالة الرؤوس والتذييلات تلقائيًا
• استخراج الصور مع روابط نسبية إلى مجلد منفصل
• OCR ذكي: يُطبّق على المناطق غير المقروءة فقط، ويوفر نحو 50% من وقت المعالجة
• محرك C أصلي، ولا يحتاج إلى GPU

التثبيت

pip install pymupdf4llm

الاستخدام

import pymupdf4llm

# الاستخدام الأساسي - التحويل مباشرة إلى Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

# حفظه:
with open("document.md", "w") as f:
    f.write(md_text)

في سطر واحد، كما وعدنا:

python3 -c "import pymupdf4llm; \
  open('document.md','w').write(pymupdf4llm.to_markdown('document.pdf'))"

متى تختار PyMuPDF4LLM بدلًا من MarkItDown

• عندما يحتوي ملف PDF على روابط كثيرة تريد الحفاظ عليها (فـMarkItDown يفقدها).
• عندما يكون المستند ممسوحًا ضوئيًا وتحتاج إلى OCR.
• عندما تحتاج إلى سرعة في معالجة آلاف الملفات محليًا؛ فمحرك C الأصلي أسرع من أغلفة Python.
• عندما تحتاج إلى استخراج صور PDF إلى مجلد منفصل لمزيد من المعالجة.

تفاصيل الترخيص (مهمة للأعمال)

يخضع PyMuPDF4LLM لترخيص مزدوج: AGPL v3 أو ترخيص Artifex التجاري.

معنى AGPL: إذا استخدمت المكتبة في خدمة SaaS عامة، فعليك نشر كامل الشيفرة المصدرية للخدمة بموجب ترخيص AGPL نفسه. أما الاستخدام الداخلي (تشغيل النص البرمجي على حاسوبك المحمول) فلا تقيّده أي شروط.

للتطوير التجاري من دون الإفصاح عن الكود، اشترِ ترخيصًا من Artifex (artifex.com). الأسعار غير منشورة؛ اطلبها من فريق المبيعات.

إذا كنت تبني منتجًا للعملاء، فتحقّق من الترخيص منذ البداية. MarkItDown (MIT) وDocling (MIT) خياران أكثر أمانًا لخدمات SaaS.

الطريقة 3: كيف تربط خادم MarkItDown MCP بـClaude Code؟#

يعني MarkItDown في وضع CLI: «أحوّل الملفات يدويًا مسبقًا»؛ أما خادم MCP فيعني: «يقرر Claude Code متى يحوّلها».

التثبيت

تحتاج إلى مدير الحزم uv. لا حاجة إلى تثبيت الخادم بشكل منفصل؛ إذ ينزّله uv عند تشغيله أول مرة.

الإعداد في Claude Code

يربط أمر واحد الخادم بجميع مشاريعك مع تثبيت الإصدار:

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

ينبغي أن يظهر بجوار markitdown وصف “Connected”. ينزّل التشغيل الأول نحو 70 حزمة وقد يستغرق دقيقة؛ وبعدها يبدأ الخادم خلال ثانية أو ثانيتين.

إليك سبب الحاجة إلى المتغيرين في الأمر. يعطّل ORT_DISABLE_TELEMETRY=1 الإحصاءات التي يرسلها محرك onnxruntime المضمّن في الخادم إلى Microsoft افتراضيًا على Mac وLinux. ويشغّل UV_PYTHON=3.12 الخادم باستخدام Python 3.12، الذي تتوفر له حزم مُعدّة مسبقًا على Windows وLinux وأجهزة Mac المزودة بمعالجات Apple Silicon. وعلى أجهزة Intel Mac وmacOS 13 والإصدارات الأقدم، لا يُثبّت الخادم باستخدام Python 3.14. ثمة ملاحظة تخص Intel و3.12: سيبني uv مكتبة cryptography من المصدر، لأن حزمة Intel مُعدّة مسبقًا غير متاحة منذ يونيو 2026. يستغرق التثبيت وقتًا أطول وقد يفشل. إذا لم يكن Python 3.12 مثبتًا لديك، فسينزّله uv.

يعمل الخادم مباشرةً على حاسوبك ويمكنه فتح أي ملف تستطيع الوصول إليه. إذا كان Claude Code مفتوحًا، فأعد تشغيله؛ وسيظهر markitdown في قائمة خوادم MCP.

طريقة الاستخدام

قل ببساطة في Claude Code:

حوّل /Users/your-user/Documents/report.pdf إلى Markdown وحلّل النقاط الرئيسية.

يستدعي Claude الأداة convert_to_markdown(uri) بنفسه، ويحصل على Markdown، ثم يعمل عليه؛ ولا يُحمّل ملف PDF إلى السياق أصلًا.

عناوين URI المدعومة

• file:// - الملفات المحلية
• http:// وhttps:// - المستندات المتاحة على الإنترنت
• data: - بيانات مضمنة (Base64)

الأمان

من ملف README الرسمي:

يرتبط الخادم افتراضيًا بـlocalhost. إذا شغّلته عبر HTTP/SSE (الخيار --http --host 127.0.0.1 --port 3001)، فلا تكشف المنفذ للعامة من دون وكيل عكسي يتطلب المصادقة.

أي طريقة تختار لمهمتك؟#

جدول مقارنة موسّع:

ينشر Marker أرقامًا لافتة للدقة في الاختبارات المعيارية:

لكن Marker يحتاج إلى GPU لتحقيق سرعة جيدة، كما يضم نماذج تعلّم آلي. أما معظم المهام (ملفات PDF النصية العادية)، فيمكن إنجازها باستخدام PyMuPDF4LLM أو MarkItDown خلال ثوانٍ ومن دون GPU.

قاعدة بسيطة للاختيار

1. ملف PDF واحد أو اثنان، وتريد إنجازهما بسرعة - MarkItDown CLI.
2. عشرات ملفات PDF وتحتاج إلى الأتمتة - خادم MarkItDown MCP أو PyMuPDF4LLM ضمن نص برمجي.
3. ملفات PDF تحوي روابط وصورًا، والحفاظ على بنيتها مهم - PyMuPDF4LLM.
4. RAG للإنتاج في الأعمال، حيث ثبات الجداول مهم - Docling.
5. أوراق علمية تتضمن صيغًا رياضية - Marker.
6. لا تريد التفكير في الأمر، ودع Claude يحوّل الملف - خادم MarkItDown MCP.

كيف تكتب نصًا برمجيًا جاهزًا لتحويل مجلد من المستندات تلقائيًا؟#

مثال عملي: تخيّل أن لديك 40 تقريرًا بصيغة PDF وPPTX من عملاء في مجلد واحد—كشوف حسابات الوساطة والعقود والعروض التقديمية. تحميل المجلد مباشرةً إلى Claude لن يفيد؛ فستمتلئ نافذة السياق بالمعلومات قبل أن تتلقى أول رد. مرّر المجلد كاملًا عبر النص البرمجي أدناه مرة واحدة، ثم تابع العمل على ملفات .md خفيفة بدلًا من ملفات PDF كبيرة.

احفظ هذا النص البرمجي في scripts/docs-to-md.sh في جذر المشروع:

#!/bin/bash
# docs-to-md.sh - يحوّل جميع المستندات في مجلد إلى Markdown باستخدام MarkItDown
# الاستخدام: bash docs-to-md.sh ./documents

set -e

INPUT_DIR="${1:-./documents}"
OUTPUT_DIR="${INPUT_DIR}/_md"

mkdir -p "$OUTPUT_DIR"

echo "Scanning $INPUT_DIR..."

for file in "$INPUT_DIR"/*.{pdf,docx,pptx,xlsx}; do
  [ -f "$file" ] || continue

  basename=$(basename "$file")
  name="${basename%.*}"
  output="$OUTPUT_DIR/${name}.md"

  if [ -f "$output" ] && [ "$output" -nt "$file" ]; then
    echo "Skipping $basename (already converted)"
    continue
  fi

  echo "Converting $basename..."
  markitdown "$file" > "$output"
done

echo "Done. Results are in $OUTPUT_DIR"

اجعله قابلًا للتنفيذ:

chmod +x scripts/docs-to-md.sh

شغّله:

bash scripts/docs-to-md.sh ./reports

بعد التشغيل، سيحتوي ./reports/_md/ على نسخ .md من جميع المستندات. أضفها إلى Claude Code باستخدام @reports/_md/، واعمل على النص المضغوط بدلًا من ملفات PDF.

يتخطى النص البرمجي تلقائيًا الملفات التي سبق تحويلها (إذا كان ملف .md أحدث من الملف المصدر)؛ لذا فإن إعادة تشغيله سريعة ولا تعيد حساب كل شيء.

idempotency والتحويل التدريجي

إذا أردت أن يكتشف النص البرمجي ملفات PDF التي تغيّرت (وأُعيد حفظها بالاسم نفسه)، فأضف فحصًا لبصمة المحتوى:

hash=$(shasum -a 256 "$file" | cut -d' ' -f1)
hash_file="$OUTPUT_DIR/.${name}.sha256"

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Skipping $basename (hash matches)"
  continue
fi

markitdown "$file" > "$output"
echo "$hash" > "$hash_file"

يعيد هذا الإصدار تحويل الملف فقط إذا تغيّر محتواه.

متى يكون استخدام PDF في Claude أفضل من Markdown؟#

ثلاث حالات لا يفي فيها التحويل إلى Markdown بالغرض:

1. التحليل البصري للمخططات والرسوم البيانية

إذا احتاج Claude إلى «قراءة» رسم بياني—مثل منحنى الأسعار أو مخطط عملية أو مخطط بنية—فلن تكون هذه المعلومات موجودة في Markdown. يحافظ Markdown على التعليقات التوضيحية للأشكال فقط؛ أما الشكل نفسه فيضيع.

الحل: حمّل ملف PDF وفعّل الوضع البصري صراحةً. يعمل الخيار تلقائيًا في Claude API؛ أما في AWS Bedrock فتحتاج إلى خيار citations.

2. الجداول المعقدة ذات الخلايا المدمجة

جداول Markdown مسطّحة. إذا احتوى ملف PDF على جدول بخلايا مدمجة أو رؤوس متعددة المستويات أو جداول فرعية متداخلة، فسيحوّله المحوّل إلى بنية مسطّحة أو يفقد الروابط بين أجزائه.

الحل: استخدم ملف PDF مباشرةً أو Docling (فهو الأفضل في التعامل مع الجداول المعقدة) أو نسّق الجدول يدويًا بعد التحويل.

3. المستندات بوصفها مراجع مع أرقام الصفحات

في المستندات القانونية والعقود ومحاضر الاجتماعات، من المهم أن تتمكن من الاستشهاد بعبارة «الصفحة 7، الفقرة 3». تضيع أرقام الصفحات في Markdown.

الحل: PDF + Files API + التخزين المؤقت للموجّهات. حمّله مرة واحدة، ثم أشِر إليه باستخدام file_id؛ عندها يرى Claude ترقيم الصفحات ويمكنه الاستشهاد بصفحات محددة.

المستندات القصيرة

إذا كان ملف PDF أقل من صفحتين وكنت ستستخدمه مرة واحدة، فلا يستحق التحويل. فالتوفير من 5,000 رمز لملف PDF إلى 800 رمز في Markdown لا يبرر تثبيت MarkItDown.

تبدأ نقطة التعادل عند نحو 5 صفحات أو أكثر، أو عند استخدام المستند نفسه مرتين أو أكثر. دون ذلك، حمّل ملف PDF مباشرةً؛ وفوق ذلك، حوّله.

ما الأخطاء الخمسة الأكثر شيوعًا عند استخدام ملفات PDF في Claude؟#

1. تحميل ملف PDF نفسه في كل محادثة جديدة

يفرض Claude Pro حدًا للرسائل على مدى 5 ساعات؛ وقد يستهلك تقرير واحد من 50 صفحة الحد كله قبل أن تطرح سؤالًا ثانيًا.

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

الحل: حوّله إلى Markdown مرة واحدة، أو استخدم Files API مع file_id والتخزين المؤقت للموجّهات.

2. استخدام لقطة شاشة بدلًا من النص

مثال شائع: يريد شخص أن يري Claude جزءًا من الكود أو جدولًا، فيأخذ لقطة شاشة للشاشة بأكملها بقياس 1920×1080، ثم يتساءل عن سبب نفاد الحد بعد 5 طلبات.

تكلّف لقطة شاشة بقياس 1000×1000 بكسل نحو 1,300 رمز. أما النص نفسه إذا نُسخ يدويًا فيكلّف 50–100 رمز. أي فرق يتراوح بين 13 و26 ضعفًا.

الحل: اقتطع لقطات الشاشة بدقة لتشمل الجزء المهم فقط، أو الأفضل من ذلك، انسخ النص مباشرةً.

3. ملف PDF ممسوح ضوئيًا بلا OCR

لا يستطيع MarkItDown إجراء OCR. إذا حوّلت ملفًا ممسوحًا ضوئيًا، فستكون النتيجة ملف .md فارغًا (أو 3 أسطر من التشويش).

الحل: استخدم PyMuPDF4LLM (مع OCR الذكي المضمّن فيه) أو Docling للملفات الممسوحة ضوئيًا.

4. تجاهل حد الصفحات البالغ 100 صفحة

تحدد وثائق Anthropic الحد الأقصى بـ600 صفحة للطلب، لكن الحد الفعلي للنماذج ذات سياق 200K (Sonnet 4.x وOpus 4.x) هو 100 صفحة. ويستهدف حد 600 صفحة النماذج الأقدم أو المستويات الخاصة.

إذا حمّلت تقريرًا من 150 صفحة إلى Sonnet 4.6، فستحصل على خطأ أو، ما هو أسوأ، سيعالج Claude أول 100 صفحة فقط ويتصرف كما لو أنه قرأ المستند كاملًا.

الحل: قسّم ملفات PDF الطويلة إلى أجزاء قبل تحميلها، أو حوّلها إلى Markdown؛ فلا يوجد حد للصفحات، بل حد للرموز فقط.

5. عدم استخدام التخزين المؤقت للموجّهات مع الطلبات المتكررة

إذا كنت تعمل على المستند نفسه عبر API، فأحط محتواه بـcache_control: ephemeral. تكلّف الطلبات المتكررة خلال 5 دقائق 10% من السعر الأولي. يكلّف الطلب الأول أكثر، وتحصل بقية الطلبات على خصم 90%.

الحل: فعّل التخزين المؤقت للموجّهات افتراضيًا لكل ما تحمّله أكثر من مرة.

الخطوة التالية: هندسة السياق#

تحويل PDF إلى Markdown طريقة لتوفير الرموز. لكنه وحده لا يجعل إجابات Claude أدق. تأتي الدقة من هندسة السياق—أي تحديد ما تضعه في سياق النموذج قبل طرح السؤال.

إذا احتوى ملف CLAUDE.md على 800 سطر، وضمّ مشروعك 10 خوادم MCP غير ضرورية، وأضفت ملف PDF من 100 صفحة، فسيمنع التحويل إلى Markdown أحد مصادر الهدر، لكن المصادر الثلاثة الأخرى ستبقى. لذلك تتناول هذه الأدلة ما يلي:

• أين تُستهلك الرموز في Claude Code - 9 أنماط لتسرّب السياق، وليس ملفات PDF فقط.
• هندسة السياق في 2026 - إدارة السياق بطريقة منهجية.
• وضع Plan Mode في Claude Code - وضع التخطيط قبل أن يبدأ Claude بكتابة الكود.