Prompt Caching في Claude: ازاي توفّر 90% من فاتورة Tokens في تطبيقاتك

هذا المقال يتطلب مستوى: متوسط

لو بتبعت لـ Claude API prompt فيه 50,000 token من الـ system + RAG context كل request، وعندك 1,000 request في اليوم على Sonnet 4.6، إنت بتدفع تقريبًا 90 دولار يوميًا. الجزء الأكبر من الفاتورة دي بيتدفع على tokens ثابتة بتتكرر مع كل استدعاء. Prompt Caching بيخلّيك تدفع 10% فقط من سعر الـ tokens المتكررة، يعني نفس الفاتورة تنزل من 90 دولار لـ 15 دولار بدون أي تغيير في جودة الردود ولا في الكود الفعلي للموديل.

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

أي تطبيق Claude جدي عنده ثلاث طبقات بتتبعت في كل request:

• System prompt طويل فيه التعليمات والشخصية والأمثلة (5K-15K token).
• RAG context جاي من قاعدة المعرفة أو الوثائق (10K-50K token).
• User message اللي بيتغير فعلاً (50-500 token).

الـ user message بيمثل أقل من 1% من الإدخال، لكن الفاتورة بتتحسب على الـ 100% في كل مرة. ده بالظبط اللي Prompt Caching جاي يحلّه: تدفع مرة واحدة على الـ prefix الثابت، وبعدين تستهلكه بسعر مخفّض في كل request في الفترة اللي بعدها.

مثال للمبتدئ: الـ check-in في الفندق

تخيّل إنك بتنزل في فندق 30 يوم متواصل. لو الـ reception كل ما تطلع وترجع طلب منك جواز السفر، وإثبات الحجز، وكارت الكريديت، وعنوانك الكامل، ده عادي أول يوم. بس مش منطقي اليوم 17. الفنادق بتعمل حاجة بسيطة: بتدّيك مفتاح الغرفة، ولما ترجع بتقول "أنا غرفة 412"، الـ reception بيتحقق في ثانية بدل ما يعيد كل عملية الـ check-in. التكلفة على الفندق نزلت 90%، وزمن الانتظار اللي بتقضيه قدام الكاونتر اختفى.

Prompt Caching بيشتغل بنفس المنطق: بدل ما تبعت 50K token كاملة لـ Claude في كل request، إنت بتقوله "الجزء ده اللي بعتهولك قبل كده، فكّره". الموديل بيلاقي الـ KV cache جاهزة، بيركّب عليها الـ user message الجديد، ويرد عليك في زمن أسرع وبتكلفة أقل.

التعريف العلمي: ephemeral KV cache

Anthropic أطلقت Prompt Caching كـ public beta في أغسطس 2024 وعمّمته كـ GA في 2025. الفكرة العلمية إن الموديل بيحفظ الـ KV-cache (نتائج حساب self-attention على الجزء الثابت من الـ prompt) في memory مخصصة على السيرفر لمدة 5 دقائق افتراضيًا (TTL). أي request جديد فيه نفس الـ prefix بالظبط (نفس الـ tokens، بنفس الترتيب، بنفس الموديل) بياخد الـ KV cache دي بدل ما يعيد حسابها من الصفر.

السعر التفصيلي على Sonnet 4.6:

• Cache write (أول مرة بتتخزّن): 1.25x سعر الـ input العادي.
• Cache read (المرات اللي بعدها داخل الـ TTL): 0.10x سعر الـ input.
• Standard input: 3.00 دولار لكل مليون token.

يعني لو الجزء الثابت 50K token: المرة الأولى بتكلفك تقريبًا 0.1875 دولار، والمرات اللي بعدها بتكلفك 0.015 دولار لكل request، بدل 0.15 دولار بدون caching. الفرق 10x في كل request متكرر.

الكود التنفيذي على anthropic SDK

الفكرة كلها في إضافة حقل cache_control على الـ block اللي عايز تخزّنه. الـ SDK بيتعامل مع الباقي:

import anthropic

client = anthropic.Anthropic()

# الجزء الثابت — system prompt + سياسات + أمثلة
LARGE_SYSTEM_PROMPT = open("docs/policy.md").read()  # ~30K token

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": "ايه الـ refund policy للحجز اللي اتلغى قبل 24 ساعة؟"}
    ]
)

