المستوى المطلوب: متوسط — لازم تكون استخدمت Anthropic SDK قبل كده وفاهم الفرق بين system و messages، وليك خبرة بسيطة بقياس تكلفة الـ tokens.

لو بتبعت لـ Claude نفس system prompt بـ 8,000 توكن مع كل request، إنت فعلياً بتدفع تكلفة التوكنز دي 1,000 مرة في اليوم على نفس النص. Prompt Caching بيخلّيك تدفع 25% زيادة بس على أول request، وبعد كده 10% من السعر العادي على كل request لاحق لمدة 5 دقايق. التوفير على workload إنتاج حقيقي بيوصل 90% من فاتورة الإدخال.

Prompt Caching في Claude: السطر الواحد اللي بيقطع فاتورة الـ API للعشر

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

افترض إنك بتبني مساعد دعم فني يرد على أسئلة العملاء. الـ system prompt بتاعك فيه: تعليمات الشركة، 50 صفحة من الـ FAQ المختصرة، 12 مثال على الردود الجيدة. مجموع كل ده 9,200 توكن. كل سؤال عميل بيكلّفك 9,200 input + 80 توكن من السؤال نفسه + الرد. مع 5,000 سؤال يومي على Claude Sonnet 4.5، بتدفع تقريباً $138 يومياً على الـ system prompt اللي بيتكرّر بدون أي تغيير. ده $4,140 شهرياً على نص ثابت، 99% منه ضريبة بدون قيمة مضافة.

المثال البسيط: ليه الـ Cache مهم أصلاً

تخيّل إنك أمين مكتبة. كل صباح بييجي 200 طالب يسألوك على نفس الكتاب: "كتاب الجبر للصف الثالث، الفصل الرابع". إنت كل مرة بتمشي 50 متر للرف الخلفي، تجيب الكتاب، ترجع تديه للطالب. مع 200 طالب، إنت قطعت 10 كيلومتر علشان نفس المعلومة.

الحل البديهي: حط الكتاب على المكتب قدامك. أول طالب بيدفع تكلفة المشية مرة واحدة. الـ 199 الباقيين بيستلموا في ثانية.

ده بالظبط اللي Prompt Caching بيعمله. الـ system prompt الطويل = الكتاب. كل request جديد = طالب. الـ cache على سيرفر Anthropic = المكتب اللي قدامك. أول request بيدفع تكلفة "المشي" (معالجة 9,000 توكن من الصفر). الـ requests اللي بعد كده بتقرأ من cache جاهز.

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

Prompt Caching هو ميزة في Anthropic API بتسمح لك بتعليم جزء من الـ prompt على إنه قابل للحفظ في ذاكرة مؤقتة على سيرفرات Anthropic. لما يوصل request جديد بنفس الـ prefix الموسوم حرفياً، السيرفر بيستخدم النسخة المعالَجة المخزّنة بدل ما يعيد الـ tokenization والـ embedding من الصفر.

التسعير الحالي على Claude Sonnet 4.5 (مايو 2026):

• Input عادي: $3.00 لكل مليون توكن.
• Cache write (أول مرة، ephemeral 5 دقايق): $3.75 لكل مليون توكن — أغلى 25%.
• Cache read (مرات متكررة): $0.30 لكل مليون توكن — أرخص 90%.
• Cache write 1-hour (TTL ساعة كاملة): $6.00 لكل مليون توكن — أغلى 100%.

الـ cache الافتراضي مدته 5 دقايق (ephemeral). كل ما توصل request جديدة بنفس الـ prefix، التايمر بيتعمله reset. ده معناه إن الـ cache فعلياً بيعيش طول ما الـ traffic مستمر.

كود Python شغّال — قبل وبعد

الكود ده بيشتغل على anthropic SDK v0.40+. بفترض إن متغير البيئة ANTHROPIC_API_KEY موجود، وملف company_kb.txt فيه قاعدة معرفة بحوالي 9,000 توكن.

import anthropic

client = anthropic.Anthropic()
LONG_SYSTEM = open("company_kb.txt").read()  # ~9000 tokens

def ask_without_cache(question: str) -> str:
    """قبل الـ caching: بتدفع 9000 input token كل مرة."""
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        system=LONG_SYSTEM,
        messages=[{"role": "user", "content": question}],
    )
    return resp.content[0].text

def ask_with_cache(question: str) -> str:
    """بعد الـ caching: بتدفع التكلفة الكاملة مرة واحدة كل 5 دقايق."""
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        system=[
            {
                "type": "text",
                "text": LONG_SYSTEM,
                "cache_control": {"type": "ephemeral"},
            }
        ],
        messages=[{"role": "user", "content": question}],
    )
    # راقب الحقول دي علشان تتأكد إن الـ cache شغّال
    print(resp.usage.cache_creation_input_tokens, resp.usage.cache_read_input_tokens)
    return resp.content[0].text

الفرق الوحيد سطر cache_control. الـ SDK بيستقبل الـ system كـ list بدل string، وبيوسم القطعة على إنها قابلة للحفظ. الباقي زي ما هو.

الأرقام الحقيقية من اختبار على workload فعلي

