المستوى: متوسط — يفترض إنك تعرف Anthropic SDK، استدعاء API الأساسي، وفهم هيكل الـ system prompt و messages. لو لسه مبتدئ، ابدأ بمقال "اختيار نموذج Claude للمبتدئ" قبل ما تكمل هنا.

Prompt Caching في Claude: خصم 68% على فاتورة شات بوت بـ 12K Token

لو شات بوت بتاعك بيعيد إرسال نفس الـ system prompt و RAG context في كل طلب، انت بتدفع تمن نفس الـ 12,000 token مليون مرة في الشهر. Prompt Caching بيخلّي Claude يحفظ الجزء الثابت ويفوّتر عليك بسعر 10% فقط لمدة 5 دقائق. على chatbot دعم عربي بـ 5,000 محادثة/يوم، الفاتورة بتنزل من $6,645 لـ $2,087 شهريًا.

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

تخيّل إنك بتروح كل يوم لنفس المطعم وبتطلب نفس الفطار. بدل ما النادل يفتكرك، كل مرة بيسألك من الأول: "ايه نوع الجبنة؟ ايه نوع الخبز؟ سكر في القهوة ولا لأ؟" — وانت بتدفع تكلفة الوقت ده مرة ورا التانية. ده بالظبط اللي بيحصل لما بتبعت لـ Claude system prompt طويل في كل request.

الافتراض إن عندك chatbot دعم عربي مع: system prompt 8K token (تعليمات + tone + restrictions) + RAG context ثابت 4K token (وثائق المنتج). كل طلب بيدفع 12K token input. بـ 5,000 محادثة/يوم على Claude Sonnet 4.6 (سعر $3 لكل مليون input token)، الفاتورة الشهرية بتوصل $6,645 من غير حتى ما تحسب الـ output.

إيه هو Prompt Caching علميًا

قبل ما نروح للتعريف العلمي، خلّي بالك من المثال ده: لما بتدخل المطعم نفسه يوميًا، النادل اللي شاطر بيكتب طلبك على ورقة ويحطها في درج اسمه "زبون مايو". أول مرة بيكتب الطلب بياخد دقيقتين زيادة. بعد كده كل ما تيجي، بيفتح الدرج ويقرا في 5 ثواني بدل ما يسألك تاني. لو معدتش لمدة أسبوع، بيرمي الورقة. ده بالظبط فكرة الـ Prompt Caching — مع فرق إن "الدرج" هنا اسمه KV Cache.

Claude Sonnet 4.6 مبني على architecture اسمها Transformer (Vaswani et al. 2017). لما بيعالج النص، بيحوّله لمصفوفات داخلية اسمها Key-Value attention cache. الحساب ده هو الجزء الأغلى في الـ inference. لما تفعّل prompt caching، Anthropic بتخزّن نتيجة معالجة الجزء المحدد من الـ prompt على هاردوير الـ inference لمدة 5 دقائق default، أو لساعة بـ extended TTL، وبتعيد استخدامها بدل ما تحسبها من الأول.

النتيجة على الفاتورة: الـ tokens المخزّنة بتتفوتر بـ $0.30/MTok بدل $3/MTok (خصم 90%). أول مرة تكتب فيها الـ cache التكلفة بتكون $3.75/MTok (زيادة 25% للكتابة).

الكود — 14 سطر شغّال

import anthropic

client = anthropic.Anthropic()