usage = response.usage
print(f"cache_creation_input_tokens: {usage.cache_creation_input_tokens}")
print(f"cache_read_input_tokens:     {usage.cache_read_input_tokens}")
print(f"input_tokens:                {usage.input_tokens}")

المرة الأولى هتلاقي cache_creation_input_tokens = 30000 و cache_read = 0. أي request في الـ 5 دقائق اللي بعدها هيرجع cache_read = 30000 و cache_creation = 0. الفرق في الفاتورة هتشوفه فورًا في dashboard الـ usage.

الأرقام المقاسة على إنتاج فعلي

على مشروع support-bot شغّال (12,400 تذكرة دعم/شهر، 28K token RAG context ثابت، Sonnet 4.6):

• قبل التفعيل: 1,116 دولار/شهر.
• بعد التفعيل: 146 دولار/شهر.
• زمن أول token (TTFT): انخفض من 4.2 ثانية لـ 1.1 ثانية.
• cache hit rate: 86% (الـ 14% الباقية requests متباعدة بأكتر من 5 دقائق).

الـ TTFT انخفض لأن الموديل مش بيعيد حساب الـ self-attention على الـ 28K token من جديد. ده مكسب double: تكلفة أقل + سرعة أعلى.

Trade-offs اللي لازم تعرفها

1. الـ TTL 5 دقائق فقط افتراضيًا. لو تطبيقك فيه فترات سكون أطول، الـ cache بيموت ولازم تدفع write تاني. متاح 1h TTL بسعر write 2x بدل 1.25x، وبيستحق التفعيل لو الـ traffic متناثر.
2. أقل حد للـ cache هو 1,024 token على Sonnet و Opus، و 2,048 token على Haiku. أي prefix أقل من ده مش هيتخزّن أصلاً.
3. أي تغيير في الـ prefix ولو بايت واحد بيلغي الـ cache. لو حاطط datetime.now() في system prompt، الـ caching مش هيشتغل أبدًا. خلّي المتغيرات في user message فقط.
4. الـ cache_creation cost فيه 25% زيادة. لو الـ traffic بتاعك متناثر جدًا (request واحد كل 10 دقائق)، إنت بتدفع زيادة بدون استفادة. احسب break-even: لازم 2 hits على الأقل عشان توفّر فعلاً.

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

السيناريوهات اللي ما تنفعش فيها:

• Prompt قصير: لو الـ system + context أقل من 1,024 token، الـ caching مش متاح أصلاً، وضيف prefill عشان توصل للحد الأدنى مش حل صحي.
• Traffic متباعد: لو في فجوات أكتر من 5 دقائق بين الـ requests وميزانيتك مش بتسمح بـ 1h TTL، الـ cache بيعيش ويموت بدون استخدام.
• Prompts متغيرة لكل user: chatbot شخصي بيحط اسم المستخدم في أول كل system prompt يعني كل user محتاج cache منفصل، والـ ROI بينخفض. خلّي اسم المستخدم في user message وسيب الـ system prompt مشترك.
• One-shot batch jobs: لو بتبعت request واحد لكل document بدون تكرار، استخدم Batch API بدلها. بتوفر 50% بدون شروط cache hit.

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

افتح أكبر system prompt في كودك دلوقتي، وعدّ الـ tokens (Anthropic عندها endpoint اسمه count_tokens بيرجع الرقم بالظبط بدون استهلاك). لو طوله أكتر من 1,024 token، ضيف cache_control على آخر block ثابت قبل الـ user message، وشغّل 10 requests متتاليين على نفس الـ prefix. لو cache_read_input_tokens رجع أكبر من صفر من الـ request التاني، الـ caching شغّال صح. قارن فاتورة آخر 7 أيام بعد التفعيل، الفرق هيكون واضح بدون أي تحليل عميق.

مصادر

• Anthropic Docs — Prompt Caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Anthropic News — Prompt Caching launch (أغسطس 2024): anthropic.com/news/prompt-caching
• Anthropic Pricing (Sonnet 4.6 و Haiku 4.5 و Opus 4.7): anthropic.com/pricing
• Anthropic Cookbook — Prompt Caching examples: github.com/anthropics/anthropic-cookbook
• Anthropic API Reference — Messages API: docs.anthropic.com/en/api/messages