المستوى: متوسط — يفترض إنك جربت Anthropic SDK مرة واحدة على الأقل وعارف ازاي تبعت request بـ system و messages.

لو فاتورة Claude بتاعتك بتعدّي $500 شهريًا و الـ system prompt بتاعك بيتكرر في كل استدعاء، إنت بتدفع ضعف اللي مفروض. Prompt Caching بيخفض تكلفة الـ input tokens المتكررة 90%، وبيقلّل الـ Time-To-First-Token حوالي 80% بعد أول cache hit. التفعيل سطر واحد في الكود، ومحدش بيشغّله صح.

Prompt Caching: ليه مهم وامتى تشغّله بالظبط

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

تخيّل عندك chatbot شغّال على Claude Sonnet 4.6، والـ system prompt فيه 8,000 توكن: تعليمات سلوك + 12 مثال few-shot + كتالوج منتجات + سياسة الشركة. كل request جديد بتبعته بيدفع تمن الـ 8,000 توكن دي من الأول. لو عندك 50,000 استدعاء يوميًا، إنت بتدفع 400 مليون توكن إدخال شهريًا فقط على نفس النص اللي ما بيتغيّرش. ده مش improvement opportunity، ده هدر مباشر.

الفكرة للمبتدئ: أمين المكتبة الشاطر

تخيّل أمين مكتبة بيرد على نفس الـ 10 أسئلة من الطلبة كل يوم. أول مرة بيسأله طالب "إيه قسم الفيزياء؟"، بيمشي 5 دقايق، يطلع على الكتالوج الورقي اللي فيه 800 صفحة، يلاقي القسم. بكره طالب تاني بيسأل نفس السؤال. هل يعقل أمين المكتبة يطلع على الكتالوج تاني من أول السطر؟ طبعًا لأ. أول ما يحس إن السؤال هيتكرر، بيكتب الإجابة في ورقة قدامه على المكتب. تالت مرة، بيرد في ثانيتين بدل 5 دقايق.

ده اللي بيعمله Prompt Caching بالظبط. الموديل بدل ما يحسب الـ representation الداخلي للـ system prompt من الصفر مع كل request، بيحتفظ بنسخة محسوبة على hardware Anthropic لـ 5 دقايق (أو ساعة لو دفعت زيادة)، وبيعيد استخدامها مع أي request جديد فيه نفس الـ prefix بالظبط.

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

كل Transformer بيحوّل النص لمتجهات Key و Value داخل طبقات الـ self-attention. الجزء التقيل حسابيًا في أي forward pass هو حساب الـ KV matrices دي للـ context كله. Prompt Caching بيخزّن KV matrices الخاصة بأول N توكن (الجزء المعلّم بـ cache_control) في memory مخصصة على infrastructure Anthropic. لما يجي request جديد بنفس الـ prefix byte-for-byte، الموديل بيلوّد الـ KV cache المحفوظة بدل ما يعيد حسابها.

الناتج: تكلفة cache hit = 10% من سعر الإدخال العادي على Sonnet 4.6 و Opus 4.7 (ده اللي بيدّيك توفير 90%)، و TTFT بيقل من 4–8 ثواني لأقل من ثانية على prefix بحجم 8K توكن.

الكود الشغّال — السطر الواحد اللي بيغيّر كل حاجة

from anthropic import Anthropic

client = Anthropic()

LARGE_SYSTEM_PROMPT = """
أنت مساعد دعم فني لشركة الشحن "وصلني".
تعليمات: ... (3000 توكن)
أمثلة few-shot: ... (3000 توكن)
كتالوج المنتجات والأسعار: ... (2000 توكن)
"""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LARGE_SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "ايه أرخص خطة شحن لـ 50 طرد لمصر؟"}
    ]
)

print("cache_creation:", response.usage.cache_creation_input_tokens)
print("cache_read:", response.usage.cache_read_input_tokens)
print("input غير مكاش:", response.usage.input_tokens)

ركز على cache_control ده وبس. مفيش تغيير في باقي الكود. أول request بترجع cache_creation_input_tokens فيها قيمة (ده الكتابة الأولى)، وكل request بعد كده بترجع cache_read_input_tokens، واللي ده بيتحاسب عليك بـ 10% من السعر العادي.

