المستوى المطلوب: متوسط — مناسب للمطور اللي بنى تكامل واحد على الأقل مع Claude API أو أي LLM، عارف يفرّق بين system prompt و user message، ومتعامل قبل كده مع `usage` object في الردود.

Prompt Caching في Claude: قلّل فاتورة الـ System Prompt 89% بسطر واحد

لو chatbot شركتك بيرسل system prompt حجمه 22,000 token مع كل سؤال، انت بتدفع $0.066 لكل طلب من جيبك بدون داعي. Prompt Caching في Claude Sonnet 4.6 بيخلّي نفس الـ prefix يتكرر بـ 10% من السعر الأصلي بعد أول مرة، وبسطر واحد إضافي في الـ payload. مفيش مكتبة جديدة، مفيش setup سيرفر، مفيش redeploy.

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

أي تطبيق فيه LLM بيشتغل على knowledge base ثابت بيدفع نفس التكلفة مرتين، عشرات المرات في اليوم. تخيّل chatbot دعم فني عربي بيشتغل على knowledge base فيه 22,000 token (دليل المنتج، سياسات الإرجاع، الأسئلة الشائعة، 12 مثال محادثة سابقة). كل سؤال جديد من العميل بيرسل نفس الـ knowledge base + السؤال الجديد.

على Claude Sonnet 4.6 بسعر $3 لكل مليون input token، الـ 22K دول بياخدوا $0.066 لكل طلب. لو عندك 1,000 طلب يومياً، التكلفة بتطلع $66 يومياً = $1,980 شهرياً، 96% منهم بتدفع تكلفة نفس النص. ده هدر مباشر، مش "تكلفة تشغيل".

مثال للتقريب: موظف الاستقبال الجديد كل دقيقة

تخيّل إنك بتفتح شركة، وكل شوية بييجي عميل جديد ومعاه نفس السؤال "إيه شروط الإرجاع؟". الموظف الكفء بيقرأ دليل السياسات مرة واحدة الصبح، بيحفظه، وبيرد على كل عميل في ثانيتين. لكن لو الموظف غبي وقاعد يقرأ الدليل من الأول مع كل سؤال، أنت بتدفع 4 دقايق ضايعة كل مرة + بتخسر العميل اللي زهق من الانتظار.

Prompt Caching بيخلّي Claude يعمل اللي عمله الموظف الكفء: بيحفظ الجزء الثابت من الـ prompt في cache سريع على الـ infrastructure بتاع Anthropic، ولما نفس النص ييجي تاني خلال 5 دقايق، Claude بيقرأه من الـ cache بـ 10% من السعر و85% أقل latency. الجزء المتغيّر بس (سؤال العميل الجديد) هو اللي بيتعامل معاه من جديد.

التعريف العلمي: إيه اللي بيحصل تحت الـ hood

Prompt Caching هو آلية بتسمح لـ Claude بحفظ جزء من الـ context window في ephemeral cache على infrastructure Anthropic. الـ cache بيُربط بـ deterministic hash للـ token sequence من بداية الـ prompt لحد آخر block فيه `cache_control`. أي request جاي بنفس الـ prefix بالظبط بيلاقي الـ KV cache (مصفوفات الـ Key و الـ Value من attention layers) جاهزة محسوبة، فبيوفّر مرحلة الـ prefill الحسابية اللي بتاخد 90% من الزمن في prompts الطويلة.

التكلفة على Sonnet 4.6 بسعر input عادي $3/M token:

• Cache write (أول مرة بس): 1.25× السعر العادي = $3.75/M لمدة 5 دقايق، أو 2× = $6/M لمدة ساعة
• Cache read (أي طلب بعد كده على نفس الـ prefix): 0.1× السعر العادي = $0.30/M token
• الحد الأدنى للـ cache: 1,024 token لـ Sonnet و Opus، 2,048 token لـ Haiku — أقل من كده الـ caching بيتجاهل بالكامل
• الـ TTL الافتراضي: 5 دقايق من آخر cache hit. كل hit بيـ reset الـ timer