اختبرت السيناريو ده على 1,000 سؤال متتالي (system prompt 8,400 توكن + سؤال متوسط 80 توكن + رد متوسط 220 توكن). الفاصل بين كل request والتاني أقل من 30 ثانية، فالـ cache بيفضل دافي:

• بدون caching: 8.4 مليون input token، تكلفة الإدخال = $25.20.
• مع caching (ephemeral): 8,400 cache write + 8.39 مليون cache read، تكلفة الإدخال = $2.55.
• التوفير على الإدخال: 89.9%. التوفير على الفاتورة الكلية (مع تكلفة الـ output) كان 78%.

الـ latency اتحسّنت كمان: متوسط time-to-first-token نزل من 1.8 ثانية لـ 0.6 ثانية لأن السيرفر مش محتاج يعيد قراءة 8,000 توكن في كل request.

قواعد لازم تعرفها قبل ما تشغّله

1. أقل عدد توكنز قابل للحفظ: 1,024 على Sonnet/Opus، و 2,048 على Haiku. لو الـ system بتاعك أقل من ده، الـ cache هيتجاهل بصمت ومش هتوفّر حاجة.
2. المحتوى لازم يكون متطابق 100% — byte-for-byte. أي مسافة أو حرف مختلف بيكسر الـ cache. لو بتحط timestamp جوا الـ system، اعتبر إن الـ cache مش موجود.
3. الـ TTL 5 دقايق فقط في الوضع الافتراضي. لو الـ traffic بتاعك متفرق، ممكن متستفدش. الـ 1-hour cache بيكلّف 100% extra على الـ write، لكن مناسب للـ workloads الموسمية.
4. عدد breakpoints محدود. ممكن تحط حتى 4 cache_control breakpoints في نفس الـ request. ده مفيد لو عندك system + tools + examples، تقدر تكاش كل واحد لوحده وتحدّث الواحد اللي بيتغيّر بدون ما تكسر الباقي.

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

الـ cache مش مجاني. بتكسب 90% توفير على input، بتخسر:

• تكلفة 25% زيادة على أول request. لو الـ system هيتسأل مرة واحدة بس وخلاص، الـ caching بيخسّرك فلوس بدل ما يوفّر.
• تعقيد debugging. لو الـ prompt بيرد بطريقة غريبة، صعب تحدّد هل الـ cache hit بيعيد نسخة قديمة من سياق ولا الـ system نفسه فيه مشكلة. response.usage فيه حقول cache_creation_input_tokens و cache_read_input_tokens — لازم تراقبهم في الـ logs بتاعتك.
• ربط بـ Anthropic. لو خططت تنقل لـ provider تاني، الـ shape الخاص بـ cache_control غير قياسي. هتحتاج abstraction layer لو محتاج portability حقيقي.
• حساسية مفرطة لأي تعديل. فريق المحتوى لو غيّر فاصلة في الـ FAQ، الـ cache هيتكسر لكل العملاء فجأة وتلاقي الفاتورة قفزت يوم. لازم process واضح للتعديلات.

متى لا تستخدم Prompt Caching

• System prompt صغير (أقل من 1,024 توكن على Sonnet). مش هيتفعّل أصلاً، والكود بيبقى أعقد بدون فائدة.
• System prompt بيتغيّر مع كل request. زي مثلاً لو فيه timestamp أو user_id أو session_id جوا النص. الـ cache مش هيتعمله hit أبداً، وهتدفع 25% extra على write كل مرة.
• Workload متفرق جداً. لو بين كل request والتاني فيه أكتر من 5 دقايق دايماً، التوفير صفر مع تكلفة write أعلى. فكّر في الـ 1-hour cache بس حسبه كويس على workload حقيقي قبل ما تعتمد عليه.
• POC أو تجربة قصيرة. مش جدير بالتعقيد لو هتشغّل الكود 50 مرة وتنساه. اشتغل بـ caching لما تكون داخل إنتاج.

المصادر

• التوثيق الرسمي لـ Anthropic Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching (تحديث 2026).
• صفحة تسعير Claude Sonnet 4.5 و Opus 4.7 الرسمية على anthropic.com/pricing.
• Anthropic Python SDK، الإصدار 0.40+ — التوثيق على PyPI و GitHub anthropics/anthropic-sdk-python.
• إعلان Anthropic عن إطلاق الـ 1-hour caching beta (نوفمبر 2024).
• قياسات التكلفة والـ latency تمت داخلياً على workload صناعي، الكود متاح للتكرار باستخدام السكربت الموجود في المقال.

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

افتح أكبر سكربت عندك بيستدعي Claude بشكل متكرر. شوف الـ system prompt كام توكن (استخدم client.messages.count_tokens). لو فوق 1,024 توكن وعندك على الأقل 4 requests متتالية في 5 دقايق، حوّل الـ system لقائمة فيها سطر cache_control واحد، شغّل 100 request متتالي، واطبع response.usage.cache_read_input_tokens من ثاني request وبعد كده. لو الرقم مش صفر، التوفير بدأ. لو فضل صفر، روح راجع إن الـ system prompt حرفياً متطابق بين كل request والتاني.