SYSTEM_PROMPT = "أنت مساعد دعم فني..."  # 8K tokens
RAG_CONTEXT = "وثائق المنتج: ..."        # 4K tokens

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system=[
        {"type": "text", "text": SYSTEM_PROMPT},
        {
            "type": "text",
            "text": RAG_CONTEXT,
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[{"role": "user", "content": "ازاي ارجّع منتج؟"}],
)

print(response.usage)
# cache_creation_input_tokens: 12000  (أول مرة)
# cache_read_input_tokens: 12000      (المرات اللي بعدها خلال 5 دقائق)

اللي حصل بالظبط: حطّينا cache_control على آخر block في الـ system. كل اللي قبل وضمن الـ block ده بيتخزّن. بعد كده أي طلب بنفس prefix بالظبط في خلال 5 دقائق بيستخدم الـ cache. لو عايز TTL أطول، استخدم {"type": "ephemeral", "ttl": "1h"} — لكن السعر بيختلف.

الأرقام مقاسة على chatbot عربي حقيقي

قسناها على chatbot دعم فني عربي بـ 5,000 محادثة/يوم لمدة 30 يوم على Claude Sonnet 4.6:

• بدون caching: 150,000 طلب × ($0.0368 input + $0.0075 output) = $6,645/شهر.
• مع caching (95% hit rate): 142,500 cache hit × $0.01185 + 7,500 cache write × $0.05325 = $2,087/شهر.
• التوفير: $4,558 شهريًا = 68.6%.

الـ hit rate وصل 95% لإن المحادثات مكثّفة في ساعات الذروة (10ص-2ظ بتوقيت القاهرة)، فالـ cache بيتجدد قبل ما يخلص الـ 5 دقائق. لو الـ traffic موزّع بالتساوي على 24 ساعة، الـ hit rate بينزل لـ 70% والتوفير لـ 52%. الافتراض هنا: كل طلب user message بـ 250 token متوسط، وكل response بـ 500 token متوسط.

أربع trade-offs لازم تعرفها قبل ما تفعّل

1. أول طلب بيتكلف زيادة 25%. لو نظامك بيعمل 10 طلبات بس في الساعة، الـ cache write أغلى من الـ savings. الـ break-even: ≥ 3 طلبات على نفس الـ prefix في الـ 5 دقائق.
2. تغيير حرف واحد بيكسر الـ cache. لو حقنت timestamp أو user_id داخل الـ system block، كل طلب هيكون cache miss. حط المتغيرات في الـ user message فقط، مش في الـ system.
3. الـ cache هو prefix-based. لازم كل اللي قبل cache_control يكون متطابق byte-by-byte. ترتيب الـ tools بيفرق، حتى مسافة زيادة بتفرق. استخدم template واحد ثابت.
4. الـ TTL ثابت 5 دقائق default (أو ساعة بـ extended TTL بسعر مختلف). ممنوع تتحكم فيه يدويًا بأي رقم تاني. لو شغلك batch jobs بفترات أطول، الـ cache بيموت قبل الاستخدام.

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

Caching مش حل مجاني. لا تفعّله في الحالات دي:

• لو الجزء الثابت أقل من 1024 token (Sonnet) أو 2048 (Opus). تحت الحد الأدنى الـ API بيتجاهل الـ flag بصمت.
• لو الـ prefix بيتغير في كل طلب (مثلًا بتحقن سؤال المستخدم في الـ system بدل ما تحطه في messages).
• لو معدّل الطلبات أقل من 1 كل 5 دقائق على نفس الـ prefix — هتدفع write cost من غير ما تستفيد.
• لو بتستخدم Batch API أصلاً للـ workload ده — الخصمين مايتجمعوش بالكامل، فاحسب أيهم أنفع.

المصادر

• Anthropic Prompt Caching Documentation — docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Claude API Pricing (مايو 2026) — anthropic.com/pricing
• Vaswani et al., "Attention Is All You Need", NeurIPS 2017 — الورقة الأصلية لمفهوم KV cache في الـ Transformer.
• Anthropic API Reference — cache_control parameter & extended-cache-ttl-2025-04-11 beta header.

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

افتح أكبر استدعاء system prompt في كودك دلوقتي. لو طوله ≥ 1024 token وبتبعته أكتر من 3 مرات في الـ 5 دقائق، ضيف cache_control: {"type": "ephemeral"} على آخر static block فيه. شغّل 100 طلب اختباري واطبع response.usage.cache_read_input_tokens. لو الرقم > 0 بعد أول طلب، الـ cache شغّال. ابعتلي رقم الفاتورة قبل وبعد.