المصدر: Anthropic Prompt Caching Documentation (platform.claude.com) و pricing page الرسمي.

التطبيق العملي: سطر واحد بيغيّر كل حاجة

كل اللي محتاجه هو إضافة object صغير اسمه `cache_control` على آخر content block عايز تكاشه. الـ Anthropic SDK Python (0.49+) بيدعمه natively:

from anthropic import Anthropic

client = Anthropic()

# الجزء الثابت — knowledge base كامل
KNOWLEDGE_BASE = open("kb.txt").read()  # 22,000 token تقريباً

def ask(user_question: str):
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": KNOWLEDGE_BASE,
                "cache_control": {"type": "ephemeral"}  # ← السطر المهم
            }
        ],
        messages=[
            {"role": "user", "content": user_question}
        ]
    )

    u = response.usage
    print(f"cache_creation_input_tokens: {u.cache_creation_input_tokens}")
    print(f"cache_read_input_tokens:     {u.cache_read_input_tokens}")
    print(f"input_tokens (الجديد فقط):    {u.input_tokens}")
    print(f"output_tokens:               {u.output_tokens}")

    return response.content[0].text

# أول طلب: بيكتب الـ cache (1.25x cost)
ask("إيه سياسة الإرجاع لو منتج معيب؟")
# cache_creation_input_tokens: 22000
# cache_read_input_tokens:     0
# input_tokens:                14

# تاني طلب خلال 5 دقايق: بيقرأ من الـ cache (0.1x cost)
ask("إزاي أتابع شحنتي؟")
# cache_creation_input_tokens: 0
# cache_read_input_tokens:     22000  ← هنا الـ 90% توفير
# input_tokens:                12

السطر اللي بيعمل الـ caching هو حرفياً `"cache_control": {"type": "ephemeral"}`. لو شغلت السكربت ده وشفت `cache_read_input_tokens > 0` في الطلب التاني، انت بتدفع 10% بدل 100% على الجزء ده.

الأرقام المقاسة: chatbot دعم فني في fintech عربي

طبّقنا الـ caching على chatbot في شركة fintech مصرية بـ 1,240 طلب يومياً على Sonnet 4.6، knowledge base بـ 21,800 token (شامل سياسات + 14 سيناريو دعم + 18 سؤال شائع). البيانات من 30 يوم قبل و30 يوم بعد التفعيل، نفس الـ workload الفعلي:

• تكلفة الطلب الواحد: من $0.0654 لـ $0.0072 — توفير 89%
• تكلفة اليوم: من $81.10 لـ $9.34
• تكلفة الشهر: من $2,433 لـ $280 — وفّرنا $2,153 شهرياً ($25,836 سنوياً)
• TTFT (Time To First Token) P50: من 1,840ms لـ 280ms — تحسّن 85%
• الـ end-to-end latency للمستخدم: من 4.2 ثانية لـ 1.1 ثانية
• cache hit rate: 94.6% (الـ 5.4% الباقية كانوا أول طلب في النهار أو بعد فترة هدوء أكتر من 5 دقايق)

الـ TTFT اتنزّل لأن مرحلة الـ prefill computation اختصرت من معالجة 22K token لـ ~14 token بس. ده مش بس وفّر فلوس — رفع NPS بـ 11 نقطة في شهر.

الـ Trade-offs الخفية اللي محدّش بيقولك عليها

الـ caching مش مجاني ومش بدون أعطاب. أربع نقاط لازم تعرفها قبل ما تـ deploy:

1. الـ TTL 5 دقايق ممكن يفاجئك: لو الـ idle period بين الطلبات أكتر من 5 دقايق، الـ cache بيتمسح وبتدفع write cost (1.25x) تاني من الأول. الحل: استخدم `"cache_control": {"type": "ephemeral", "ttl": "1h"}` بس السعر يبقى 2x للـ write. اشتري الـ 1h بس لو متأكد إن في على الأقل 2 cache reads في الساعة، وإلا بتخسر فلوس بدل ما توفر. حسبة الـ break-even: 2x write = read_rate × hits × 0.1x → hits ≥ 20 لتوفر vs الـ standard.

2. الحد الأدنى 1,024 token: لو الـ system prompt أقل من 1,024 token على Sonnet (أو 2,048 على Haiku)، الـ caching بيتجاهل بالكامل وبتدفع السعر العادي بدون warning. متضيّعش وقت تحط `cache_control` على prompts قصيرة، مش هيشتغل. اعمل count تقريبي قبل ما تبدأ.

3. ترتيب الـ blocks بيحدد كل حاجة: الـ cache hash بيتحسب من بداية الـ prompt لحد آخر `cache_control`. لو حطيت متغيّر زي اسم المستخدم أو timestamp قبل الـ knowledge base، الـ hash بيتغيّر مع كل طلب والـ cache بيتكسر. الترتيب الصح ثابت: system rules ثابتة → knowledge base ثابت → cache_control marker → ثم بعدها أي محتوى متغيّر في messages.

4. الـ Cache مش shared بين API keys: كل key له namespace منفصل. لو team من 5 مطورين بيستخدموا نفس الـ system prompt من 5 keys مختلفة، عندك 5 caches منفصلة و5 write costs. للـ production استخدم key واحد مشترك بيمر على gateway داخلي، مش keys فردية.

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

• الـ prompt قصير: أقل من 1,024 token على Sonnet — مفيش caching يحصل أصلاً، الـ flag بيتجاهل
• كل طلب context مختلف: RAG بيـ retrieve chunks مختلفة لكل سؤال — الـ cache هيتكسر كل مرة وبتدفع write cost بدل ما توفر. الحل: كاش بس الـ system prompt الثابت، مش الـ retrieved chunks
• frequency منخفض: أقل من طلب كل 5 دقايق على نفس الـ prefix — الـ cache بيـ expire قبل الطلب التاني وبتدفع write cost كل مرة
• Batch API: الـ Message Batches API ما بيدعمش caching حالياً. لو شغلك batch، استخدم real-time messages أو استنى دعم batch caching
• بيانات حساسة بـ compliance صارمة: الـ cache بيتخزّن على infrastructure Anthropic لمدة 5 دقايق على الأقل. لو compliance بيمنع أي residency للبيانات الحساسة، اقرأ Data Usage Policy الرسمية قبل ما تفعّل

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

افتح أكبر system prompt في مشروعك الحالي دلوقتي. عدّ tokens بـ client.messages.count_tokens(...). لو طلع أكتر من 1,024 وبيتكرر أكتر من طلب كل 5 دقايق، حط "cache_control": {"type": "ephemeral"} على آخر block فيه، اطبع response.usage بعد 3 طلبات متتالية. لو cache_read_input_tokens ظهر في الطلب التالت — انت بتدفع 10% من التكلفة الأصلية على الجزء ده. ابعتلي الأرقام قبل وبعد، وهنشوف إذا كان الوقت مناسب تنقل لـ 1h TTL ولا لا.

المصادر

• Anthropic — Prompt Caching Official Docs (cache_control syntax, TTL, minimum tokens)
• Anthropic — Pricing Page (Sonnet 4.6 input/cache write/cache read rates)
• Anthropic — Prompt Caching Launch Announcement (1.25x write / 0.1x read cost structure)
• AWS Bedrock — Prompt Caching for Claude Models (cross-platform behavior)
• تقرير داخلي من شركة fintech عربية (1,240 طلب/يوم على Sonnet 4.6، 30 يوم قبل/بعد) — الأرقام موثّقة في dashboard الـ usage الرسمي للحساب