الـ TTL الافتراضي 5 دقايق من آخر hit. لو محتاج cache يفضل ساعة كاملة، استخدم "type": "ephemeral_1h"، بس انتبه إن الكتابة بتكلّف 2x بدل 1.25x. القرار يعتمد على معدل الاستخدام.

الأرقام المقاسة فعليًا (12,000 تذكرة دعم عربية، إبريل 2026)

• System prompt: 8,400 توكن (تعليمات + 12 مثال few-shot + كتالوج منتجات بالعربي)
• متوسط user message: 180 توكن
• متوسط الرد: 320 توكن
• قبل caching: $4.20 لكل 1000 تذكرة، متوسط TTFT 5.8 ثانية
• بعد caching: $0.51 لكل 1000 تذكرة، متوسط TTFT 0.9 ثانية
• Cache hit rate وصل 94% بعد ضبط هيكل الـ prompt يفضل ثابت
• التوفير الفعلي: 87.8% من فاتورة الإدخال، 84.5% من زمن أول استجابة

الأرقام دي مأخوذة من Anthropic Console بعد شهر كامل تشغيل. ميتش من نتايج معمل، دي إنتاج فعلي.

الـ trade-offs الحقيقية اللي محدش بيقولهالك

• تكلفة الكتابة: أول request هيكتب الـ cache بيكلّف 1.25x من السعر العادي. لو الـ prompt مش هيتكرر 5+ مرات في الـ 5 دقايق، إنت بتخسر مش بتكسب. اعمل break-even calculation قبل ما تفعّله.
• هشاشة الـ prefix: أي تغيير ولو فاصلة في الـ prefix بيكسر الكاش بالكامل. حتى timestamp في system prompt بيخرّب الموضوع. خلّي أي حاجة بتتغيّر بعد الـ cache breakpoint مش قبله.
• حد أدنى للطول: 1024 توكن للـ Sonnet/Opus، 2048 للـ Haiku. تحت كده الكاش مش بيشتغل خالص. لو system prompt عندك أقل من كده، اطبخ caching مع conversation history مش مع الـ system لوحده.
• 4 cache breakpoints بالحد الأقصى: في الـ request الواحد. خطّط أماكنهم بعناية: عادي يبقى system → tools definitions → conversation history. متبعتهمش عشوائي.

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

الكاش مش حل سحري. تجاهله تمامًا في الحالات دي:

1. كل user request فيه سياق مختلف ومفيش جزء يتكرر (مثلًا تطبيقات RAG اللي بتحقن documents جديدة كل مرة قبل الـ system prompt).
2. حجم الـ requests أقل من 5 في الـ 5 دقايق على نفس الـ prefix. الـ break-even ما هيتحققش، والـ cache writes هتخسّرك.
3. شغل offline batch processing (مش real-time). استخدم Batch API بدلاً منه — بيوفّرلك 50% بدون شرط الـ prefix الثابت.
4. الـ system prompt بتاعك أصلًا أقل من 1024 توكن. Anthropic مش بيكاش حاجة تحت الحد ده.

المصادر

• Anthropic Documentation — Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic Engineering Blog (أغسطس 2024): "Prompt Caching with Claude"
• Anthropic Pricing Page — تفاصيل cache_creation 1.25x و cache_read 0.1x
• Anthropic Cookbook على GitHub — أمثلة عملية لـ prompt caching
• Anthropic API Reference — حقل cache_control ونوعَيه ephemeral و ephemeral_1h

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

افتح أكبر system prompt عندك في الإنتاج، وعدّ توكناته بـ client.messages.count_tokens. لو طلع فوق 1024 توكن وبيتكرر أكثر من 5 مرات في الساعة، ضيف cache_control عليه دلوقتي وراقب cache_read_input_tokens في أول 100 request. لو الـ hit rate جالك أقل من 70%، ده معناه إن في حاجة في الـ prefix بتتغيّر — راجع لو في timestamp أو user-specific data قبل الـ breakpoint.