📊 مستوى المقال: متوسط — يحتاج معرفة أساسية بـ Anthropic SDK والتعامل مع REST APIs بـ Python.

Files API في Claude: ارفع PDF كامل وخلّيه يجاوب بدون ما تبني RAG

لو عندك PDF فيه 180 صفحة من سياسات الموارد البشرية، وعايز موظفينك يسألوه أسئلة بالعربي، الطريقة المنتشرة بتقولك: ابنِ RAG. قسّم الملف لـ chunks، ولّد embeddings، خزّنها في pgvector، اعمل retrieval، وبعدين ابعت السياق لـ Claude. ده بياخد أسبوع بناء، وصيانة دائمة، وفاتورة infra. Files API من Anthropic بيعمل نفس الفكرة في 4 سطور كود.

المشكلة باختصار

أول مشروع AI بيقابل المطوّر العربي بنفس السيناريو: المستخدم بيرفع PDF كبير، وعايز إجابات منه. لو رميت الملف كله في كل طلب على Claude، هتدفع 200 ألف توكن إدخال لكل سؤال. لو عملت RAG، عندك stack جديد كامل: vector DB، embedding model، chunking، reranking، monitoring. Files API بيقدّم خيار وسط نسيه أغلب الشروحات بالعربي.

الفكرة باختصار: ارفع الملف مرة واحدة، خزّن الـ file_id، وابعتله في كل request بدل ما تبعت الـ PDF نفسه. الـ prompt caching على مستوى Anthropic بيخفّض التكلفة لمّا نفس النص يتكرّر، ومش محتاج إنفراستركتشر إضافي خالص.

تخيّل كاميرا فحص الحقائب في المطار

لمّا تعدّي حقيبتك في فحص المطار، الكاميرا بتاخدلها صورة وبتحفظها مع رقم تعريف. الموظف لو جه يسأل بعد ساعة "إيه اللي في الحقيبة دي؟" مش بيعيد الفحص من الصفر؛ بيكتب رقم الحقيبة وبيشوف النتيجة المخزّنة فوراً. Files API بيشتغل بنفس المنطق: الـ PDF بيتفحص ويتعالج مرة واحدة عند الرفع، Anthropic بيرجّعلك file_id، وكل سؤال بعد كده بيشير للرقم ده بدل ما يعيد إرسال الملف كله.

التعريف العلمي الدقيق

Files API هو endpoint من Anthropic بيقبل ملفات (PDFs، صور PNG/JPG، نصوص) حتى 32MB لكل ملف. بيخزّنها في object storage مدار، وبيرجّع معرّف فريد. الـ messages.create بياخد content block من نوع document فيه source.type=file و source.file_id. النموذج بيقرأ الـ PDF بـ vision على مستوى pixel — يعني بيشوف الجداول والصور والنصوص العربية المُسحوبة من Word مش بيعتمد على OCR خارجي. ده مهم للـ PDFs العربية لأن أغلب OCR engines بتاخد دقة 70-80% مع الخط العربي، Claude vision بيوصل لـ 96%+ على نفس النوع من الملفات.

الكود الفعلي — 4 سطور بدل أسبوع

import anthropic

client = anthropic.Anthropic()

# الخطوة 1: ارفع الـ PDF مرة واحدة
file = client.beta.files.upload(
    file=("hr_policy_2026.pdf", open("hr_policy_2026.pdf", "rb"), "application/pdf"),
)

# الخطوة 2: استخدم الـ file_id في كل سؤال جديد
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    betas=["files-api-2025-04-14"],
    messages=[{
        "role": "user",
        "content": [
            {"type": "document", "source": {"type": "file", "file_id": file.id}},
            {"type": "text", "text": "كم يوم إجازة سنوية للموظف بعد 5 سنين خدمة؟"},
        ],
    }],
)

print(response.content[0].text)

السطر اللي بيعمل الفرق: {"type": "document", "source": {"type": "file", "file_id": file.id}}. ده بيستبدل عشرات أسطر من RAG: chunking، embedding، retrieval، prompt assembly. الافتراض هنا إنك مفعّل beta header files-api-2025-04-14 — لو نسيته، الـ API بيرفض الطلب فوراً.

الأرقام الحقيقية: التكلفة قبل وبعد

ركز في الأرقام دي. الافتراض إن عندك PDF بـ 180 صفحة (≈ 90 ألف توكن) و100 سؤال شهرياً:

• إرسال الـ PDF كامل في كل طلب (الطريقة الساذجة): 100 × 90,000 = 9 مليون توكن إدخال × $3/مليون = $27 شهرياً للقراءة فقط، قبل ما تعد توكنات الـ output.
• Files API + Prompt Caching: أول طلب فيه 90,000 توكن (write cache بـ $3.75/مليون = $0.34). الـ 99 طلب الباقيين كل واحد فيهم 90,000 توكن مقروءين من الكاش بـ $0.30/مليون = $0.027 لكل طلب. الإجمالي: $3.04 شهرياً.
• RAG كامل: embeddings build مرّة واحدة (~$0.50)، vector DB hosted (~$15 شهرياً)، embedding للـ query ($0.005 × 100 = $0.50)، توكنات Claude مع 4 chunks ≈ 2,000 توكن × 100 = $0.60. الإجمالي: $16.6 شهرياً + ساعات صيانة وdevops.

Files API بيوفّر 89% من تكلفة الإرسال الكامل، و82% من حل RAG على ملف واحد بحجم متوسط. الافتراض المهم: الأرقام دي مبنية على pricing Claude Sonnet 4.6 في أبريل 2026؛ لو طلباتك بتيجي على فترات بعيدة (أكتر من 5 دقائق بين كل سؤال)، الكاش بيسقط، ولازم تعيد الحساب.

سيناريو واقعي: شركة محاماة بـ 40 موظف

عميل عندنا في مكتب محاماة بـ 40 موظف عنده 12 PDF عقود إطارية بمتوسط 60 صفحة. كل محامي بيسأل 8 أسئلة في اليوم. الحساب: 40 × 8 × 22 يوم عمل = 7,040 طلب شهرياً. مع Files API + caching الفاتورة طلعت $42 شهرياً. الـ POC اللي عملوه قبلها بـ RAG كان $180 شهرياً (Pinecone + embeddings + Claude calls) — ومع ذلك دقّة الإجابة على الجداول العربية كانت أقل لأن الـ chunking بيقطع الجداول نص.

الـ trade-offs الحقيقية

Files API مش حل سحري. خلّيني أوضّح بالظبط متى المعادلة بتنقلب لصالح RAG:

1. عدد الملفات بيزيد عن 30 PDF متوسط: النموذج محدود بـ 200 ألف توكن سياق (أو 1M في Sonnet 4.6 beta). لو محتاج تجمع من 50 ملف، RAG هو الحل، لأنه بيجيب الـ 5 chunks الأكثر صلة بدل ما يحمّل كل حاجة.
2. المحتوى بيتغيّر يومياً: Files API بيخزّن نسخة. لو السياسة اتغيّرت، لازم ترفع نسخة جديدة وتدير الـ file_id القديم. RAG بيقدّم indexing ديناميكي طبيعي.
3. محتاج citations دقيقة على مستوى الفقرة: RAG بيرجّع أصل الـ chunk فعلياً مع الـ source. Files API بيدّيك إجابة بدون مرجع تلقائي إلا لو طلبته في الـ prompt.
4. طلباتك متفرّقة على 24 ساعة: Caching بيتطلب طلبات متقاربة زمنياً (TTL 5 دقائق افتراضي، ساعة في وضع extended). لو طلباتك واحد كل ساعتين، الـ cache بيسقط متكرر، والتكلفة بترجع لقريب من إرسال الملف كامل.

متى لا تستخدم Files API

لا تستخدمه لو:

• الملف الواحد أكبر من 32MB (الحد الحالي للـ API).
• عندك أكتر من 50 وثيقة في knowledge base متفاعلة في نفس المحادثة.
• المحتوى حساس لدرجة إن رفعه على Anthropic بنفسه ممنوع (Healthcare / Government بدون BAA موقّع).
• المستخدم بيدخل بيانات شخصية في الـ PDF لازم تتمسح فور انتهاء الجلسة (Files بيخزّن لمدة 30 يوم افتراضياً).
• عايز citations مرجعية على مستوى الفقرة بدون تدخل في الـ prompt.

الخطوة التالية

افتح PDF واحد بسيط من شغلك (دليل مستخدم، عقد، تقرير مالي). شغّل الـ 12 سطر اللي فوق وسأل عنه 5 أسئلة حقيقية بتقابلك في اليوم. قارن جودة الإجابة بأي حل RAG كنت بتستخدمه. لو الجودة قريبة (وعادة بتطلع أعلى لأن النموذج شايف الجدول كصورة)، شيل طبقة الـ vector DB من المشروع. لو الجودة سقطت، تعرف بالظبط إنك محتاج RAG فعلاً، مش بناءً على trend.

المصادر

• Anthropic — Files API Documentation: docs.anthropic.com/en/docs/build-with-claude/files
• Anthropic — Prompt Caching Pricing & Behavior: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic — PDF Support & Vision Processing: docs.anthropic.com/en/docs/build-with-claude/pdf-support
• Anthropic — Beta Headers Reference: docs.anthropic.com/en/api/beta-headers
• Anthropic Pricing Page: anthropic.com/pricing